diff options
| author | Yuriy Andamasov <yuriy@vyos.io> | 2026-05-06 20:11:13 +0300 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2026-05-06 20:11:13 +0300 |
| commit | ab5359702db9ba94fa27d770af440a20cf95a41b (patch) | |
| tree | 22b30d717e61a573a3712efec8a60f3e6b409d97 /docs | |
| parent | c784d8880325f96423fdd2c558750cac4313a56e (diff) | |
| parent | 88957530a3e174bfc61e8358cb2b28fd8f1fbbb6 (diff) | |
| download | vyos-documentation-ab5359702db9ba94fa27d770af440a20cf95a41b.tar.gz vyos-documentation-ab5359702db9ba94fa27d770af440a20cf95a41b.zip | |
Merge pull request #1898 from vyos/fix/myst-import-sagitta-v2
feat: bundle MyST migration + swap mechanism for sagitta (replaces #1886)
Diffstat (limited to 'docs')
659 files changed, 64741 insertions, 341 deletions
diff --git a/docs/_include/interface-address-with-dhcp.txt b/docs/_include/interface-address-with-dhcp.txt index d454d051..101a4e6d 100644 --- a/docs/_include/interface-address-with-dhcp.txt +++ b/docs/_include/interface-address-with-dhcp.txt @@ -1,4 +1,7 @@ -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} address <address | dhcp | dhcpv6> @@ -11,14 +14,15 @@ * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 server on this segment. - .. note:: When using DHCP to retrieve IPv4 address and if local - customizations are needed, they should be possible using the enter and - exit hooks provided. The hook dirs are: - - * ``/config/scripts/dhcp-client/pre-hooks.d/`` - * ``/config/scripts/dhcp-client/post-hooks.d/`` + :::{note} + When using DHCP to retrieve IPv4 address and if local + customizations are needed, they should be possible using the enter and + exit hooks provided. The hook dirs are: + * ``/config/scripts/dhcp-client/pre-hooks.d/`` + * ``/config/scripts/dhcp-client/post-hooks.d/`` + ::: Example: .. code-block:: none diff --git a/docs/_include/interface-address.txt b/docs/_include/interface-address.txt index 00a9ec09..90667dde 100644 --- a/docs/_include/interface-address.txt +++ b/docs/_include/interface-address.txt @@ -1,4 +1,6 @@ -.. cfgcmd:: set interfaces {{ var0 }} <interface> address <address> +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> address \<address\> + +:::: Configure interface `<interface>` with one or more interface addresses. diff --git a/docs/_include/interface-common-with-dhcp.txt b/docs/_include/interface-common-with-dhcp.txt index 47b4796f..393706f1 100644 --- a/docs/_include/interface-common-with-dhcp.txt +++ b/docs/_include/interface-common-with-dhcp.txt @@ -1,21 +1,31 @@ -.. cmdinclude:: /_include/interface-address-with-dhcp.txt +```{cmdincludemd} /_include/interface-address-with-dhcp.txt +``` + :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: /_include/interface-common.txt +```{cmdincludemd} /_include/interface-common.txt +``` + :var0: {{ var0 }} :var1: {{ var1 }} **DHCP(v6)** -.. cmdinclude:: /_include/interface-dhcp-options.txt +```{cmdincludemd} /_include/interface-dhcp-options.txt +``` + :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: /_include/interface-dhcpv6-options.txt +```{cmdincludemd} /_include/interface-dhcpv6-options.txt +``` + :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: /_include/interface-dhcpv6-prefix-delegation.txt +```{cmdincludemd} /_include/interface-dhcpv6-prefix-delegation.txt +``` + :var0: {{ var0 }} :var1: {{ var1 }} diff --git a/docs/_include/interface-common-without-dhcp.txt b/docs/_include/interface-common-without-dhcp.txt index 73d39dd0..260653e1 100644 --- a/docs/_include/interface-common-without-dhcp.txt +++ b/docs/_include/interface-common-without-dhcp.txt @@ -1,7 +1,11 @@ -.. cmdinclude:: /_include/interface-address.txt +```{cmdincludemd} /_include/interface-address.txt +``` + :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: /_include/interface-common.txt +```{cmdincludemd} /_include/interface-common.txt +``` + :var0: {{ var0 }} :var1: {{ var1 }} diff --git a/docs/_include/interface-common-without-mac.txt b/docs/_include/interface-common-without-mac.txt index cc01db12..4803d4ca 100644 --- a/docs/_include/interface-common-without-mac.txt +++ b/docs/_include/interface-common-without-mac.txt @@ -1,31 +1,47 @@ -.. cmdinclude:: /_include/interface-description.txt +```{cmdincludemd} /_include/interface-description.txt +``` + :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: /_include/interface-disable.txt +```{cmdincludemd} /_include/interface-disable.txt +``` + :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: /_include/interface-disable-flow-control.txt +```{cmdincludemd} /_include/interface-disable-flow-control.txt +``` + :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: /_include/interface-disable-link-detect.txt +```{cmdincludemd} /_include/interface-disable-link-detect.txt +``` + :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: /_include/interface-mtu.txt +```{cmdincludemd} /_include/interface-mtu.txt +``` + :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: /_include/interface-ip.txt +```{cmdincludemd} /_include/interface-ip.txt +``` + :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: /_include/interface-ipv6.txt +```{cmdincludemd} /_include/interface-ipv6.txt +``` + :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: /_include/interface-vrf.txt +```{cmdincludemd} /_include/interface-vrf.txt +``` + :var0: {{ var0 }} :var1: {{ var1 }} diff --git a/docs/_include/interface-common.txt b/docs/_include/interface-common.txt index 5a997482..45634cd8 100644 --- a/docs/_include/interface-common.txt +++ b/docs/_include/interface-common.txt @@ -1,35 +1,53 @@ -.. cmdinclude:: /_include/interface-description.txt +```{cmdincludemd} /_include/interface-description.txt +``` + :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: /_include/interface-disable.txt +```{cmdincludemd} /_include/interface-disable.txt +``` + :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: /_include/interface-disable-flow-control.txt +```{cmdincludemd} /_include/interface-disable-flow-control.txt +``` + :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: /_include/interface-disable-link-detect.txt +```{cmdincludemd} /_include/interface-disable-link-detect.txt +``` + :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: /_include/interface-mac.txt +```{cmdincludemd} /_include/interface-mac.txt +``` + :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: /_include/interface-mtu.txt +```{cmdincludemd} /_include/interface-mtu.txt +``` + :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: /_include/interface-ip.txt +```{cmdincludemd} /_include/interface-ip.txt +``` + :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: /_include/interface-ipv6.txt +```{cmdincludemd} /_include/interface-ipv6.txt +``` + :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: /_include/interface-vrf.txt +```{cmdincludemd} /_include/interface-vrf.txt +``` + :var0: {{ var0 }} :var1: {{ var1 }} diff --git a/docs/_include/interface-description.txt b/docs/_include/interface-description.txt index 064d9559..ac3cbbb0 100644 --- a/docs/_include/interface-description.txt +++ b/docs/_include/interface-description.txt @@ -1,4 +1,7 @@ -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} description <description> Set a human readable, descriptive alias for this connection. Alias is used by diff --git a/docs/_include/interface-dhcp-options.txt b/docs/_include/interface-dhcp-options.txt index 27a80acd..1b25b9cb 100644 --- a/docs/_include/interface-dhcp-options.txt +++ b/docs/_include/interface-dhcp-options.txt @@ -1,4 +1,7 @@ -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} dhcp-options client-id <description> :rfc:`2131` states: The client MAY choose to explicitly provide the identifier @@ -13,7 +16,10 @@ set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcp-options client-id 'foo-bar' -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} dhcp-options host-name <hostname> Instead of sending the real system hostname to the DHCP server, overwrite the @@ -25,7 +31,10 @@ set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcp-options host-name 'VyOS' -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} dhcp-options vendor-class-id <vendor-id> The vendor-class-id option can be used to request a specific class of vendor @@ -37,7 +46,10 @@ set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcp-options vendor-class-id 'VyOS' -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} dhcp-options no-default-route Only request an address from the DHCP server but do not request a default @@ -49,7 +61,10 @@ set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcp-options no-default-route -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} dhcp-options default-route-distance <distance> Set the distance for the default gateway sent by the DHCP server. @@ -60,7 +75,10 @@ set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcp-options default-route-distance 220 -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} dhcp-options reject <address> Reject DHCP leases from a given address or range. diff --git a/docs/_include/interface-dhcpv6-options.txt b/docs/_include/interface-dhcpv6-options.txt index a2361e11..4f6b9617 100644 --- a/docs/_include/interface-dhcpv6-options.txt +++ b/docs/_include/interface-dhcpv6-options.txt @@ -1,4 +1,7 @@ -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} dhcpv6-options duid <duid> The DHCP unique identifier (DUID) is used by a client to get an IP address @@ -11,7 +14,10 @@ set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} duid '0e:00:00:01:00:01:27:71:db:f0:00:50:56:bf:c5:6d' -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} dhcpv6-options no-release When no-release is specified, dhcp6c will send a release message on client @@ -22,7 +28,10 @@ set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcpv6-options no-release -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} dhcpv6-options parameters-only This statement specifies dhcp6c to only exchange informational configuration @@ -34,7 +43,10 @@ set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcpv6-options parameters-only -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} dhcpv6-options rapid-commit When rapid-commit is specified, dhcp6c will include a rapid-commit option in @@ -44,7 +56,10 @@ set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcpv6-options rapid-commit -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} dhcpv6-options temporary Request only a temporary address and not form an IA_NA (Identity Association diff --git a/docs/_include/interface-dhcpv6-prefix-delegation.txt b/docs/_include/interface-dhcpv6-prefix-delegation.txt index c6564092..1974ade0 100644 --- a/docs/_include/interface-dhcpv6-prefix-delegation.txt +++ b/docs/_include/interface-dhcpv6-prefix-delegation.txt @@ -4,7 +4,10 @@ VyOS 1.3 (equuleus) supports DHCPv6-PD (:rfc:`3633`). DHCPv6 Prefix Delegation is supported by most ISPs who provide native IPv6 for consumers on fixed networks. -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} dhcpv6-options pd <id> length <length> Some ISPs by default only delegate a /64 prefix. To request for a specific @@ -20,7 +23,10 @@ networks. set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcpv6-options pd 0 length 56 -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} dhcpv6-options pd <id> interface <delegatee> address <address> @@ -44,7 +50,10 @@ networks. set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcpv6-options pd 0 interface eth8 address 65534 -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} dhcpv6-options pd <id> interface <delegatee> sla-id <id> Specify the identifier value of the site-level aggregator (SLA) on the diff --git a/docs/_include/interface-disable-flow-control.txt b/docs/_include/interface-disable-flow-control.txt index 347f1145..88328c18 100644 --- a/docs/_include/interface-disable-flow-control.txt +++ b/docs/_include/interface-disable-flow-control.txt @@ -1,5 +1,7 @@ -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} - disable-flow-control +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +disable-flow-control +:::: Ethernet flow control is a mechanism for temporarily stopping the transmission of data on Ethernet family computer networks. The goal of this mechanism is to diff --git a/docs/_include/interface-disable-link-detect.txt b/docs/_include/interface-disable-link-detect.txt index 1a766715..a8add7f7 100644 --- a/docs/_include/interface-disable-link-detect.txt +++ b/docs/_include/interface-disable-link-detect.txt @@ -1,4 +1,7 @@ -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} disable-link-detect Use this command to direct an interface to not detect any physical state diff --git a/docs/_include/interface-disable.txt b/docs/_include/interface-disable.txt index 774c1cdd..8ceea73b 100644 --- a/docs/_include/interface-disable.txt +++ b/docs/_include/interface-disable.txt @@ -1,4 +1,7 @@ -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} disable Disable given `<interface>`. It will be placed in administratively down diff --git a/docs/_include/interface-eapol.txt b/docs/_include/interface-eapol.txt index 640fc6e3..19edfaf6 100644 --- a/docs/_include/interface-eapol.txt +++ b/docs/_include/interface-eapol.txt @@ -6,7 +6,10 @@ resources. EAPoL comes with an identify option. We automatically use the interface MAC address as identity parameter. -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} eapol ca-certificate <name> Set the name of the SSL :abbr:`CA (Certificate Authority)` PKI entry used for @@ -23,7 +26,10 @@ address as identity parameter. set pki ca eapol-server-root-ca <Server root CA contents> set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} eapol ca-certificate eapol-server-intermediate-ca -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} eapol certificate <name> Set the name of the x509 client keypair used to authenticate against the diff --git a/docs/_include/interface-evpn-uplink.txt b/docs/_include/interface-evpn-uplink.txt index 3495361d..ff319799 100644 --- a/docs/_include/interface-evpn-uplink.txt +++ b/docs/_include/interface-evpn-uplink.txt @@ -1,4 +1,6 @@ -.. cfgcmd:: set interfaces {{ var0 }} <interface> evpn uplink +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> evpn uplink + +:::: When all the underlay links go down the PE no longer has access to the VxLAN +overlay. To prevent blackholing of traffic the diff --git a/docs/_include/interface-ip.txt b/docs/_include/interface-ip.txt index 6359aceb..2b8e9a00 100644 --- a/docs/_include/interface-ip.txt +++ b/docs/_include/interface-ip.txt @@ -1,4 +1,7 @@ -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} ip adjust-mss <mss | clamp-mss-to-pmtu> As Internet wide PMTU discovery rarely works, we sometimes need to clamp our @@ -6,16 +9,23 @@ 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'. - .. note:: This command was introduced in VyOS 1.4 - it was previously called: - ``set firewall options interface <name> adjust-mss <value>`` + :::{note} + This command was introduced in VyOS 1.4 - it was previously called: - .. hint:: MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting in - 1452 bytes on a 1492 byte MTU. + ``set firewall options interface <name> adjust-mss <value>`` + ::: + :::{hint} + MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting in + 1452 bytes on a 1492 byte MTU. + ::: Instead of a numerical MSS value `clamp-mss-to-pmtu` can be used to automatically set the proper value. -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} ip arp-cache-timeout Once a neighbor has been found, the entry is considered to be valid for at @@ -30,7 +40,10 @@ set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ip arp-cache-timeout 180 -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} ip disable-arp-filter If set the kernel can respond to arp requests with addresses from other @@ -53,7 +66,10 @@ set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ip disable-arp-filter -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} ip disable-forwarding Configure interface-specific Host/Router behaviour. If set, the interface will @@ -63,7 +79,10 @@ set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ip disable-forwarding -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} ip enable-directed-broadcast Define different modes for IP directed broadcast forwarding as described in @@ -79,7 +98,10 @@ set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ip enable-directed-broadcast -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} ip enable-arp-accept Define behavior for gratuitous ARP frames who's IP is not already present in @@ -95,7 +117,10 @@ set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ip enable-arp-accept -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} ip enable-arp-announce Define different restriction levels for announcing the local source IP address @@ -115,7 +140,10 @@ set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ip enable-arp-announce -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} ip enable-arp-ignore Define different modes for sending replies in response to received ARP @@ -131,7 +159,10 @@ set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ip enable-arp-ignore -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} ip enable-proxy-arp Use this command to enable proxy Address Resolution Protocol (ARP) on this @@ -147,7 +178,10 @@ set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ip enable-proxy-arp -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} ip proxy-arp-pvlan Private VLAN proxy arp. Basically allow proxy arp replies back to the same @@ -159,8 +193,9 @@ possible to allow these hosts to communicate through the upstream router by proxy_arp'ing. - .. note:: Does not need to be used together with proxy_arp. - + :::{note} + Does not need to be used together with proxy_arp. + ::: This technology is known by different names: - In :rfc:`3069` it is called VLAN Aggregation @@ -171,7 +206,10 @@ - Ericsson call it MAC-Forced Forwarding (RFC Draft) -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} ip source-validation <strict | loose | disable> Enable policy for source validation by reversed path, as specified in diff --git a/docs/_include/interface-ipv6.txt b/docs/_include/interface-ipv6.txt index 0c222d80..1d3b741b 100644 --- a/docs/_include/interface-ipv6.txt +++ b/docs/_include/interface-ipv6.txt @@ -1,4 +1,7 @@ -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} ipv6 address autoconf :abbr:`SLAAC (Stateless Address Autoconfiguration)` :rfc:`4862`. IPv6 hosts @@ -9,9 +12,11 @@ its configuration parameters; routers respond to such a request with a router advertisement packet that contains Internet Layer configuration parameters. - .. note:: This method automatically disables IPv6 traffic forwarding on the - interface in question. + :::{note} + This method automatically disables IPv6 traffic forwarding on the + interface in question. + ::: Example: .. code-block:: none @@ -19,7 +24,10 @@ set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ipv6 address autoconf -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} ipv6 address eui64 <prefix> :abbr:`EUI-64 (64-Bit Extended Unique Identifier)` as specified in @@ -31,7 +39,10 @@ set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ipv6 address eui64 2001:db8:beef::/64 -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} ipv6 address no-default-link-local Do not assign a link-local IPv6 address to this interface. @@ -42,7 +53,10 @@ set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ipv6 address no-default-link-local -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} ipv6 disable-forwarding Configure interface-specific Host/Router behaviour. If set, the interface will @@ -54,7 +68,10 @@ set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ipv6 disable-forwarding -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} ipv6 adjust-mss <mss | clamp-mss-to-pmtu> As Internet wide PMTU discovery rarely works, we sometimes need to clamp our @@ -62,16 +79,23 @@ 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'. - .. note:: This command was introduced in VyOS 1.4 - it was previously called: - ``set firewall options interface <name> adjust-mss6 <value>`` + :::{note} + This command was introduced in VyOS 1.4 - it was previously called: - .. hint:: MSS value = MTU - 40 (IPv6 header) - 20 (TCP header), resulting in - 1432 bytes on a 1492 byte MTU. + ``set firewall options interface <name> adjust-mss6 <value>`` + ::: + :::{hint} + MSS value = MTU - 40 (IPv6 header) - 20 (TCP header), resulting in + 1432 bytes on a 1492 byte MTU. + ::: Instead of a numerical MSS value `clamp-mss-to-pmtu` can be used to automatically set the proper value. -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} ipv6 accept-dad <1-3> Whether to accept DAD (Duplicate Address Detection). @@ -86,7 +110,10 @@ set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ipv6 accept-dad 2 -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} ipv6 dup-addr-detect-transmits <n> The amount of Duplicate Address Detection probes to send. diff --git a/docs/_include/interface-mac.txt b/docs/_include/interface-mac.txt index 03aa6106..d81ce660 100644 --- a/docs/_include/interface-mac.txt +++ b/docs/_include/interface-mac.txt @@ -1,4 +1,7 @@ -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} mac <xx:xx:xx:xx:xx:xx> Configure user defined :abbr:`MAC (Media Access Control)` address on given diff --git a/docs/_include/interface-mirror.txt b/docs/_include/interface-mirror.txt index 66d63248..3e2a7bed 100644 --- a/docs/_include/interface-mirror.txt +++ b/docs/_include/interface-mirror.txt @@ -10,28 +10,31 @@ VyOS uses the `mirror` option to configure port mirroring. The configuration is divided into 2 different directions. Destination ports should be configured for different traffic directions. -.. cfgcmd:: set interfaces {{ var0 }} <interface> mirror - ingress <monitor-interface> - - Configure port mirroring for `interface` inbound traffic and copy the - traffic to `monitor-interface` - - Example: Mirror the inbound traffic of `{{ var1 }}` port to `{{ var2 }}` - - .. code-block:: none - - set interfaces {{ var0 }} {{ var1 }} mirror ingress {{ var2 }} - -.. cfgcmd:: set interfaces {{ var0 }} <interface> mirror egress - <monitor-interface> - - Configure port mirroring for `interface` outbound traffic and copy the - traffic to `monitor-interface` - - Example: Mirror the outbound traffic of `{{ var1 }}` port to `{{ var2 }}` - - .. code-block:: none - - set interfaces {{ var0 }} {{ var1 }} mirror egress {{ var2 }} - - +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> mirror + +ingress <monitor-interface> + +Configure port mirroring for `interface` inbound traffic and copy the +traffic to `monitor-interface` + +Example: Mirror the inbound traffic of `{{ var1 }}` port to `{{ var2 }}` + +```none + +``` + set interfaces {{ var0 }} {{ var1 }} mirror ingress {{ var2 }} +:::: +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> mirror egress + +<monitor-interface> + +Configure port mirroring for `interface` outbound traffic and copy the +traffic to `monitor-interface` + +Example: Mirror the outbound traffic of `{{ var1 }}` port to `{{ var2 }}` + +```none + +``` + set interfaces {{ var0 }} {{ var1 }} mirror egress {{ var2 }} +:::: diff --git a/docs/_include/interface-mtu.txt b/docs/_include/interface-mtu.txt index f3666179..01bf102e 100644 --- a/docs/_include/interface-mtu.txt +++ b/docs/_include/interface-mtu.txt @@ -1,4 +1,7 @@ -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} mtu <mtu> Configure :abbr:`MTU (Maximum Transmission Unit)` on given `<interface>`. It diff --git a/docs/_include/interface-per-client-thread.txt b/docs/_include/interface-per-client-thread.txt index 877be591..bc662ff5 100644 --- a/docs/_include/interface-per-client-thread.txt +++ b/docs/_include/interface-per-client-thread.txt @@ -1,4 +1,7 @@ -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} per-client-thread Provides a per-device control to enable/disable the threaded mode for diff --git a/docs/_include/interface-vlan-8021ad.txt b/docs/_include/interface-vlan-8021ad.txt index 0a1722dc..ad808880 100644 --- a/docs/_include/interface-vlan-8021ad.txt +++ b/docs/_include/interface-vlan-8021ad.txt @@ -28,126 +28,138 @@ tag is the one closer/closest to the Ethernet header, its name is S-TAG (service tag with Ethernet Type = 0x88a8). -.. cmdinclude:: /_include/interface-address-with-dhcp.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif-s - :var3: <vlan-id> - :var4: 1000 - :var5: vif-c - :var6: <vlan-id> - :var7: 20 - -.. cmdinclude:: /_include/interface-description.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif-s - :var3: <vlan-id> - :var4: 1000 - :var5: vif-c - :var6: <vlan-id> - :var7: 20 - -.. cmdinclude:: /_include/interface-disable.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif-s - :var3: <vlan-id> - :var4: 1000 - :var5: vif-c - :var6: <vlan-id> - :var7: 20 - -.. cmdinclude:: /_include/interface-disable-link-detect.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif-s - :var3: <vlan-id> - :var4: 1000 - :var5: vif-c - :var6: <vlan-id> - :var7: 20 - -.. cmdinclude:: /_include/interface-mac.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif-s - :var3: <vlan-id> - :var4: 1000 - :var5: vif-c - :var6: <vlan-id> - :var7: 20 - -.. cmdinclude:: /_include/interface-mtu.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif-s - :var3: <vlan-id> - :var4: 1000 - :var5: vif-c - :var6: <vlan-id> - :var7: 20 - -.. cmdinclude:: /_include/interface-ip.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif-s - :var3: <vlan-id> - :var4: 1000 - :var5: vif-c - :var6: <vlan-id> - :var7: 20 - -.. cmdinclude:: /_include/interface-ipv6.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif-s - :var3: <vlan-id> - :var4: 1000 - :var5: vif-c - :var6: <vlan-id> - :var7: 20 - -.. cmdinclude:: /_include/interface-vrf.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif-s - :var3: <vlan-id> - :var4: 1000 - :var5: vif-c - :var6: <vlan-id> - :var7: 20 +```{cmdincludemd} /_include/interface-address-with-dhcp.txt +:var0: {{ var0 }} +:var1: {{ var1 }} +:var2: vif-s +:var3: <vlan-id> +:var4: 1000 +:var5: vif-c +:var6: <vlan-id> +:var7: 20 +``` + +```{cmdincludemd} /_include/interface-description.txt +:var0: {{ var0 }} +:var1: {{ var1 }} +:var2: vif-s +:var3: <vlan-id> +:var4: 1000 +:var5: vif-c +:var6: <vlan-id> +:var7: 20 +``` + +```{cmdincludemd} /_include/interface-disable.txt +:var0: {{ var0 }} +:var1: {{ var1 }} +:var2: vif-s +:var3: <vlan-id> +:var4: 1000 +:var5: vif-c +:var6: <vlan-id> +:var7: 20 +``` + +```{cmdincludemd} /_include/interface-disable-link-detect.txt +:var0: {{ var0 }} +:var1: {{ var1 }} +:var2: vif-s +:var3: <vlan-id> +:var4: 1000 +:var5: vif-c +:var6: <vlan-id> +:var7: 20 +``` + +```{cmdincludemd} /_include/interface-mac.txt +:var0: {{ var0 }} +:var1: {{ var1 }} +:var2: vif-s +:var3: <vlan-id> +:var4: 1000 +:var5: vif-c +:var6: <vlan-id> +:var7: 20 +``` + +```{cmdincludemd} /_include/interface-mtu.txt +:var0: {{ var0 }} +:var1: {{ var1 }} +:var2: vif-s +:var3: <vlan-id> +:var4: 1000 +:var5: vif-c +:var6: <vlan-id> +:var7: 20 +``` + +```{cmdincludemd} /_include/interface-ip.txt +:var0: {{ var0 }} +:var1: {{ var1 }} +:var2: vif-s +:var3: <vlan-id> +:var4: 1000 +:var5: vif-c +:var6: <vlan-id> +:var7: 20 +``` + +```{cmdincludemd} /_include/interface-ipv6.txt +:var0: {{ var0 }} +:var1: {{ var1 }} +:var2: vif-s +:var3: <vlan-id> +:var4: 1000 +:var5: vif-c +:var6: <vlan-id> +:var7: 20 +``` + +```{cmdincludemd} /_include/interface-vrf.txt +:var0: {{ var0 }} +:var1: {{ var1 }} +:var2: vif-s +:var3: <vlan-id> +:var4: 1000 +:var5: vif-c +:var6: <vlan-id> +:var7: 20 +``` **DHCP(v6)** -.. cmdinclude:: /_include/interface-dhcp-options.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif-s - :var3: <vlan-id> - :var4: 1000 - :var5: vif-c - :var6: <vlan-id> - :var7: 20 - -.. cmdinclude:: /_include/interface-dhcpv6-options.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif-s - :var3: <vlan-id> - :var4: 1000 - :var5: vif-c - :var6: <vlan-id> - :var7: 20 - -.. cmdinclude:: /_include/interface-dhcpv6-prefix-delegation.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif-s - :var3: <vlan-id> - :var4: 1000 - :var5: vif-c - :var6: <vlan-id> - :var7: 20 +```{cmdincludemd} /_include/interface-dhcp-options.txt +:var0: {{ var0 }} +:var1: {{ var1 }} +:var2: vif-s +:var3: <vlan-id> +:var4: 1000 +:var5: vif-c +:var6: <vlan-id> +:var7: 20 +``` + +```{cmdincludemd} /_include/interface-dhcpv6-options.txt +:var0: {{ var0 }} +:var1: {{ var1 }} +:var2: vif-s +:var3: <vlan-id> +:var4: 1000 +:var5: vif-c +:var6: <vlan-id> +:var7: 20 +``` + +```{cmdincludemd} /_include/interface-dhcpv6-prefix-delegation.txt +:var0: {{ var0 }} +:var1: {{ var1 }} +:var2: vif-s +:var3: <vlan-id> +:var4: 1000 +:var5: vif-c +:var6: <vlan-id> +:var7: 20 +``` .. include:: /_include/common-references.txt diff --git a/docs/_include/interface-vlan-8021q.txt b/docs/_include/interface-vlan-8021q.txt index 1a527590..70e017c4 100644 --- a/docs/_include/interface-vlan-8021q.txt +++ b/docs/_include/interface-vlan-8021q.txt @@ -21,7 +21,9 @@ revisions is 802.1Q-2014 which incorporated IEEE 802.1aq 802.1q VLAN interfaces are represented as virtual sub-interfaces in VyOS. The term used for this is ``vif``. -.. cfgcmd:: set interfaces {{ var0 }} <interface> vif <vlan-id> +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> vif \<vlan-id\> + +:::: Create a new VLAN interface on interface `<interface>` using the VLAN number provided via `<vlan-id>`. @@ -29,92 +31,106 @@ term used for this is ``vif``. You can create multiple VLAN interfaces on a physical interface. The VLAN ID range is from 0 to 4094. - .. note:: Only 802.1Q-tagged packets are accepted on Ethernet vifs. - -.. cmdinclude:: /_include/interface-address-with-dhcp.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif - :var3: <vlan-id> - :var4: 10 - -.. cmdinclude:: /_include/interface-description.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif - :var3: <vlan-id> - :var4: 10 - -.. cmdinclude:: /_include/interface-disable.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif - :var3: <vlan-id> - :var4: 10 - -.. cmdinclude:: /_include/interface-disable-link-detect.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif - :var3: <vlan-id> - :var4: 10 - -.. cmdinclude:: /_include/interface-mac.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif - :var3: <vlan-id> - :var4: 10 - -.. cmdinclude:: /_include/interface-mtu.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif - :var3: <vlan-id> - :var4: 10 - -.. cmdinclude:: /_include/interface-ip.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif - :var3: <vlan-id> - :var4: 10 - -.. cmdinclude:: /_include/interface-ipv6.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif - :var3: <vlan-id> - :var4: 10 - -.. cmdinclude:: /_include/interface-vrf.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif - :var3: <vlan-id> - :var4: 10 + :::{note} + Only 802.1Q-tagged packets are accepted on Ethernet vifs. + ::: + +```{cmdincludemd} /_include/interface-address-with-dhcp.txt +:var0: {{ var0 }} +:var1: {{ var1 }} +:var2: vif +:var3: <vlan-id> +:var4: 10 +``` + +```{cmdincludemd} /_include/interface-description.txt +:var0: {{ var0 }} +:var1: {{ var1 }} +:var2: vif +:var3: <vlan-id> +:var4: 10 +``` + +```{cmdincludemd} /_include/interface-disable.txt +:var0: {{ var0 }} +:var1: {{ var1 }} +:var2: vif +:var3: <vlan-id> +:var4: 10 +``` + +```{cmdincludemd} /_include/interface-disable-link-detect.txt +:var0: {{ var0 }} +:var1: {{ var1 }} +:var2: vif +:var3: <vlan-id> +:var4: 10 +``` + +```{cmdincludemd} /_include/interface-mac.txt +:var0: {{ var0 }} +:var1: {{ var1 }} +:var2: vif +:var3: <vlan-id> +:var4: 10 +``` + +```{cmdincludemd} /_include/interface-mtu.txt +:var0: {{ var0 }} +:var1: {{ var1 }} +:var2: vif +:var3: <vlan-id> +:var4: 10 +``` + +```{cmdincludemd} /_include/interface-ip.txt +:var0: {{ var0 }} +:var1: {{ var1 }} +:var2: vif +:var3: <vlan-id> +:var4: 10 +``` + +```{cmdincludemd} /_include/interface-ipv6.txt +:var0: {{ var0 }} +:var1: {{ var1 }} +:var2: vif +:var3: <vlan-id> +:var4: 10 +``` + +```{cmdincludemd} /_include/interface-vrf.txt +:var0: {{ var0 }} +:var1: {{ var1 }} +:var2: vif +:var3: <vlan-id> +:var4: 10 +``` **DHCP(v6)** -.. cmdinclude:: /_include/interface-dhcp-options.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif - :var3: <vlan-id> - :var4: 10 - -.. cmdinclude:: /_include/interface-dhcpv6-options.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif - :var3: <vlan-id> - :var4: 10 - -.. cmdinclude:: /_include/interface-dhcpv6-prefix-delegation.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif - :var3: <vlan-id> - :var4: 10 +```{cmdincludemd} /_include/interface-dhcp-options.txt +:var0: {{ var0 }} +:var1: {{ var1 }} +:var2: vif +:var3: <vlan-id> +:var4: 10 +``` + +```{cmdincludemd} /_include/interface-dhcpv6-options.txt +:var0: {{ var0 }} +:var1: {{ var1 }} +:var2: vif +:var3: <vlan-id> +:var4: 10 +``` + +```{cmdincludemd} /_include/interface-dhcpv6-prefix-delegation.txt +:var0: {{ var0 }} +:var1: {{ var1 }} +:var2: vif +:var3: <vlan-id> +:var4: 10 +``` .. include:: /_include/common-references.txt diff --git a/docs/_include/interface-vrf.txt b/docs/_include/interface-vrf.txt index 1fa94f9f..ab98c2d3 100644 --- a/docs/_include/interface-vrf.txt +++ b/docs/_include/interface-vrf.txt @@ -1,11 +1,16 @@ -.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} +::::{cfgcmd} set interfaces {{ var0 }} \<interface\> {{ var2 }} {{ var3 }} + +:::: + {{ var5 }} {{ var6 }} vrf <vrf> Place interface in given VRF instance. - .. seealso:: There is an entire chapter about how to configure a :ref:`vrf`, - please check this for additional information. + :::{seealso} + There is an entire chapter about how to configure a :ref:`vrf`, + please check this for additional information. + ::: Example: .. code-block:: none diff --git a/docs/_include/need_improvement.txt b/docs/_include/need_improvement.txt index 1ce50685..3404c7e1 100644 --- a/docs/_include/need_improvement.txt +++ b/docs/_include/need_improvement.txt @@ -1,21 +1,8 @@ -.. raw:: latex - - \iffalse - -.. raw:: html - - <div class="admonition error"> - <p class="admonition-title">Call for Contributions</p> - +:::{error} Call for Contributions This section needs improvements, examples and explanations. Please take a look at the Contributing Guide for our :ref:`documentation`. - -.. raw:: html - - </div> - -.. raw:: latex +::: \fi
\ No newline at end of file diff --git a/docs/_static/css/DataTables-1.11.5/images/sort_asc.webp b/docs/_static/css/DataTables-1.11.5/images/sort_asc.webp Binary files differnew file mode 100644 index 00000000..eebabad0 --- /dev/null +++ b/docs/_static/css/DataTables-1.11.5/images/sort_asc.webp diff --git a/docs/_static/css/DataTables-1.11.5/images/sort_asc_disabled.webp b/docs/_static/css/DataTables-1.11.5/images/sort_asc_disabled.webp Binary files differnew file mode 100644 index 00000000..847d4f5d --- /dev/null +++ b/docs/_static/css/DataTables-1.11.5/images/sort_asc_disabled.webp diff --git a/docs/_static/css/DataTables-1.11.5/images/sort_both.webp b/docs/_static/css/DataTables-1.11.5/images/sort_both.webp Binary files differnew file mode 100644 index 00000000..1b09597a --- /dev/null +++ b/docs/_static/css/DataTables-1.11.5/images/sort_both.webp diff --git a/docs/_static/css/DataTables-1.11.5/images/sort_desc.webp b/docs/_static/css/DataTables-1.11.5/images/sort_desc.webp Binary files differnew file mode 100644 index 00000000..857789c6 --- /dev/null +++ b/docs/_static/css/DataTables-1.11.5/images/sort_desc.webp diff --git a/docs/_static/css/DataTables-1.11.5/images/sort_desc_disabled.webp b/docs/_static/css/DataTables-1.11.5/images/sort_desc_disabled.webp Binary files differnew file mode 100644 index 00000000..3368310f --- /dev/null +++ b/docs/_static/css/DataTables-1.11.5/images/sort_desc_disabled.webp diff --git a/docs/_static/images/1u_vyos_back.jpg b/docs/_static/images/1u_vyos_back.jpg Binary files differdeleted file mode 100644 index cd00c11c..00000000 --- a/docs/_static/images/1u_vyos_back.jpg +++ /dev/null diff --git a/docs/_static/images/1u_vyos_back.webp b/docs/_static/images/1u_vyos_back.webp Binary files differnew file mode 100644 index 00000000..b0dbab1d --- /dev/null +++ b/docs/_static/images/1u_vyos_back.webp diff --git a/docs/_static/images/1u_vyos_front.jpg b/docs/_static/images/1u_vyos_front.jpg Binary files differdeleted file mode 100644 index 3d135d56..00000000 --- a/docs/_static/images/1u_vyos_front.jpg +++ /dev/null diff --git a/docs/_static/images/1u_vyos_front.webp b/docs/_static/images/1u_vyos_front.webp Binary files differnew file mode 100644 index 00000000..a47e4f9e --- /dev/null +++ b/docs/_static/images/1u_vyos_front.webp diff --git a/docs/_static/images/1u_vyos_front_10ge_open_1.jpg b/docs/_static/images/1u_vyos_front_10ge_open_1.jpg Binary files differdeleted file mode 100644 index edfba5a3..00000000 --- a/docs/_static/images/1u_vyos_front_10ge_open_1.jpg +++ /dev/null diff --git a/docs/_static/images/1u_vyos_front_10ge_open_1.webp b/docs/_static/images/1u_vyos_front_10ge_open_1.webp Binary files differnew file mode 100644 index 00000000..87f53ddd --- /dev/null +++ b/docs/_static/images/1u_vyos_front_10ge_open_1.webp diff --git a/docs/_static/images/1u_vyos_front_10ge_open_2.jpg b/docs/_static/images/1u_vyos_front_10ge_open_2.jpg Binary files differdeleted file mode 100644 index 4f48a116..00000000 --- a/docs/_static/images/1u_vyos_front_10ge_open_2.jpg +++ /dev/null diff --git a/docs/_static/images/1u_vyos_front_10ge_open_2.webp b/docs/_static/images/1u_vyos_front_10ge_open_2.webp Binary files differnew file mode 100644 index 00000000..1fe5d4ca --- /dev/null +++ b/docs/_static/images/1u_vyos_front_10ge_open_2.webp diff --git a/docs/_static/images/1u_vyos_front_10ge_open_3.jpg b/docs/_static/images/1u_vyos_front_10ge_open_3.jpg Binary files differdeleted file mode 100644 index c102b903..00000000 --- a/docs/_static/images/1u_vyos_front_10ge_open_3.jpg +++ /dev/null diff --git a/docs/_static/images/1u_vyos_front_10ge_open_3.webp b/docs/_static/images/1u_vyos_front_10ge_open_3.webp Binary files differnew file mode 100644 index 00000000..2200b448 --- /dev/null +++ b/docs/_static/images/1u_vyos_front_10ge_open_3.webp diff --git a/docs/_static/images/1u_vyos_front_10ge_open_4.jpg b/docs/_static/images/1u_vyos_front_10ge_open_4.jpg Binary files differdeleted file mode 100644 index 2f270b7e..00000000 --- a/docs/_static/images/1u_vyos_front_10ge_open_4.jpg +++ /dev/null diff --git a/docs/_static/images/1u_vyos_front_10ge_open_4.webp b/docs/_static/images/1u_vyos_front_10ge_open_4.webp Binary files differnew file mode 100644 index 00000000..fd4a43c7 --- /dev/null +++ b/docs/_static/images/1u_vyos_front_10ge_open_4.webp diff --git a/docs/_static/images/1u_vyos_front_open_1.jpg b/docs/_static/images/1u_vyos_front_open_1.jpg Binary files differdeleted file mode 100644 index d90d565e..00000000 --- a/docs/_static/images/1u_vyos_front_open_1.jpg +++ /dev/null diff --git a/docs/_static/images/1u_vyos_front_open_1.webp b/docs/_static/images/1u_vyos_front_open_1.webp Binary files differnew file mode 100644 index 00000000..00006feb --- /dev/null +++ b/docs/_static/images/1u_vyos_front_open_1.webp diff --git a/docs/_static/images/1u_vyos_front_open_2.jpg b/docs/_static/images/1u_vyos_front_open_2.jpg Binary files differdeleted file mode 100644 index 6d112463..00000000 --- a/docs/_static/images/1u_vyos_front_open_2.jpg +++ /dev/null diff --git a/docs/_static/images/1u_vyos_front_open_2.webp b/docs/_static/images/1u_vyos_front_open_2.webp Binary files differnew file mode 100644 index 00000000..ad6fa807 --- /dev/null +++ b/docs/_static/images/1u_vyos_front_open_2.webp diff --git a/docs/_static/images/1u_vyos_front_open_3.jpg b/docs/_static/images/1u_vyos_front_open_3.jpg Binary files differdeleted file mode 100644 index 198ba3ce..00000000 --- a/docs/_static/images/1u_vyos_front_open_3.jpg +++ /dev/null diff --git a/docs/_static/images/1u_vyos_front_open_3.webp b/docs/_static/images/1u_vyos_front_open_3.webp Binary files differnew file mode 100644 index 00000000..15edf863 --- /dev/null +++ b/docs/_static/images/1u_vyos_front_open_3.webp diff --git a/docs/_static/images/480px-Acrosser_ANDJ190N1_Back.jpg b/docs/_static/images/480px-Acrosser_ANDJ190N1_Back.jpg Binary files differdeleted file mode 100644 index 6441c54a..00000000 --- a/docs/_static/images/480px-Acrosser_ANDJ190N1_Back.jpg +++ /dev/null diff --git a/docs/_static/images/480px-Acrosser_ANDJ190N1_Back.webp b/docs/_static/images/480px-Acrosser_ANDJ190N1_Back.webp Binary files differnew file mode 100644 index 00000000..10c350cc --- /dev/null +++ b/docs/_static/images/480px-Acrosser_ANDJ190N1_Back.webp diff --git a/docs/_static/images/480px-Acrosser_ANDJ190N1_Front.jpg b/docs/_static/images/480px-Acrosser_ANDJ190N1_Front.jpg Binary files differdeleted file mode 100644 index 5f216aa1..00000000 --- a/docs/_static/images/480px-Acrosser_ANDJ190N1_Front.jpg +++ /dev/null diff --git a/docs/_static/images/480px-Acrosser_ANDJ190N1_Front.webp b/docs/_static/images/480px-Acrosser_ANDJ190N1_Front.webp Binary files differnew file mode 100644 index 00000000..0ea695d4 --- /dev/null +++ b/docs/_static/images/480px-Acrosser_ANDJ190N1_Front.webp diff --git a/docs/_static/images/600px-Partaker-i5.jpg b/docs/_static/images/600px-Partaker-i5.jpg Binary files differdeleted file mode 100644 index 68196d41..00000000 --- a/docs/_static/images/600px-Partaker-i5.jpg +++ /dev/null diff --git a/docs/_static/images/600px-Partaker-i5.webp b/docs/_static/images/600px-Partaker-i5.webp Binary files differnew file mode 100644 index 00000000..d68d5afa --- /dev/null +++ b/docs/_static/images/600px-Partaker-i5.webp diff --git a/docs/_static/images/ESP_AH.png b/docs/_static/images/ESP_AH.png Binary files differdeleted file mode 100644 index 6075c3f4..00000000 --- a/docs/_static/images/ESP_AH.png +++ /dev/null diff --git a/docs/_static/images/ESP_AH.webp b/docs/_static/images/ESP_AH.webp Binary files differnew file mode 100644 index 00000000..1c70082e --- /dev/null +++ b/docs/_static/images/ESP_AH.webp diff --git a/docs/_static/images/IPSec_close_action_settings.png b/docs/_static/images/IPSec_close_action_settings.png Binary files differdeleted file mode 100644 index 531643f7..00000000 --- a/docs/_static/images/IPSec_close_action_settings.png +++ /dev/null diff --git a/docs/_static/images/IPSec_close_action_settings.webp b/docs/_static/images/IPSec_close_action_settings.webp Binary files differnew file mode 100644 index 00000000..6510ba7c --- /dev/null +++ b/docs/_static/images/IPSec_close_action_settings.webp diff --git a/docs/_static/images/L3VPN_hub_and_spoke.png b/docs/_static/images/L3VPN_hub_and_spoke.png Binary files differdeleted file mode 100644 index d442cc1a..00000000 --- a/docs/_static/images/L3VPN_hub_and_spoke.png +++ /dev/null diff --git a/docs/_static/images/L3VPN_hub_and_spoke.webp b/docs/_static/images/L3VPN_hub_and_spoke.webp Binary files differnew file mode 100644 index 00000000..2f3cafcd --- /dev/null +++ b/docs/_static/images/L3VPN_hub_and_spoke.webp diff --git a/docs/_static/images/PA-ESP-group.png b/docs/_static/images/PA-ESP-group.png Binary files differdeleted file mode 100644 index c6411b66..00000000 --- a/docs/_static/images/PA-ESP-group.png +++ /dev/null diff --git a/docs/_static/images/PA-ESP-group.webp b/docs/_static/images/PA-ESP-group.webp Binary files differnew file mode 100644 index 00000000..1802c511 --- /dev/null +++ b/docs/_static/images/PA-ESP-group.webp diff --git a/docs/_static/images/PA-IKE-GW-1.png b/docs/_static/images/PA-IKE-GW-1.png Binary files differdeleted file mode 100644 index 863eeb3a..00000000 --- a/docs/_static/images/PA-IKE-GW-1.png +++ /dev/null diff --git a/docs/_static/images/PA-IKE-GW-1.webp b/docs/_static/images/PA-IKE-GW-1.webp Binary files differnew file mode 100644 index 00000000..ce0a123d --- /dev/null +++ b/docs/_static/images/PA-IKE-GW-1.webp diff --git a/docs/_static/images/PA-IKE-GW-2.png b/docs/_static/images/PA-IKE-GW-2.png Binary files differdeleted file mode 100644 index 21a16055..00000000 --- a/docs/_static/images/PA-IKE-GW-2.png +++ /dev/null diff --git a/docs/_static/images/PA-IKE-GW-2.webp b/docs/_static/images/PA-IKE-GW-2.webp Binary files differnew file mode 100644 index 00000000..5facbc1e --- /dev/null +++ b/docs/_static/images/PA-IKE-GW-2.webp diff --git a/docs/_static/images/PA-IKE-group.png b/docs/_static/images/PA-IKE-group.png Binary files differdeleted file mode 100644 index 06fd535d..00000000 --- a/docs/_static/images/PA-IKE-group.png +++ /dev/null diff --git a/docs/_static/images/PA-IKE-group.webp b/docs/_static/images/PA-IKE-group.webp Binary files differnew file mode 100644 index 00000000..f244a3fa --- /dev/null +++ b/docs/_static/images/PA-IKE-group.webp diff --git a/docs/_static/images/PA-IPsec-tunnel.png b/docs/_static/images/PA-IPsec-tunnel.png Binary files differdeleted file mode 100644 index 2f8f4cb8..00000000 --- a/docs/_static/images/PA-IPsec-tunnel.png +++ /dev/null diff --git a/docs/_static/images/PA-IPsec-tunnel.webp b/docs/_static/images/PA-IPsec-tunnel.webp Binary files differnew file mode 100644 index 00000000..f8aac9b8 --- /dev/null +++ b/docs/_static/images/PA-IPsec-tunnel.webp diff --git a/docs/_static/images/PA-tunnel-1.png b/docs/_static/images/PA-tunnel-1.png Binary files differdeleted file mode 100644 index 3c99c6c7..00000000 --- a/docs/_static/images/PA-tunnel-1.png +++ /dev/null diff --git a/docs/_static/images/PA-tunnel-1.webp b/docs/_static/images/PA-tunnel-1.webp Binary files differnew file mode 100644 index 00000000..b72c9364 --- /dev/null +++ b/docs/_static/images/PA-tunnel-1.webp diff --git a/docs/_static/images/PA-tunnel-2.png b/docs/_static/images/PA-tunnel-2.png Binary files differdeleted file mode 100644 index 6f073513..00000000 --- a/docs/_static/images/PA-tunnel-2.png +++ /dev/null diff --git a/docs/_static/images/PA-tunnel-2.webp b/docs/_static/images/PA-tunnel-2.webp Binary files differnew file mode 100644 index 00000000..8b1bfbf8 --- /dev/null +++ b/docs/_static/images/PA-tunnel-2.webp diff --git a/docs/_static/images/PA-tunnel-3.png b/docs/_static/images/PA-tunnel-3.png Binary files differdeleted file mode 100644 index ca5a94e9..00000000 --- a/docs/_static/images/PA-tunnel-3.png +++ /dev/null diff --git a/docs/_static/images/PA-tunnel-3.webp b/docs/_static/images/PA-tunnel-3.webp Binary files differnew file mode 100644 index 00000000..098c3c4d --- /dev/null +++ b/docs/_static/images/PA-tunnel-3.webp diff --git a/docs/_static/images/VyOS_Dual-Hub_DMVPN.webp b/docs/_static/images/VyOS_Dual-Hub_DMVPN.webp Binary files differnew file mode 100644 index 00000000..71f6d5e5 --- /dev/null +++ b/docs/_static/images/VyOS_Dual-Hub_DMVPN.webp diff --git a/docs/_static/images/Wan_load_balancing1.png b/docs/_static/images/Wan_load_balancing1.png Binary files differdeleted file mode 100644 index bde1edb6..00000000 --- a/docs/_static/images/Wan_load_balancing1.png +++ /dev/null diff --git a/docs/_static/images/Wan_load_balancing1.webp b/docs/_static/images/Wan_load_balancing1.webp Binary files differnew file mode 100644 index 00000000..7efb6ab7 --- /dev/null +++ b/docs/_static/images/Wan_load_balancing1.webp diff --git a/docs/_static/images/Wan_load_balancing_exclude1.png b/docs/_static/images/Wan_load_balancing_exclude1.png Binary files differdeleted file mode 100644 index 1111535d..00000000 --- a/docs/_static/images/Wan_load_balancing_exclude1.png +++ /dev/null diff --git a/docs/_static/images/Wan_load_balancing_exclude1.webp b/docs/_static/images/Wan_load_balancing_exclude1.webp Binary files differnew file mode 100644 index 00000000..cc5fc4d1 --- /dev/null +++ b/docs/_static/images/Wan_load_balancing_exclude1.webp diff --git a/docs/_static/images/ansible.webp b/docs/_static/images/ansible.webp Binary files differnew file mode 100644 index 00000000..746a46e8 --- /dev/null +++ b/docs/_static/images/ansible.webp diff --git a/docs/_static/images/apu4_desk_1.jpg b/docs/_static/images/apu4_desk_1.jpg Binary files differdeleted file mode 100644 index b7a3d08e..00000000 --- a/docs/_static/images/apu4_desk_1.jpg +++ /dev/null diff --git a/docs/_static/images/apu4_desk_1.webp b/docs/_static/images/apu4_desk_1.webp Binary files differnew file mode 100644 index 00000000..8298c3f2 --- /dev/null +++ b/docs/_static/images/apu4_desk_1.webp diff --git a/docs/_static/images/apu4_desk_2.jpg b/docs/_static/images/apu4_desk_2.jpg Binary files differdeleted file mode 100644 index fe356e1f..00000000 --- a/docs/_static/images/apu4_desk_2.jpg +++ /dev/null diff --git a/docs/_static/images/apu4_desk_2.webp b/docs/_static/images/apu4_desk_2.webp Binary files differnew file mode 100644 index 00000000..ccf54bb8 --- /dev/null +++ b/docs/_static/images/apu4_desk_2.webp diff --git a/docs/_static/images/apu4_desk_3.jpg b/docs/_static/images/apu4_desk_3.jpg Binary files differdeleted file mode 100644 index af7dc406..00000000 --- a/docs/_static/images/apu4_desk_3.jpg +++ /dev/null diff --git a/docs/_static/images/apu4_desk_3.webp b/docs/_static/images/apu4_desk_3.webp Binary files differnew file mode 100644 index 00000000..965ff112 --- /dev/null +++ b/docs/_static/images/apu4_desk_3.webp diff --git a/docs/_static/images/apu4_desk_4.jpg b/docs/_static/images/apu4_desk_4.jpg Binary files differdeleted file mode 100644 index 37251af2..00000000 --- a/docs/_static/images/apu4_desk_4.jpg +++ /dev/null diff --git a/docs/_static/images/apu4_desk_4.webp b/docs/_static/images/apu4_desk_4.webp Binary files differnew file mode 100644 index 00000000..2cbc2bd3 --- /dev/null +++ b/docs/_static/images/apu4_desk_4.webp diff --git a/docs/_static/images/apu4_rack_1.jpg b/docs/_static/images/apu4_rack_1.jpg Binary files differdeleted file mode 100644 index 3793cd39..00000000 --- a/docs/_static/images/apu4_rack_1.jpg +++ /dev/null diff --git a/docs/_static/images/apu4_rack_1.webp b/docs/_static/images/apu4_rack_1.webp Binary files differnew file mode 100644 index 00000000..c6bd9229 --- /dev/null +++ b/docs/_static/images/apu4_rack_1.webp diff --git a/docs/_static/images/apu4_rack_2.jpg b/docs/_static/images/apu4_rack_2.jpg Binary files differdeleted file mode 100644 index b8caf976..00000000 --- a/docs/_static/images/apu4_rack_2.jpg +++ /dev/null diff --git a/docs/_static/images/apu4_rack_2.webp b/docs/_static/images/apu4_rack_2.webp Binary files differnew file mode 100644 index 00000000..f2673488 --- /dev/null +++ b/docs/_static/images/apu4_rack_2.webp diff --git a/docs/_static/images/apu4_rack_3.jpg b/docs/_static/images/apu4_rack_3.jpg Binary files differdeleted file mode 100644 index 08ff633e..00000000 --- a/docs/_static/images/apu4_rack_3.jpg +++ /dev/null diff --git a/docs/_static/images/apu4_rack_3.webp b/docs/_static/images/apu4_rack_3.webp Binary files differnew file mode 100644 index 00000000..a12e7895 --- /dev/null +++ b/docs/_static/images/apu4_rack_3.webp diff --git a/docs/_static/images/apu4_rack_4.jpg b/docs/_static/images/apu4_rack_4.jpg Binary files differdeleted file mode 100644 index a88d62fe..00000000 --- a/docs/_static/images/apu4_rack_4.jpg +++ /dev/null diff --git a/docs/_static/images/apu4_rack_4.webp b/docs/_static/images/apu4_rack_4.webp Binary files differnew file mode 100644 index 00000000..a3ea439c --- /dev/null +++ b/docs/_static/images/apu4_rack_4.webp diff --git a/docs/_static/images/apu4_rack_5.jpg b/docs/_static/images/apu4_rack_5.jpg Binary files differdeleted file mode 100644 index 644b8e0a..00000000 --- a/docs/_static/images/apu4_rack_5.jpg +++ /dev/null diff --git a/docs/_static/images/apu4_rack_5.webp b/docs/_static/images/apu4_rack_5.webp Binary files differnew file mode 100644 index 00000000..8310600e --- /dev/null +++ b/docs/_static/images/apu4_rack_5.webp diff --git a/docs/_static/images/apu4_rack_vyos_print.jpg b/docs/_static/images/apu4_rack_vyos_print.jpg Binary files differdeleted file mode 100644 index a0bbaab2..00000000 --- a/docs/_static/images/apu4_rack_vyos_print.jpg +++ /dev/null diff --git a/docs/_static/images/apu4_rack_vyos_print.webp b/docs/_static/images/apu4_rack_vyos_print.webp Binary files differnew file mode 100644 index 00000000..61b14f3f --- /dev/null +++ b/docs/_static/images/apu4_rack_vyos_print.webp diff --git a/docs/_static/images/aws.png b/docs/_static/images/aws.png Binary files differdeleted file mode 100644 index c1c111bb..00000000 --- a/docs/_static/images/aws.png +++ /dev/null diff --git a/docs/_static/images/aws.webp b/docs/_static/images/aws.webp Binary files differnew file mode 100644 index 00000000..29fe0684 --- /dev/null +++ b/docs/_static/images/aws.webp diff --git a/docs/_static/images/blueprint-dmvpn.png b/docs/_static/images/blueprint-dmvpn.png Binary files differdeleted file mode 100644 index b07c190d..00000000 --- a/docs/_static/images/blueprint-dmvpn.png +++ /dev/null diff --git a/docs/_static/images/blueprint-dmvpn.webp b/docs/_static/images/blueprint-dmvpn.webp Binary files differnew file mode 100644 index 00000000..8a3c38aa --- /dev/null +++ b/docs/_static/images/blueprint-dmvpn.webp diff --git a/docs/_static/images/boot-options.png b/docs/_static/images/boot-options.png Binary files differdeleted file mode 100644 index b00350bc..00000000 --- a/docs/_static/images/boot-options.png +++ /dev/null diff --git a/docs/_static/images/boot-options.webp b/docs/_static/images/boot-options.webp Binary files differnew file mode 100644 index 00000000..9616a336 --- /dev/null +++ b/docs/_static/images/boot-options.webp diff --git a/docs/_static/images/cisco-vpn-ipsec.png b/docs/_static/images/cisco-vpn-ipsec.png Binary files differdeleted file mode 100644 index bc19e8bc..00000000 --- a/docs/_static/images/cisco-vpn-ipsec.png +++ /dev/null diff --git a/docs/_static/images/cisco-vpn-ipsec.webp b/docs/_static/images/cisco-vpn-ipsec.webp Binary files differnew file mode 100644 index 00000000..45c570f0 --- /dev/null +++ b/docs/_static/images/cisco-vpn-ipsec.webp diff --git a/docs/_static/images/cloud-aws-01.webp b/docs/_static/images/cloud-aws-01.webp Binary files differnew file mode 100644 index 00000000..94ce4b8f --- /dev/null +++ b/docs/_static/images/cloud-aws-01.webp diff --git a/docs/_static/images/cloud-aws-02.webp b/docs/_static/images/cloud-aws-02.webp Binary files differnew file mode 100644 index 00000000..ede125c1 --- /dev/null +++ b/docs/_static/images/cloud-aws-02.webp diff --git a/docs/_static/images/cloud-aws-03.webp b/docs/_static/images/cloud-aws-03.webp Binary files differnew file mode 100644 index 00000000..d2789ff1 --- /dev/null +++ b/docs/_static/images/cloud-aws-03.webp diff --git a/docs/_static/images/cloud-aws-04.webp b/docs/_static/images/cloud-aws-04.webp Binary files differnew file mode 100644 index 00000000..c42eca50 --- /dev/null +++ b/docs/_static/images/cloud-aws-04.webp diff --git a/docs/_static/images/cloud-aws-05.webp b/docs/_static/images/cloud-aws-05.webp Binary files differnew file mode 100644 index 00000000..8206cd66 --- /dev/null +++ b/docs/_static/images/cloud-aws-05.webp diff --git a/docs/_static/images/cloud-aws-06.webp b/docs/_static/images/cloud-aws-06.webp Binary files differnew file mode 100644 index 00000000..107ff785 --- /dev/null +++ b/docs/_static/images/cloud-aws-06.webp diff --git a/docs/_static/images/cloud-aws-07.webp b/docs/_static/images/cloud-aws-07.webp Binary files differnew file mode 100644 index 00000000..98dffd0b --- /dev/null +++ b/docs/_static/images/cloud-aws-07.webp diff --git a/docs/_static/images/cloud-aws-08.webp b/docs/_static/images/cloud-aws-08.webp Binary files differnew file mode 100644 index 00000000..97fd28a1 --- /dev/null +++ b/docs/_static/images/cloud-aws-08.webp diff --git a/docs/_static/images/cloud-aws-eip-01.png b/docs/_static/images/cloud-aws-eip-01.png Binary files differdeleted file mode 100755 index 6e376d63..00000000 --- a/docs/_static/images/cloud-aws-eip-01.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-eip-02.png b/docs/_static/images/cloud-aws-eip-02.png Binary files differdeleted file mode 100755 index 69bd5aa5..00000000 --- a/docs/_static/images/cloud-aws-eip-02.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-eni-01.png b/docs/_static/images/cloud-aws-eni-01.png Binary files differdeleted file mode 100755 index 5c67f4dc..00000000 --- a/docs/_static/images/cloud-aws-eni-01.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-eni-02.png b/docs/_static/images/cloud-aws-eni-02.png Binary files differdeleted file mode 100755 index 15b5b8aa..00000000 --- a/docs/_static/images/cloud-aws-eni-02.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-ha-architecture.png b/docs/_static/images/cloud-aws-ha-architecture.png Binary files differdeleted file mode 100755 index 043f28f3..00000000 --- a/docs/_static/images/cloud-aws-ha-architecture.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-igw-01.png b/docs/_static/images/cloud-aws-igw-01.png Binary files differdeleted file mode 100755 index 148c2d05..00000000 --- a/docs/_static/images/cloud-aws-igw-01.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-igw-02.png b/docs/_static/images/cloud-aws-igw-02.png Binary files differdeleted file mode 100755 index 26e6ea48..00000000 --- a/docs/_static/images/cloud-aws-igw-02.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-keypair-01.png b/docs/_static/images/cloud-aws-keypair-01.png Binary files differdeleted file mode 100644 index 2ebc9ac3..00000000 --- a/docs/_static/images/cloud-aws-keypair-01.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-keypair-02.png b/docs/_static/images/cloud-aws-keypair-02.png Binary files differdeleted file mode 100644 index 419e8168..00000000 --- a/docs/_static/images/cloud-aws-keypair-02.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-keypair-03.png b/docs/_static/images/cloud-aws-keypair-03.png Binary files differdeleted file mode 100644 index cc3f0dec..00000000 --- a/docs/_static/images/cloud-aws-keypair-03.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-keypair-04.png b/docs/_static/images/cloud-aws-keypair-04.png Binary files differdeleted file mode 100644 index 0e4b9f6d..00000000 --- a/docs/_static/images/cloud-aws-keypair-04.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-route-01.png b/docs/_static/images/cloud-aws-route-01.png Binary files differdeleted file mode 100755 index 1563c0b4..00000000 --- a/docs/_static/images/cloud-aws-route-01.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-route-02.png b/docs/_static/images/cloud-aws-route-02.png Binary files differdeleted file mode 100755 index 9ba19f1e..00000000 --- a/docs/_static/images/cloud-aws-route-02.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-route-03.png b/docs/_static/images/cloud-aws-route-03.png Binary files differdeleted file mode 100755 index 1bfef11c..00000000 --- a/docs/_static/images/cloud-aws-route-03.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-route-04.png b/docs/_static/images/cloud-aws-route-04.png Binary files differdeleted file mode 100755 index e3987ad3..00000000 --- a/docs/_static/images/cloud-aws-route-04.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-sg-01.png b/docs/_static/images/cloud-aws-sg-01.png Binary files differdeleted file mode 100755 index 77558eeb..00000000 --- a/docs/_static/images/cloud-aws-sg-01.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-sg-02.png b/docs/_static/images/cloud-aws-sg-02.png Binary files differdeleted file mode 100755 index 22351f75..00000000 --- a/docs/_static/images/cloud-aws-sg-02.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-sg-03.png b/docs/_static/images/cloud-aws-sg-03.png Binary files differdeleted file mode 100755 index 7375b681..00000000 --- a/docs/_static/images/cloud-aws-sg-03.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-sg-04.png b/docs/_static/images/cloud-aws-sg-04.png Binary files differdeleted file mode 100755 index 874feed5..00000000 --- a/docs/_static/images/cloud-aws-sg-04.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-sg-05.png b/docs/_static/images/cloud-aws-sg-05.png Binary files differdeleted file mode 100755 index 43b7b5cd..00000000 --- a/docs/_static/images/cloud-aws-sg-05.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-subnet-01.png b/docs/_static/images/cloud-aws-subnet-01.png Binary files differdeleted file mode 100755 index 05fe311c..00000000 --- a/docs/_static/images/cloud-aws-subnet-01.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-subnet-02.png b/docs/_static/images/cloud-aws-subnet-02.png Binary files differdeleted file mode 100755 index 22ebde4c..00000000 --- a/docs/_static/images/cloud-aws-subnet-02.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-subnet-03.png b/docs/_static/images/cloud-aws-subnet-03.png Binary files differdeleted file mode 100755 index f9092955..00000000 --- a/docs/_static/images/cloud-aws-subnet-03.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-to-azure.png b/docs/_static/images/cloud-aws-to-azure.png Binary files differdeleted file mode 100755 index 5fa0d7ad..00000000 --- a/docs/_static/images/cloud-aws-to-azure.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-vpc-01.png b/docs/_static/images/cloud-aws-vpc-01.png Binary files differdeleted file mode 100755 index 4a41375c..00000000 --- a/docs/_static/images/cloud-aws-vpc-01.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-vpc-02.png b/docs/_static/images/cloud-aws-vpc-02.png Binary files differdeleted file mode 100755 index bdd04f30..00000000 --- a/docs/_static/images/cloud-aws-vpc-02.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-vpc-03.png b/docs/_static/images/cloud-aws-vpc-03.png Binary files differdeleted file mode 100755 index f71fb5e5..00000000 --- a/docs/_static/images/cloud-aws-vpc-03.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-vyos-01.png b/docs/_static/images/cloud-aws-vyos-01.png Binary files differdeleted file mode 100755 index b3e70835..00000000 --- a/docs/_static/images/cloud-aws-vyos-01.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-vyos-02.png b/docs/_static/images/cloud-aws-vyos-02.png Binary files differdeleted file mode 100755 index 40957667..00000000 --- a/docs/_static/images/cloud-aws-vyos-02.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-vyos-03.png b/docs/_static/images/cloud-aws-vyos-03.png Binary files differdeleted file mode 100755 index ecd58eed..00000000 --- a/docs/_static/images/cloud-aws-vyos-03.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-vyos-04.png b/docs/_static/images/cloud-aws-vyos-04.png Binary files differdeleted file mode 100755 index e3db20db..00000000 --- a/docs/_static/images/cloud-aws-vyos-04.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-vyos-05.png b/docs/_static/images/cloud-aws-vyos-05.png Binary files differdeleted file mode 100755 index b91b5913..00000000 --- a/docs/_static/images/cloud-aws-vyos-05.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-vyos-06.png b/docs/_static/images/cloud-aws-vyos-06.png Binary files differdeleted file mode 100755 index 912cfed1..00000000 --- a/docs/_static/images/cloud-aws-vyos-06.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-vyos-07.png b/docs/_static/images/cloud-aws-vyos-07.png Binary files differdeleted file mode 100755 index ba6ad590..00000000 --- a/docs/_static/images/cloud-aws-vyos-07.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-vyos-08.png b/docs/_static/images/cloud-aws-vyos-08.png Binary files differdeleted file mode 100755 index f7d4e813..00000000 --- a/docs/_static/images/cloud-aws-vyos-08.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-vyos-09.png b/docs/_static/images/cloud-aws-vyos-09.png Binary files differdeleted file mode 100755 index 912cfed1..00000000 --- a/docs/_static/images/cloud-aws-vyos-09.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-vyos-10.png b/docs/_static/images/cloud-aws-vyos-10.png Binary files differdeleted file mode 100755 index 5912163a..00000000 --- a/docs/_static/images/cloud-aws-vyos-10.png +++ /dev/null diff --git a/docs/_static/images/cloud-aws-vyos-11.png b/docs/_static/images/cloud-aws-vyos-11.png Binary files differdeleted file mode 100755 index 28aa3346..00000000 --- a/docs/_static/images/cloud-aws-vyos-11.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-01.webp b/docs/_static/images/cloud-azure-01.webp Binary files differnew file mode 100644 index 00000000..95ce6eef --- /dev/null +++ b/docs/_static/images/cloud-azure-01.webp diff --git a/docs/_static/images/cloud-azure-02.webp b/docs/_static/images/cloud-azure-02.webp Binary files differnew file mode 100644 index 00000000..ad769a3c --- /dev/null +++ b/docs/_static/images/cloud-azure-02.webp diff --git a/docs/_static/images/cloud-azure-03.webp b/docs/_static/images/cloud-azure-03.webp Binary files differnew file mode 100644 index 00000000..018f408a --- /dev/null +++ b/docs/_static/images/cloud-azure-03.webp diff --git a/docs/_static/images/cloud-azure-04.webp b/docs/_static/images/cloud-azure-04.webp Binary files differnew file mode 100644 index 00000000..e7bf1df9 --- /dev/null +++ b/docs/_static/images/cloud-azure-04.webp diff --git a/docs/_static/images/cloud-azure-05.webp b/docs/_static/images/cloud-azure-05.webp Binary files differnew file mode 100644 index 00000000..280c58e8 --- /dev/null +++ b/docs/_static/images/cloud-azure-05.webp diff --git a/docs/_static/images/cloud-azure-06.webp b/docs/_static/images/cloud-azure-06.webp Binary files differnew file mode 100644 index 00000000..0f0b8135 --- /dev/null +++ b/docs/_static/images/cloud-azure-06.webp diff --git a/docs/_static/images/cloud-azure-ha-architecture.png b/docs/_static/images/cloud-azure-ha-architecture.png Binary files differdeleted file mode 100755 index be42e603..00000000 --- a/docs/_static/images/cloud-azure-ha-architecture.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-nic-01.png b/docs/_static/images/cloud-azure-nic-01.png Binary files differdeleted file mode 100755 index 80109a69..00000000 --- a/docs/_static/images/cloud-azure-nic-01.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-nic-02.png b/docs/_static/images/cloud-azure-nic-02.png Binary files differdeleted file mode 100755 index 066f0ca1..00000000 --- a/docs/_static/images/cloud-azure-nic-02.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-nic-03.png b/docs/_static/images/cloud-azure-nic-03.png Binary files differdeleted file mode 100755 index 7d272620..00000000 --- a/docs/_static/images/cloud-azure-nic-03.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-nic-04.png b/docs/_static/images/cloud-azure-nic-04.png Binary files differdeleted file mode 100755 index 918c7e28..00000000 --- a/docs/_static/images/cloud-azure-nic-04.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-pub-ip-01.png b/docs/_static/images/cloud-azure-pub-ip-01.png Binary files differdeleted file mode 100755 index 721eff2c..00000000 --- a/docs/_static/images/cloud-azure-pub-ip-01.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-pub-ip-02.png b/docs/_static/images/cloud-azure-pub-ip-02.png Binary files differdeleted file mode 100755 index cebf1799..00000000 --- a/docs/_static/images/cloud-azure-pub-ip-02.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-pub-ip-03.png b/docs/_static/images/cloud-azure-pub-ip-03.png Binary files differdeleted file mode 100755 index 3a429dba..00000000 --- a/docs/_static/images/cloud-azure-pub-ip-03.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-rg-01.png b/docs/_static/images/cloud-azure-rg-01.png Binary files differdeleted file mode 100755 index 399a156c..00000000 --- a/docs/_static/images/cloud-azure-rg-01.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-rg-02.png b/docs/_static/images/cloud-azure-rg-02.png Binary files differdeleted file mode 100755 index 24de95f2..00000000 --- a/docs/_static/images/cloud-azure-rg-02.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-route-01.png b/docs/_static/images/cloud-azure-route-01.png Binary files differdeleted file mode 100755 index 1cf33838..00000000 --- a/docs/_static/images/cloud-azure-route-01.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-route-02.png b/docs/_static/images/cloud-azure-route-02.png Binary files differdeleted file mode 100755 index 0e4f294b..00000000 --- a/docs/_static/images/cloud-azure-route-02.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-route-03.png b/docs/_static/images/cloud-azure-route-03.png Binary files differdeleted file mode 100755 index 09dd3ec2..00000000 --- a/docs/_static/images/cloud-azure-route-03.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-route-04.png b/docs/_static/images/cloud-azure-route-04.png Binary files differdeleted file mode 100755 index 4c497c1c..00000000 --- a/docs/_static/images/cloud-azure-route-04.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-route-05.png b/docs/_static/images/cloud-azure-route-05.png Binary files differdeleted file mode 100755 index f30d3f5b..00000000 --- a/docs/_static/images/cloud-azure-route-05.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-sg-01.png b/docs/_static/images/cloud-azure-sg-01.png Binary files differdeleted file mode 100755 index 76f0ea95..00000000 --- a/docs/_static/images/cloud-azure-sg-01.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-sg-02.png b/docs/_static/images/cloud-azure-sg-02.png Binary files differdeleted file mode 100755 index 4e98a5c0..00000000 --- a/docs/_static/images/cloud-azure-sg-02.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-sg-03.png b/docs/_static/images/cloud-azure-sg-03.png Binary files differdeleted file mode 100755 index 4eeec886..00000000 --- a/docs/_static/images/cloud-azure-sg-03.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-sg-04.png b/docs/_static/images/cloud-azure-sg-04.png Binary files differdeleted file mode 100755 index a6d6426e..00000000 --- a/docs/_static/images/cloud-azure-sg-04.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vm-01.png b/docs/_static/images/cloud-azure-vm-01.png Binary files differdeleted file mode 100755 index aebf2c9e..00000000 --- a/docs/_static/images/cloud-azure-vm-01.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vm-02.png b/docs/_static/images/cloud-azure-vm-02.png Binary files differdeleted file mode 100755 index 5d24917f..00000000 --- a/docs/_static/images/cloud-azure-vm-02.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vm-03.png b/docs/_static/images/cloud-azure-vm-03.png Binary files differdeleted file mode 100755 index 63e8ef94..00000000 --- a/docs/_static/images/cloud-azure-vm-03.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vm-04.png b/docs/_static/images/cloud-azure-vm-04.png Binary files differdeleted file mode 100755 index 9cfaeccf..00000000 --- a/docs/_static/images/cloud-azure-vm-04.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vm-05.png b/docs/_static/images/cloud-azure-vm-05.png Binary files differdeleted file mode 100755 index 6f2a0c05..00000000 --- a/docs/_static/images/cloud-azure-vm-05.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vm-06.png b/docs/_static/images/cloud-azure-vm-06.png Binary files differdeleted file mode 100755 index 9a735f0e..00000000 --- a/docs/_static/images/cloud-azure-vm-06.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vm-07.png b/docs/_static/images/cloud-azure-vm-07.png Binary files differdeleted file mode 100755 index ce25cb52..00000000 --- a/docs/_static/images/cloud-azure-vm-07.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vm-08.png b/docs/_static/images/cloud-azure-vm-08.png Binary files differdeleted file mode 100755 index 30017934..00000000 --- a/docs/_static/images/cloud-azure-vm-08.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vm-09.png b/docs/_static/images/cloud-azure-vm-09.png Binary files differdeleted file mode 100755 index 5f0daf34..00000000 --- a/docs/_static/images/cloud-azure-vm-09.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vm-10.png b/docs/_static/images/cloud-azure-vm-10.png Binary files differdeleted file mode 100755 index ea913d68..00000000 --- a/docs/_static/images/cloud-azure-vm-10.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vm-11.png b/docs/_static/images/cloud-azure-vm-11.png Binary files differdeleted file mode 100755 index a0da6ea2..00000000 --- a/docs/_static/images/cloud-azure-vm-11.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vm-12.png b/docs/_static/images/cloud-azure-vm-12.png Binary files differdeleted file mode 100755 index 30cbcc52..00000000 --- a/docs/_static/images/cloud-azure-vm-12.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vm-13.png b/docs/_static/images/cloud-azure-vm-13.png Binary files differdeleted file mode 100755 index 527330e1..00000000 --- a/docs/_static/images/cloud-azure-vm-13.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vnet-01.png b/docs/_static/images/cloud-azure-vnet-01.png Binary files differdeleted file mode 100755 index 3577d8ab..00000000 --- a/docs/_static/images/cloud-azure-vnet-01.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vnet-02.png b/docs/_static/images/cloud-azure-vnet-02.png Binary files differdeleted file mode 100755 index 6da436f5..00000000 --- a/docs/_static/images/cloud-azure-vnet-02.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vnet-03.png b/docs/_static/images/cloud-azure-vnet-03.png Binary files differdeleted file mode 100755 index 36a6803b..00000000 --- a/docs/_static/images/cloud-azure-vnet-03.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vnet-04.png b/docs/_static/images/cloud-azure-vnet-04.png Binary files differdeleted file mode 100755 index 8351e203..00000000 --- a/docs/_static/images/cloud-azure-vnet-04.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vnet-05.png b/docs/_static/images/cloud-azure-vnet-05.png Binary files differdeleted file mode 100755 index daea1900..00000000 --- a/docs/_static/images/cloud-azure-vnet-05.png +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vnet-06.png b/docs/_static/images/cloud-azure-vnet-06.png Binary files differdeleted file mode 100755 index b11df2c0..00000000 --- a/docs/_static/images/cloud-azure-vnet-06.png +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-01.png b/docs/_static/images/cloud-gcp-01.png Binary files differdeleted file mode 100644 index f7681d6e..00000000 --- a/docs/_static/images/cloud-gcp-01.png +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-01.webp b/docs/_static/images/cloud-gcp-01.webp Binary files differnew file mode 100644 index 00000000..d21fc5ff --- /dev/null +++ b/docs/_static/images/cloud-gcp-01.webp diff --git a/docs/_static/images/cloud-gcp-02.png b/docs/_static/images/cloud-gcp-02.png Binary files differdeleted file mode 100644 index 5a17efb4..00000000 --- a/docs/_static/images/cloud-gcp-02.png +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-02.webp b/docs/_static/images/cloud-gcp-02.webp Binary files differnew file mode 100644 index 00000000..977f411f --- /dev/null +++ b/docs/_static/images/cloud-gcp-02.webp diff --git a/docs/_static/images/cloud-gcp-03.webp b/docs/_static/images/cloud-gcp-03.webp Binary files differnew file mode 100644 index 00000000..dd3a410b --- /dev/null +++ b/docs/_static/images/cloud-gcp-03.webp diff --git a/docs/_static/images/cloud-gcp-04.webp b/docs/_static/images/cloud-gcp-04.webp Binary files differnew file mode 100644 index 00000000..62e4380a --- /dev/null +++ b/docs/_static/images/cloud-gcp-04.webp diff --git a/docs/_static/images/cloud-gcp-05.webp b/docs/_static/images/cloud-gcp-05.webp Binary files differnew file mode 100644 index 00000000..92ed88b0 --- /dev/null +++ b/docs/_static/images/cloud-gcp-05.webp diff --git a/docs/_static/images/cloud-gcp-market-01.png b/docs/_static/images/cloud-gcp-market-01.png Binary files differdeleted file mode 100755 index 2d6f69b5..00000000 --- a/docs/_static/images/cloud-gcp-market-01.png +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-market-02.png b/docs/_static/images/cloud-gcp-market-02.png Binary files differdeleted file mode 100755 index 25e7f8a6..00000000 --- a/docs/_static/images/cloud-gcp-market-02.png +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-market-03.png b/docs/_static/images/cloud-gcp-market-03.png Binary files differdeleted file mode 100755 index f08de2ba..00000000 --- a/docs/_static/images/cloud-gcp-market-03.png +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-market-04.png b/docs/_static/images/cloud-gcp-market-04.png Binary files differdeleted file mode 100755 index 3735266c..00000000 --- a/docs/_static/images/cloud-gcp-market-04.png +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-market-05.png b/docs/_static/images/cloud-gcp-market-05.png Binary files differdeleted file mode 100755 index 26b8cb59..00000000 --- a/docs/_static/images/cloud-gcp-market-05.png +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-proj.png b/docs/_static/images/cloud-gcp-proj.png Binary files differdeleted file mode 100755 index a7a8d768..00000000 --- a/docs/_static/images/cloud-gcp-proj.png +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-svc.png b/docs/_static/images/cloud-gcp-svc.png Binary files differdeleted file mode 100755 index 5394a26e..00000000 --- a/docs/_static/images/cloud-gcp-svc.png +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vm-01.png b/docs/_static/images/cloud-gcp-vm-01.png Binary files differdeleted file mode 100755 index 166a45ac..00000000 --- a/docs/_static/images/cloud-gcp-vm-01.png +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vm-02.png b/docs/_static/images/cloud-gcp-vm-02.png Binary files differdeleted file mode 100755 index 83d9a4ea..00000000 --- a/docs/_static/images/cloud-gcp-vm-02.png +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vm-03.png b/docs/_static/images/cloud-gcp-vm-03.png Binary files differdeleted file mode 100755 index 9d152461..00000000 --- a/docs/_static/images/cloud-gcp-vm-03.png +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vm-04.png b/docs/_static/images/cloud-gcp-vm-04.png Binary files differdeleted file mode 100755 index a5c4cb64..00000000 --- a/docs/_static/images/cloud-gcp-vm-04.png +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vm-06.png b/docs/_static/images/cloud-gcp-vm-06.png Binary files differdeleted file mode 100755 index da5418a6..00000000 --- a/docs/_static/images/cloud-gcp-vm-06.png +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vm-07.png b/docs/_static/images/cloud-gcp-vm-07.png Binary files differdeleted file mode 100755 index 92a8e3d5..00000000 --- a/docs/_static/images/cloud-gcp-vm-07.png +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vm-08.png b/docs/_static/images/cloud-gcp-vm-08.png Binary files differdeleted file mode 100755 index c3d6cbeb..00000000 --- a/docs/_static/images/cloud-gcp-vm-08.png +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vm-09.png b/docs/_static/images/cloud-gcp-vm-09.png Binary files differdeleted file mode 100755 index 5ad7efaf..00000000 --- a/docs/_static/images/cloud-gcp-vm-09.png +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vpc-01.png b/docs/_static/images/cloud-gcp-vpc-01.png Binary files differdeleted file mode 100755 index b1967096..00000000 --- a/docs/_static/images/cloud-gcp-vpc-01.png +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vpc-02.png b/docs/_static/images/cloud-gcp-vpc-02.png Binary files differdeleted file mode 100755 index 3c2ca787..00000000 --- a/docs/_static/images/cloud-gcp-vpc-02.png +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vpc-03.png b/docs/_static/images/cloud-gcp-vpc-03.png Binary files differdeleted file mode 100755 index 6f8f282d..00000000 --- a/docs/_static/images/cloud-gcp-vpc-03.png +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vpc-04.png b/docs/_static/images/cloud-gcp-vpc-04.png Binary files differdeleted file mode 100755 index 4aa0ba40..00000000 --- a/docs/_static/images/cloud-gcp-vpc-04.png +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vpc-05.png b/docs/_static/images/cloud-gcp-vpc-05.png Binary files differdeleted file mode 100755 index 0d6a94d0..00000000 --- a/docs/_static/images/cloud-gcp-vpc-05.png +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vpc-06.png b/docs/_static/images/cloud-gcp-vpc-06.png Binary files differdeleted file mode 100755 index 5508e4b6..00000000 --- a/docs/_static/images/cloud-gcp-vpc-06.png +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vpc-07.png b/docs/_static/images/cloud-gcp-vpc-07.png Binary files differdeleted file mode 100755 index 29f0ce8e..00000000 --- a/docs/_static/images/cloud-gcp-vpc-07.png +++ /dev/null diff --git a/docs/_static/images/dhcp-relay-through-gre-bridge.png b/docs/_static/images/dhcp-relay-through-gre-bridge.png Binary files differdeleted file mode 100644 index 1f3e7744..00000000 --- a/docs/_static/images/dhcp-relay-through-gre-bridge.png +++ /dev/null diff --git a/docs/_static/images/dhcp-relay-through-gre-bridge.webp b/docs/_static/images/dhcp-relay-through-gre-bridge.webp Binary files differnew file mode 100644 index 00000000..4b626e91 --- /dev/null +++ b/docs/_static/images/dhcp-relay-through-gre-bridge.webp diff --git a/docs/_static/images/dual-hub-DMVPN.webp b/docs/_static/images/dual-hub-DMVPN.webp Binary files differnew file mode 100644 index 00000000..db4a4afd --- /dev/null +++ b/docs/_static/images/dual-hub-DMVPN.webp diff --git a/docs/_static/images/eve-ng-vyos.png b/docs/_static/images/eve-ng-vyos.png Binary files differdeleted file mode 100644 index fdd196a7..00000000 --- a/docs/_static/images/eve-ng-vyos.png +++ /dev/null diff --git a/docs/_static/images/eve-ng-vyos.webp b/docs/_static/images/eve-ng-vyos.webp Binary files differnew file mode 100644 index 00000000..f68b2fba --- /dev/null +++ b/docs/_static/images/eve-ng-vyos.webp diff --git a/docs/_static/images/firewall-and-vrf-blueprints.png b/docs/_static/images/firewall-and-vrf-blueprints.png Binary files differdeleted file mode 100644 index 8c3bf9f2..00000000 --- a/docs/_static/images/firewall-and-vrf-blueprints.png +++ /dev/null diff --git a/docs/_static/images/firewall-and-vrf-blueprints.webp b/docs/_static/images/firewall-and-vrf-blueprints.webp Binary files differnew file mode 100644 index 00000000..17194880 --- /dev/null +++ b/docs/_static/images/firewall-and-vrf-blueprints.webp diff --git a/docs/_static/images/firewall-bridge-forward.webp b/docs/_static/images/firewall-bridge-forward.webp Binary files differnew file mode 100644 index 00000000..2fde5f14 --- /dev/null +++ b/docs/_static/images/firewall-bridge-forward.webp diff --git a/docs/_static/images/firewall-bridge-input.webp b/docs/_static/images/firewall-bridge-input.webp Binary files differnew file mode 100644 index 00000000..1666bff9 --- /dev/null +++ b/docs/_static/images/firewall-bridge-input.webp diff --git a/docs/_static/images/firewall-bridge-output.webp b/docs/_static/images/firewall-bridge-output.webp Binary files differnew file mode 100644 index 00000000..98bb580f --- /dev/null +++ b/docs/_static/images/firewall-bridge-output.webp diff --git a/docs/_static/images/firewall-bridge-packet-flow.png b/docs/_static/images/firewall-bridge-packet-flow.png Binary files differdeleted file mode 100644 index 9e32315e..00000000 --- a/docs/_static/images/firewall-bridge-packet-flow.png +++ /dev/null diff --git a/docs/_static/images/firewall-flowtable-packet-flow.png b/docs/_static/images/firewall-flowtable-packet-flow.png Binary files differdeleted file mode 100644 index fca7e13a..00000000 --- a/docs/_static/images/firewall-flowtable-packet-flow.png +++ /dev/null diff --git a/docs/_static/images/firewall-flowtable-packet-flow.webp b/docs/_static/images/firewall-flowtable-packet-flow.webp Binary files differnew file mode 100644 index 00000000..6d20ab7a --- /dev/null +++ b/docs/_static/images/firewall-flowtable-packet-flow.webp diff --git a/docs/_static/images/firewall-fwd-packet-flow.png b/docs/_static/images/firewall-fwd-packet-flow.png Binary files differdeleted file mode 100644 index e4bc2adc..00000000 --- a/docs/_static/images/firewall-fwd-packet-flow.png +++ /dev/null diff --git a/docs/_static/images/firewall-fwd-packet-flow.webp b/docs/_static/images/firewall-fwd-packet-flow.webp Binary files differnew file mode 100644 index 00000000..31b155a9 --- /dev/null +++ b/docs/_static/images/firewall-fwd-packet-flow.webp diff --git a/docs/_static/images/firewall-gral-packet-flow.png b/docs/_static/images/firewall-gral-packet-flow.png Binary files differdeleted file mode 100644 index ee4e7b70..00000000 --- a/docs/_static/images/firewall-gral-packet-flow.png +++ /dev/null diff --git a/docs/_static/images/firewall-gral-packet-flow.webp b/docs/_static/images/firewall-gral-packet-flow.webp Binary files differnew file mode 100644 index 00000000..add21b1e --- /dev/null +++ b/docs/_static/images/firewall-gral-packet-flow.webp diff --git a/docs/_static/images/firewall-input-packet-flow.png b/docs/_static/images/firewall-input-packet-flow.png Binary files differdeleted file mode 100644 index 1c53c34a..00000000 --- a/docs/_static/images/firewall-input-packet-flow.png +++ /dev/null diff --git a/docs/_static/images/firewall-input-packet-flow.webp b/docs/_static/images/firewall-input-packet-flow.webp Binary files differnew file mode 100644 index 00000000..a5f207a1 --- /dev/null +++ b/docs/_static/images/firewall-input-packet-flow.webp diff --git a/docs/_static/images/firewall-netfilter.webp b/docs/_static/images/firewall-netfilter.webp Binary files differnew file mode 100644 index 00000000..0706a660 --- /dev/null +++ b/docs/_static/images/firewall-netfilter.webp diff --git a/docs/_static/images/firewall-traditional.png b/docs/_static/images/firewall-traditional.png Binary files differdeleted file mode 100644 index 7eb2b49d..00000000 --- a/docs/_static/images/firewall-traditional.png +++ /dev/null diff --git a/docs/_static/images/firewall-traditional.webp b/docs/_static/images/firewall-traditional.webp Binary files differnew file mode 100644 index 00000000..2804393f --- /dev/null +++ b/docs/_static/images/firewall-traditional.webp diff --git a/docs/_static/images/firewall-zonebased.png b/docs/_static/images/firewall-zonebased.png Binary files differdeleted file mode 100644 index 46b2f623..00000000 --- a/docs/_static/images/firewall-zonebased.png +++ /dev/null diff --git a/docs/_static/images/firewall-zonebased.webp b/docs/_static/images/firewall-zonebased.webp Binary files differnew file mode 100644 index 00000000..11394be0 --- /dev/null +++ b/docs/_static/images/firewall-zonebased.webp diff --git a/docs/_static/images/gns3-01.png b/docs/_static/images/gns3-01.png Binary files differdeleted file mode 100644 index a655d6aa..00000000 --- a/docs/_static/images/gns3-01.png +++ /dev/null diff --git a/docs/_static/images/gns3-01.webp b/docs/_static/images/gns3-01.webp Binary files differnew file mode 100644 index 00000000..d0d48d26 --- /dev/null +++ b/docs/_static/images/gns3-01.webp diff --git a/docs/_static/images/gns3-02.png b/docs/_static/images/gns3-02.png Binary files differdeleted file mode 100644 index 3dffdd2b..00000000 --- a/docs/_static/images/gns3-02.png +++ /dev/null diff --git a/docs/_static/images/gns3-02.webp b/docs/_static/images/gns3-02.webp Binary files differnew file mode 100644 index 00000000..83ec7546 --- /dev/null +++ b/docs/_static/images/gns3-02.webp diff --git a/docs/_static/images/gns3-03.png b/docs/_static/images/gns3-03.png Binary files differdeleted file mode 100644 index fcab6c5d..00000000 --- a/docs/_static/images/gns3-03.png +++ /dev/null diff --git a/docs/_static/images/gns3-03.webp b/docs/_static/images/gns3-03.webp Binary files differnew file mode 100644 index 00000000..aab36829 --- /dev/null +++ b/docs/_static/images/gns3-03.webp diff --git a/docs/_static/images/gns3-04.png b/docs/_static/images/gns3-04.png Binary files differdeleted file mode 100644 index afc30131..00000000 --- a/docs/_static/images/gns3-04.png +++ /dev/null diff --git a/docs/_static/images/gns3-04.webp b/docs/_static/images/gns3-04.webp Binary files differnew file mode 100644 index 00000000..722789bb --- /dev/null +++ b/docs/_static/images/gns3-04.webp diff --git a/docs/_static/images/gns3-05.png b/docs/_static/images/gns3-05.png Binary files differdeleted file mode 100644 index fee0dc65..00000000 --- a/docs/_static/images/gns3-05.png +++ /dev/null diff --git a/docs/_static/images/gns3-05.webp b/docs/_static/images/gns3-05.webp Binary files differnew file mode 100644 index 00000000..db42dd62 --- /dev/null +++ b/docs/_static/images/gns3-05.webp diff --git a/docs/_static/images/gns3-06.png b/docs/_static/images/gns3-06.png Binary files differdeleted file mode 100644 index c03cd89f..00000000 --- a/docs/_static/images/gns3-06.png +++ /dev/null diff --git a/docs/_static/images/gns3-06.webp b/docs/_static/images/gns3-06.webp Binary files differnew file mode 100644 index 00000000..b41d774c --- /dev/null +++ b/docs/_static/images/gns3-06.webp diff --git a/docs/_static/images/gns3-07.png b/docs/_static/images/gns3-07.png Binary files differdeleted file mode 100644 index 89d0a565..00000000 --- a/docs/_static/images/gns3-07.png +++ /dev/null diff --git a/docs/_static/images/gns3-07.webp b/docs/_static/images/gns3-07.webp Binary files differnew file mode 100644 index 00000000..360644f8 --- /dev/null +++ b/docs/_static/images/gns3-07.webp diff --git a/docs/_static/images/gns3-08.png b/docs/_static/images/gns3-08.png Binary files differdeleted file mode 100644 index aca0ff8a..00000000 --- a/docs/_static/images/gns3-08.png +++ /dev/null diff --git a/docs/_static/images/gns3-08.webp b/docs/_static/images/gns3-08.webp Binary files differnew file mode 100644 index 00000000..d7a8f3c3 --- /dev/null +++ b/docs/_static/images/gns3-08.webp diff --git a/docs/_static/images/gns3-09.png b/docs/_static/images/gns3-09.png Binary files differdeleted file mode 100644 index 7ae38c30..00000000 --- a/docs/_static/images/gns3-09.png +++ /dev/null diff --git a/docs/_static/images/gns3-09.webp b/docs/_static/images/gns3-09.webp Binary files differnew file mode 100644 index 00000000..b68dfdab --- /dev/null +++ b/docs/_static/images/gns3-09.webp diff --git a/docs/_static/images/gns3-10.png b/docs/_static/images/gns3-10.png Binary files differdeleted file mode 100644 index 1ee70d58..00000000 --- a/docs/_static/images/gns3-10.png +++ /dev/null diff --git a/docs/_static/images/gns3-10.webp b/docs/_static/images/gns3-10.webp Binary files differnew file mode 100644 index 00000000..61ab6d4e --- /dev/null +++ b/docs/_static/images/gns3-10.webp diff --git a/docs/_static/images/gns3-11.png b/docs/_static/images/gns3-11.png Binary files differdeleted file mode 100644 index 7990c73a..00000000 --- a/docs/_static/images/gns3-11.png +++ /dev/null diff --git a/docs/_static/images/gns3-11.webp b/docs/_static/images/gns3-11.webp Binary files differnew file mode 100644 index 00000000..efac5bb7 --- /dev/null +++ b/docs/_static/images/gns3-11.webp diff --git a/docs/_static/images/gns3-12.png b/docs/_static/images/gns3-12.png Binary files differdeleted file mode 100644 index 9ad51f70..00000000 --- a/docs/_static/images/gns3-12.png +++ /dev/null diff --git a/docs/_static/images/gns3-12.webp b/docs/_static/images/gns3-12.webp Binary files differnew file mode 100644 index 00000000..f0760510 --- /dev/null +++ b/docs/_static/images/gns3-12.webp diff --git a/docs/_static/images/gns3-13.png b/docs/_static/images/gns3-13.png Binary files differdeleted file mode 100644 index 5f9dd783..00000000 --- a/docs/_static/images/gns3-13.png +++ /dev/null diff --git a/docs/_static/images/gns3-13.webp b/docs/_static/images/gns3-13.webp Binary files differnew file mode 100644 index 00000000..a246380e --- /dev/null +++ b/docs/_static/images/gns3-13.webp diff --git a/docs/_static/images/gns3-14.png b/docs/_static/images/gns3-14.png Binary files differdeleted file mode 100644 index 447fcafe..00000000 --- a/docs/_static/images/gns3-14.png +++ /dev/null diff --git a/docs/_static/images/gns3-14.webp b/docs/_static/images/gns3-14.webp Binary files differnew file mode 100644 index 00000000..7e111c58 --- /dev/null +++ b/docs/_static/images/gns3-14.webp diff --git a/docs/_static/images/gns3-15.png b/docs/_static/images/gns3-15.png Binary files differdeleted file mode 100644 index 956b9edb..00000000 --- a/docs/_static/images/gns3-15.png +++ /dev/null diff --git a/docs/_static/images/gns3-15.webp b/docs/_static/images/gns3-15.webp Binary files differnew file mode 100644 index 00000000..79e7e6db --- /dev/null +++ b/docs/_static/images/gns3-15.webp diff --git a/docs/_static/images/gns3-16.png b/docs/_static/images/gns3-16.png Binary files differdeleted file mode 100644 index 4f75ffab..00000000 --- a/docs/_static/images/gns3-16.png +++ /dev/null diff --git a/docs/_static/images/gns3-16.webp b/docs/_static/images/gns3-16.webp Binary files differnew file mode 100644 index 00000000..423503ed --- /dev/null +++ b/docs/_static/images/gns3-16.webp diff --git a/docs/_static/images/gns3-17.png b/docs/_static/images/gns3-17.png Binary files differdeleted file mode 100644 index 64eff002..00000000 --- a/docs/_static/images/gns3-17.png +++ /dev/null diff --git a/docs/_static/images/gns3-17.webp b/docs/_static/images/gns3-17.webp Binary files differnew file mode 100644 index 00000000..8b7e5c01 --- /dev/null +++ b/docs/_static/images/gns3-17.webp diff --git a/docs/_static/images/gns3-20.png b/docs/_static/images/gns3-20.png Binary files differdeleted file mode 100644 index 17d92dea..00000000 --- a/docs/_static/images/gns3-20.png +++ /dev/null diff --git a/docs/_static/images/gns3-20.webp b/docs/_static/images/gns3-20.webp Binary files differnew file mode 100644 index 00000000..a65c47b4 --- /dev/null +++ b/docs/_static/images/gns3-20.webp diff --git a/docs/_static/images/gns3-21.png b/docs/_static/images/gns3-21.png Binary files differdeleted file mode 100644 index e461016a..00000000 --- a/docs/_static/images/gns3-21.png +++ /dev/null diff --git a/docs/_static/images/gns3-21.webp b/docs/_static/images/gns3-21.webp Binary files differnew file mode 100644 index 00000000..adc71baa --- /dev/null +++ b/docs/_static/images/gns3-21.webp diff --git a/docs/_static/images/gns3-215.png b/docs/_static/images/gns3-215.png Binary files differdeleted file mode 100644 index fde268ba..00000000 --- a/docs/_static/images/gns3-215.png +++ /dev/null diff --git a/docs/_static/images/gns3-215.webp b/docs/_static/images/gns3-215.webp Binary files differnew file mode 100644 index 00000000..49755246 --- /dev/null +++ b/docs/_static/images/gns3-215.webp diff --git a/docs/_static/images/gns3-22.png b/docs/_static/images/gns3-22.png Binary files differdeleted file mode 100644 index 6ed52c1d..00000000 --- a/docs/_static/images/gns3-22.png +++ /dev/null diff --git a/docs/_static/images/gns3-22.webp b/docs/_static/images/gns3-22.webp Binary files differnew file mode 100644 index 00000000..90bc4fa4 --- /dev/null +++ b/docs/_static/images/gns3-22.webp diff --git a/docs/_static/images/gowin-01.png b/docs/_static/images/gowin-01.png Binary files differdeleted file mode 100644 index 403ce52a..00000000 --- a/docs/_static/images/gowin-01.png +++ /dev/null diff --git a/docs/_static/images/gowin-01.webp b/docs/_static/images/gowin-01.webp Binary files differnew file mode 100644 index 00000000..048252d3 --- /dev/null +++ b/docs/_static/images/gowin-01.webp diff --git a/docs/_static/images/gowin-02.png b/docs/_static/images/gowin-02.png Binary files differdeleted file mode 100644 index 413f2948..00000000 --- a/docs/_static/images/gowin-02.png +++ /dev/null diff --git a/docs/_static/images/gowin-02.webp b/docs/_static/images/gowin-02.webp Binary files differnew file mode 100644 index 00000000..816c178c --- /dev/null +++ b/docs/_static/images/gowin-02.webp diff --git a/docs/_static/images/gowin-03.png b/docs/_static/images/gowin-03.png Binary files differdeleted file mode 100644 index fbdbb142..00000000 --- a/docs/_static/images/gowin-03.png +++ /dev/null diff --git a/docs/_static/images/gowin-03.webp b/docs/_static/images/gowin-03.webp Binary files differnew file mode 100644 index 00000000..ebf67368 --- /dev/null +++ b/docs/_static/images/gowin-03.webp diff --git a/docs/_static/images/gowin-04.png b/docs/_static/images/gowin-04.png Binary files differdeleted file mode 100644 index c68b8731..00000000 --- a/docs/_static/images/gowin-04.png +++ /dev/null diff --git a/docs/_static/images/gowin-04.webp b/docs/_static/images/gowin-04.webp Binary files differnew file mode 100644 index 00000000..b5e94a84 --- /dev/null +++ b/docs/_static/images/gowin-04.webp diff --git a/docs/_static/images/inter-vrf-routing-vrf-lite.png b/docs/_static/images/inter-vrf-routing-vrf-lite.png Binary files differdeleted file mode 100644 index 3acefee6..00000000 --- a/docs/_static/images/inter-vrf-routing-vrf-lite.png +++ /dev/null diff --git a/docs/_static/images/inter-vrf-routing-vrf-lite.webp b/docs/_static/images/inter-vrf-routing-vrf-lite.webp Binary files differnew file mode 100644 index 00000000..43394ec5 --- /dev/null +++ b/docs/_static/images/inter-vrf-routing-vrf-lite.webp diff --git a/docs/_static/images/ipsec-vyos-pa.png b/docs/_static/images/ipsec-vyos-pa.png Binary files differdeleted file mode 100644 index 0929bcc7..00000000 --- a/docs/_static/images/ipsec-vyos-pa.png +++ /dev/null diff --git a/docs/_static/images/ipsec-vyos-pa.webp b/docs/_static/images/ipsec-vyos-pa.webp Binary files differnew file mode 100644 index 00000000..1758d65c --- /dev/null +++ b/docs/_static/images/ipsec-vyos-pa.webp diff --git a/docs/_static/images/json.webp b/docs/_static/images/json.webp Binary files differnew file mode 100644 index 00000000..2dd0460f --- /dev/null +++ b/docs/_static/images/json.webp diff --git a/docs/_static/images/key.webp b/docs/_static/images/key.webp Binary files differnew file mode 100644 index 00000000..24fcceca --- /dev/null +++ b/docs/_static/images/key.webp diff --git a/docs/_static/images/keypairs.png b/docs/_static/images/keypairs.png Binary files differdeleted file mode 100644 index 7e772ae9..00000000 --- a/docs/_static/images/keypairs.png +++ /dev/null diff --git a/docs/_static/images/keypairs.webp b/docs/_static/images/keypairs.webp Binary files differnew file mode 100644 index 00000000..14df4da3 --- /dev/null +++ b/docs/_static/images/keypairs.webp diff --git a/docs/_static/images/lac-lns-diagram.jpg b/docs/_static/images/lac-lns-diagram.jpg Binary files differdeleted file mode 100644 index 4463a3c3..00000000 --- a/docs/_static/images/lac-lns-diagram.jpg +++ /dev/null diff --git a/docs/_static/images/lac-lns-diagram.webp b/docs/_static/images/lac-lns-diagram.webp Binary files differnew file mode 100644 index 00000000..0ce052c2 --- /dev/null +++ b/docs/_static/images/lac-lns-diagram.webp diff --git a/docs/_static/images/lac-lns-winclient.jpg b/docs/_static/images/lac-lns-winclient.jpg Binary files differdeleted file mode 100644 index 9fa99152..00000000 --- a/docs/_static/images/lac-lns-winclient.jpg +++ /dev/null diff --git a/docs/_static/images/lac-lns-winclient.webp b/docs/_static/images/lac-lns-winclient.webp Binary files differnew file mode 100644 index 00000000..95792cad --- /dev/null +++ b/docs/_static/images/lac-lns-winclient.webp diff --git a/docs/_static/images/ldapone.png b/docs/_static/images/ldapone.png Binary files differdeleted file mode 100644 index 33ecf628..00000000 --- a/docs/_static/images/ldapone.png +++ /dev/null diff --git a/docs/_static/images/ldapone.webp b/docs/_static/images/ldapone.webp Binary files differnew file mode 100644 index 00000000..0f070454 --- /dev/null +++ b/docs/_static/images/ldapone.webp diff --git a/docs/_static/images/ldaptwo.png b/docs/_static/images/ldaptwo.png Binary files differdeleted file mode 100644 index 7cb9e0cb..00000000 --- a/docs/_static/images/ldaptwo.png +++ /dev/null diff --git a/docs/_static/images/ldaptwo.webp b/docs/_static/images/ldaptwo.webp Binary files differnew file mode 100644 index 00000000..9ee636df --- /dev/null +++ b/docs/_static/images/ldaptwo.webp diff --git a/docs/_static/images/mainschema.png b/docs/_static/images/mainschema.png Binary files differdeleted file mode 100644 index c39e5da2..00000000 --- a/docs/_static/images/mainschema.png +++ /dev/null diff --git a/docs/_static/images/mainschema.webp b/docs/_static/images/mainschema.webp Binary files differnew file mode 100644 index 00000000..c9db82ca --- /dev/null +++ b/docs/_static/images/mainschema.webp diff --git a/docs/_static/images/multicast-basic.png b/docs/_static/images/multicast-basic.png Binary files differdeleted file mode 100644 index 3d4a3de3..00000000 --- a/docs/_static/images/multicast-basic.png +++ /dev/null diff --git a/docs/_static/images/multicast-basic.webp b/docs/_static/images/multicast-basic.webp Binary files differnew file mode 100644 index 00000000..8e963421 --- /dev/null +++ b/docs/_static/images/multicast-basic.webp diff --git a/docs/_static/images/nat_before_vpn_topology.png b/docs/_static/images/nat_before_vpn_topology.png Binary files differdeleted file mode 100644 index ae23c92d..00000000 --- a/docs/_static/images/nat_before_vpn_topology.png +++ /dev/null diff --git a/docs/_static/images/nat_before_vpn_topology.webp b/docs/_static/images/nat_before_vpn_topology.webp Binary files differnew file mode 100644 index 00000000..7f93a3d8 --- /dev/null +++ b/docs/_static/images/nat_before_vpn_topology.webp diff --git a/docs/_static/images/nmp1.png b/docs/_static/images/nmp1.png Binary files differdeleted file mode 100644 index 0b761a76..00000000 --- a/docs/_static/images/nmp1.png +++ /dev/null diff --git a/docs/_static/images/nmp1.webp b/docs/_static/images/nmp1.webp Binary files differnew file mode 100644 index 00000000..60035421 --- /dev/null +++ b/docs/_static/images/nmp1.webp diff --git a/docs/_static/images/nmp2.png b/docs/_static/images/nmp2.png Binary files differdeleted file mode 100644 index 3190a099..00000000 --- a/docs/_static/images/nmp2.png +++ /dev/null diff --git a/docs/_static/images/nmp2.webp b/docs/_static/images/nmp2.webp Binary files differnew file mode 100644 index 00000000..6dbf4d42 --- /dev/null +++ b/docs/_static/images/nmp2.webp diff --git a/docs/_static/images/nmp3.png b/docs/_static/images/nmp3.png Binary files differdeleted file mode 100644 index 0585b80e..00000000 --- a/docs/_static/images/nmp3.png +++ /dev/null diff --git a/docs/_static/images/nmp3.webp b/docs/_static/images/nmp3.webp Binary files differnew file mode 100644 index 00000000..72ab7050 --- /dev/null +++ b/docs/_static/images/nmp3.webp diff --git a/docs/_static/images/nmp4.png b/docs/_static/images/nmp4.png Binary files differdeleted file mode 100644 index e0aa893e..00000000 --- a/docs/_static/images/nmp4.png +++ /dev/null diff --git a/docs/_static/images/nmp4.webp b/docs/_static/images/nmp4.webp Binary files differnew file mode 100644 index 00000000..d7684b38 --- /dev/null +++ b/docs/_static/images/nmp4.webp diff --git a/docs/_static/images/nmp5.png b/docs/_static/images/nmp5.png Binary files differdeleted file mode 100644 index d3149034..00000000 --- a/docs/_static/images/nmp5.png +++ /dev/null diff --git a/docs/_static/images/nmp5.webp b/docs/_static/images/nmp5.webp Binary files differnew file mode 100644 index 00000000..6c64707c --- /dev/null +++ b/docs/_static/images/nmp5.webp diff --git a/docs/_static/images/nmp6.png b/docs/_static/images/nmp6.png Binary files differdeleted file mode 100644 index c4645e33..00000000 --- a/docs/_static/images/nmp6.png +++ /dev/null diff --git a/docs/_static/images/nmp6.webp b/docs/_static/images/nmp6.webp Binary files differnew file mode 100644 index 00000000..85141b11 --- /dev/null +++ b/docs/_static/images/nmp6.webp diff --git a/docs/_static/images/nmp7.png b/docs/_static/images/nmp7.png Binary files differdeleted file mode 100644 index 3e518e7e..00000000 --- a/docs/_static/images/nmp7.png +++ /dev/null diff --git a/docs/_static/images/nmp7.webp b/docs/_static/images/nmp7.webp Binary files differnew file mode 100644 index 00000000..6f64df83 --- /dev/null +++ b/docs/_static/images/nmp7.webp diff --git a/docs/_static/images/openvpn_site2site_diagram.jpg b/docs/_static/images/openvpn_site2site_diagram.jpg Binary files differdeleted file mode 100644 index 05881e7d..00000000 --- a/docs/_static/images/openvpn_site2site_diagram.jpg +++ /dev/null diff --git a/docs/_static/images/openvpn_site2site_diagram.webp b/docs/_static/images/openvpn_site2site_diagram.webp Binary files differnew file mode 100644 index 00000000..97d4df3f --- /dev/null +++ b/docs/_static/images/openvpn_site2site_diagram.webp diff --git a/docs/_static/images/password-recovery-01.png b/docs/_static/images/password-recovery-01.png Binary files differdeleted file mode 100644 index 345ca357..00000000 --- a/docs/_static/images/password-recovery-01.png +++ /dev/null diff --git a/docs/_static/images/pbr_example_1.png b/docs/_static/images/pbr_example_1.png Binary files differdeleted file mode 100644 index 3dff6db6..00000000 --- a/docs/_static/images/pbr_example_1.png +++ /dev/null diff --git a/docs/_static/images/pbr_example_1.webp b/docs/_static/images/pbr_example_1.webp Binary files differnew file mode 100644 index 00000000..4e8ba882 --- /dev/null +++ b/docs/_static/images/pbr_example_1.webp diff --git a/docs/_static/images/permanent_install.png b/docs/_static/images/permanent_install.png Binary files differdeleted file mode 100644 index e772e86d..00000000 --- a/docs/_static/images/permanent_install.png +++ /dev/null diff --git a/docs/_static/images/policy-based-ipsec-and-firewall.webp b/docs/_static/images/policy-based-ipsec-and-firewall.webp Binary files differnew file mode 100644 index 00000000..2f57a305 --- /dev/null +++ b/docs/_static/images/policy-based-ipsec-and-firewall.webp diff --git a/docs/_static/images/pppoe-ipv6-pd-diagram.jpg b/docs/_static/images/pppoe-ipv6-pd-diagram.jpg Binary files differdeleted file mode 100644 index 430848c8..00000000 --- a/docs/_static/images/pppoe-ipv6-pd-diagram.jpg +++ /dev/null diff --git a/docs/_static/images/pppoe-ipv6-pd-diagram.webp b/docs/_static/images/pppoe-ipv6-pd-diagram.webp Binary files differnew file mode 100644 index 00000000..344bbf21 --- /dev/null +++ b/docs/_static/images/pppoe-ipv6-pd-diagram.webp diff --git a/docs/_static/images/project.webp b/docs/_static/images/project.webp Binary files differnew file mode 100644 index 00000000..617375a2 --- /dev/null +++ b/docs/_static/images/project.webp diff --git a/docs/_static/images/qos1.png b/docs/_static/images/qos1.png Binary files differdeleted file mode 100644 index 9c16e6a3..00000000 --- a/docs/_static/images/qos1.png +++ /dev/null diff --git a/docs/_static/images/qos1.webp b/docs/_static/images/qos1.webp Binary files differnew file mode 100644 index 00000000..fe9264a6 --- /dev/null +++ b/docs/_static/images/qos1.webp diff --git a/docs/_static/images/qos10.png b/docs/_static/images/qos10.png Binary files differdeleted file mode 100644 index 2f90ffe7..00000000 --- a/docs/_static/images/qos10.png +++ /dev/null diff --git a/docs/_static/images/qos10.webp b/docs/_static/images/qos10.webp Binary files differnew file mode 100644 index 00000000..646ae67b --- /dev/null +++ b/docs/_static/images/qos10.webp diff --git a/docs/_static/images/qos2.png b/docs/_static/images/qos2.png Binary files differdeleted file mode 100644 index 4d351344..00000000 --- a/docs/_static/images/qos2.png +++ /dev/null diff --git a/docs/_static/images/qos2.webp b/docs/_static/images/qos2.webp Binary files differnew file mode 100644 index 00000000..7c8a1336 --- /dev/null +++ b/docs/_static/images/qos2.webp diff --git a/docs/_static/images/qos3.png b/docs/_static/images/qos3.png Binary files differdeleted file mode 100644 index 97efaeb7..00000000 --- a/docs/_static/images/qos3.png +++ /dev/null diff --git a/docs/_static/images/qos3.webp b/docs/_static/images/qos3.webp Binary files differnew file mode 100644 index 00000000..3cf2dd32 --- /dev/null +++ b/docs/_static/images/qos3.webp diff --git a/docs/_static/images/qos4.png b/docs/_static/images/qos4.png Binary files differdeleted file mode 100644 index b87b256e..00000000 --- a/docs/_static/images/qos4.png +++ /dev/null diff --git a/docs/_static/images/qos4.webp b/docs/_static/images/qos4.webp Binary files differnew file mode 100644 index 00000000..cc108ee8 --- /dev/null +++ b/docs/_static/images/qos4.webp diff --git a/docs/_static/images/qos5.png b/docs/_static/images/qos5.png Binary files differdeleted file mode 100644 index 4a615755..00000000 --- a/docs/_static/images/qos5.png +++ /dev/null diff --git a/docs/_static/images/qos5.webp b/docs/_static/images/qos5.webp Binary files differnew file mode 100644 index 00000000..d41ae04d --- /dev/null +++ b/docs/_static/images/qos5.webp diff --git a/docs/_static/images/qos6.png b/docs/_static/images/qos6.png Binary files differdeleted file mode 100644 index 907d6104..00000000 --- a/docs/_static/images/qos6.png +++ /dev/null diff --git a/docs/_static/images/qos6.webp b/docs/_static/images/qos6.webp Binary files differnew file mode 100644 index 00000000..7d238851 --- /dev/null +++ b/docs/_static/images/qos6.webp diff --git a/docs/_static/images/qos7.png b/docs/_static/images/qos7.png Binary files differdeleted file mode 100644 index 03ec5cd1..00000000 --- a/docs/_static/images/qos7.png +++ /dev/null diff --git a/docs/_static/images/qos7.webp b/docs/_static/images/qos7.webp Binary files differnew file mode 100644 index 00000000..026452c2 --- /dev/null +++ b/docs/_static/images/qos7.webp diff --git a/docs/_static/images/qos8.png b/docs/_static/images/qos8.png Binary files differdeleted file mode 100644 index 3566ac00..00000000 --- a/docs/_static/images/qos8.png +++ /dev/null diff --git a/docs/_static/images/qos8.webp b/docs/_static/images/qos8.webp Binary files differnew file mode 100644 index 00000000..e1706ce2 --- /dev/null +++ b/docs/_static/images/qos8.webp diff --git a/docs/_static/images/qos9.png b/docs/_static/images/qos9.png Binary files differdeleted file mode 100644 index 67d8afd2..00000000 --- a/docs/_static/images/qos9.png +++ /dev/null diff --git a/docs/_static/images/qos9.webp b/docs/_static/images/qos9.webp Binary files differnew file mode 100644 index 00000000..2cc6fdaa --- /dev/null +++ b/docs/_static/images/qos9.webp diff --git a/docs/_static/images/reset-password-step-1.webp b/docs/_static/images/reset-password-step-1.webp Binary files differnew file mode 100644 index 00000000..fb361d3b --- /dev/null +++ b/docs/_static/images/reset-password-step-1.webp diff --git a/docs/_static/images/reset-password-step-2.webp b/docs/_static/images/reset-password-step-2.webp Binary files differnew file mode 100644 index 00000000..66262a88 --- /dev/null +++ b/docs/_static/images/reset-password-step-2.webp diff --git a/docs/_static/images/reset-password-step-3.webp b/docs/_static/images/reset-password-step-3.webp Binary files differnew file mode 100644 index 00000000..ad6f2899 --- /dev/null +++ b/docs/_static/images/reset-password-step-3.webp diff --git a/docs/_static/images/reset-password-step-4.webp b/docs/_static/images/reset-password-step-4.webp Binary files differnew file mode 100644 index 00000000..7dd5efa2 --- /dev/null +++ b/docs/_static/images/reset-password-step-4.webp diff --git a/docs/_static/images/reset-password-step-5.webp b/docs/_static/images/reset-password-step-5.webp Binary files differnew file mode 100644 index 00000000..b4702618 --- /dev/null +++ b/docs/_static/images/reset-password-step-5.webp diff --git a/docs/_static/images/service.webp b/docs/_static/images/service.webp Binary files differnew file mode 100644 index 00000000..051cd9b1 --- /dev/null +++ b/docs/_static/images/service.webp diff --git a/docs/_static/images/service_conntrack_sync-schema.png b/docs/_static/images/service_conntrack_sync-schema.png Binary files differdeleted file mode 100644 index 1b5fe8fb..00000000 --- a/docs/_static/images/service_conntrack_sync-schema.png +++ /dev/null diff --git a/docs/_static/images/service_conntrack_sync-schema.webp b/docs/_static/images/service_conntrack_sync-schema.webp Binary files differnew file mode 100644 index 00000000..e347aa19 --- /dev/null +++ b/docs/_static/images/service_conntrack_sync-schema.webp diff --git a/docs/_static/images/service_dhcp-relay01.png b/docs/_static/images/service_dhcp-relay01.png Binary files differdeleted file mode 100644 index cd7f30cf..00000000 --- a/docs/_static/images/service_dhcp-relay01.png +++ /dev/null diff --git a/docs/_static/images/service_dhcp-relay01.webp b/docs/_static/images/service_dhcp-relay01.webp Binary files differnew file mode 100644 index 00000000..5fbfad3e --- /dev/null +++ b/docs/_static/images/service_dhcp-relay01.webp diff --git a/docs/_static/images/service_dhcpv6-relay01.png b/docs/_static/images/service_dhcpv6-relay01.png Binary files differdeleted file mode 100644 index 9a10a10f..00000000 --- a/docs/_static/images/service_dhcpv6-relay01.png +++ /dev/null diff --git a/docs/_static/images/service_dhcpv6-relay01.webp b/docs/_static/images/service_dhcpv6-relay01.webp Binary files differnew file mode 100644 index 00000000..1f72f51f --- /dev/null +++ b/docs/_static/images/service_dhcpv6-relay01.webp diff --git a/docs/_static/images/service_snmp_communication_principles_diagram.png b/docs/_static/images/service_snmp_communication_principles_diagram.png Binary files differdeleted file mode 100644 index eff2ce45..00000000 --- a/docs/_static/images/service_snmp_communication_principles_diagram.png +++ /dev/null diff --git a/docs/_static/images/service_snmp_communication_principles_diagram.webp b/docs/_static/images/service_snmp_communication_principles_diagram.webp Binary files differnew file mode 100644 index 00000000..abb18133 --- /dev/null +++ b/docs/_static/images/service_snmp_communication_principles_diagram.webp diff --git a/docs/_static/images/sg.png b/docs/_static/images/sg.png Binary files differdeleted file mode 100644 index 8be51e1f..00000000 --- a/docs/_static/images/sg.png +++ /dev/null diff --git a/docs/_static/images/sg.webp b/docs/_static/images/sg.webp Binary files differnew file mode 100644 index 00000000..5ee77e0d --- /dev/null +++ b/docs/_static/images/sg.webp diff --git a/docs/_static/images/sticky-connections.jpg b/docs/_static/images/sticky-connections.jpg Binary files differdeleted file mode 100644 index 25fd72a9..00000000 --- a/docs/_static/images/sticky-connections.jpg +++ /dev/null diff --git a/docs/_static/images/sticky-connections.webp b/docs/_static/images/sticky-connections.webp Binary files differnew file mode 100644 index 00000000..92e5b769 --- /dev/null +++ b/docs/_static/images/sticky-connections.webp diff --git a/docs/_static/images/traffic.png b/docs/_static/images/traffic.png Binary files differdeleted file mode 100644 index 74002b16..00000000 --- a/docs/_static/images/traffic.png +++ /dev/null diff --git a/docs/_static/images/traffic.webp b/docs/_static/images/traffic.webp Binary files differnew file mode 100644 index 00000000..f6f9e183 --- /dev/null +++ b/docs/_static/images/traffic.webp diff --git a/docs/_static/images/uefi_secureboot_01.webp b/docs/_static/images/uefi_secureboot_01.webp Binary files differnew file mode 100644 index 00000000..dccf8964 --- /dev/null +++ b/docs/_static/images/uefi_secureboot_01.webp diff --git a/docs/_static/images/uefi_secureboot_02.webp b/docs/_static/images/uefi_secureboot_02.webp Binary files differnew file mode 100644 index 00000000..e9175323 --- /dev/null +++ b/docs/_static/images/uefi_secureboot_02.webp diff --git a/docs/_static/images/uefi_secureboot_03.webp b/docs/_static/images/uefi_secureboot_03.webp Binary files differnew file mode 100644 index 00000000..bcc5143c --- /dev/null +++ b/docs/_static/images/uefi_secureboot_03.webp diff --git a/docs/_static/images/uefi_secureboot_04.webp b/docs/_static/images/uefi_secureboot_04.webp Binary files differnew file mode 100644 index 00000000..a84f426e --- /dev/null +++ b/docs/_static/images/uefi_secureboot_04.webp diff --git a/docs/_static/images/uefi_secureboot_05.webp b/docs/_static/images/uefi_secureboot_05.webp Binary files differnew file mode 100644 index 00000000..0b3c4883 --- /dev/null +++ b/docs/_static/images/uefi_secureboot_05.webp diff --git a/docs/_static/images/uefi_secureboot_06.webp b/docs/_static/images/uefi_secureboot_06.webp Binary files differnew file mode 100644 index 00000000..4bcf4a2f --- /dev/null +++ b/docs/_static/images/uefi_secureboot_06.webp diff --git a/docs/_static/images/uefi_secureboot_07.webp b/docs/_static/images/uefi_secureboot_07.webp Binary files differnew file mode 100644 index 00000000..13ba02d1 --- /dev/null +++ b/docs/_static/images/uefi_secureboot_07.webp diff --git a/docs/_static/images/virt-libvirt-01.png b/docs/_static/images/virt-libvirt-01.png Binary files differdeleted file mode 100644 index 06baea8e..00000000 --- a/docs/_static/images/virt-libvirt-01.png +++ /dev/null diff --git a/docs/_static/images/virt-libvirt-01.webp b/docs/_static/images/virt-libvirt-01.webp Binary files differnew file mode 100644 index 00000000..02498c96 --- /dev/null +++ b/docs/_static/images/virt-libvirt-01.webp diff --git a/docs/_static/images/virt-libvirt-02.png b/docs/_static/images/virt-libvirt-02.png Binary files differdeleted file mode 100644 index b6c4b379..00000000 --- a/docs/_static/images/virt-libvirt-02.png +++ /dev/null diff --git a/docs/_static/images/virt-libvirt-02.webp b/docs/_static/images/virt-libvirt-02.webp Binary files differnew file mode 100644 index 00000000..06ad10aa --- /dev/null +++ b/docs/_static/images/virt-libvirt-02.webp diff --git a/docs/_static/images/virt-libvirt-03.png b/docs/_static/images/virt-libvirt-03.png Binary files differdeleted file mode 100644 index ac3891f0..00000000 --- a/docs/_static/images/virt-libvirt-03.png +++ /dev/null diff --git a/docs/_static/images/virt-libvirt-03.webp b/docs/_static/images/virt-libvirt-03.webp Binary files differnew file mode 100644 index 00000000..e8beae0c --- /dev/null +++ b/docs/_static/images/virt-libvirt-03.webp diff --git a/docs/_static/images/virt-libvirt-04.png b/docs/_static/images/virt-libvirt-04.png Binary files differdeleted file mode 100644 index b1218597..00000000 --- a/docs/_static/images/virt-libvirt-04.png +++ /dev/null diff --git a/docs/_static/images/virt-libvirt-04.webp b/docs/_static/images/virt-libvirt-04.webp Binary files differnew file mode 100644 index 00000000..586cdedb --- /dev/null +++ b/docs/_static/images/virt-libvirt-04.webp diff --git a/docs/_static/images/virt-libvirt-05.png b/docs/_static/images/virt-libvirt-05.png Binary files differdeleted file mode 100644 index 5579c281..00000000 --- a/docs/_static/images/virt-libvirt-05.png +++ /dev/null diff --git a/docs/_static/images/virt-libvirt-05.webp b/docs/_static/images/virt-libvirt-05.webp Binary files differnew file mode 100644 index 00000000..65c57a3d --- /dev/null +++ b/docs/_static/images/virt-libvirt-05.webp diff --git a/docs/_static/images/virt-libvirt-06.png b/docs/_static/images/virt-libvirt-06.png Binary files differdeleted file mode 100644 index e0983d23..00000000 --- a/docs/_static/images/virt-libvirt-06.png +++ /dev/null diff --git a/docs/_static/images/virt-libvirt-06.webp b/docs/_static/images/virt-libvirt-06.webp Binary files differnew file mode 100644 index 00000000..da7a41a9 --- /dev/null +++ b/docs/_static/images/virt-libvirt-06.webp diff --git a/docs/_static/images/virt-libvirt-qc-01.png b/docs/_static/images/virt-libvirt-qc-01.png Binary files differdeleted file mode 100644 index 49867bd0..00000000 --- a/docs/_static/images/virt-libvirt-qc-01.png +++ /dev/null diff --git a/docs/_static/images/virt-libvirt-qc-01.webp b/docs/_static/images/virt-libvirt-qc-01.webp Binary files differnew file mode 100644 index 00000000..1b19ca60 --- /dev/null +++ b/docs/_static/images/virt-libvirt-qc-01.webp diff --git a/docs/_static/images/virt-libvirt-qc-02.png b/docs/_static/images/virt-libvirt-qc-02.png Binary files differdeleted file mode 100644 index a71b8f64..00000000 --- a/docs/_static/images/virt-libvirt-qc-02.png +++ /dev/null diff --git a/docs/_static/images/virt-libvirt-qc-02.webp b/docs/_static/images/virt-libvirt-qc-02.webp Binary files differnew file mode 100644 index 00000000..8281ebfb --- /dev/null +++ b/docs/_static/images/virt-libvirt-qc-02.webp diff --git a/docs/_static/images/virt-libvirt-qc-03.png b/docs/_static/images/virt-libvirt-qc-03.png Binary files differdeleted file mode 100644 index 4eefaa58..00000000 --- a/docs/_static/images/virt-libvirt-qc-03.png +++ /dev/null diff --git a/docs/_static/images/virt-libvirt-qc-03.webp b/docs/_static/images/virt-libvirt-qc-03.webp Binary files differnew file mode 100644 index 00000000..7dc4e7e8 --- /dev/null +++ b/docs/_static/images/virt-libvirt-qc-03.webp diff --git a/docs/_static/images/vpn_dmvpn_topology01.png b/docs/_static/images/vpn_dmvpn_topology01.png Binary files differdeleted file mode 100644 index 17433be6..00000000 --- a/docs/_static/images/vpn_dmvpn_topology01.png +++ /dev/null diff --git a/docs/_static/images/vpn_dmvpn_topology01.webp b/docs/_static/images/vpn_dmvpn_topology01.webp Binary files differnew file mode 100644 index 00000000..3da35995 --- /dev/null +++ b/docs/_static/images/vpn_dmvpn_topology01.webp diff --git a/docs/_static/images/vpn_s2s_ikev2.png b/docs/_static/images/vpn_s2s_ikev2.png Binary files differdeleted file mode 100644 index f8050e3a..00000000 --- a/docs/_static/images/vpn_s2s_ikev2.png +++ /dev/null diff --git a/docs/_static/images/vpn_s2s_ikev2.webp b/docs/_static/images/vpn_s2s_ikev2.webp Binary files differnew file mode 100644 index 00000000..615f689c --- /dev/null +++ b/docs/_static/images/vpn_s2s_ikev2.webp diff --git a/docs/_static/images/vpn_s2s_ikev2_c.png b/docs/_static/images/vpn_s2s_ikev2_c.png Binary files differdeleted file mode 100644 index 2d9e21b5..00000000 --- a/docs/_static/images/vpn_s2s_ikev2_c.png +++ /dev/null diff --git a/docs/_static/images/vpn_s2s_ikev2_c.webp b/docs/_static/images/vpn_s2s_ikev2_c.webp Binary files differnew file mode 100644 index 00000000..f572fc29 --- /dev/null +++ b/docs/_static/images/vpn_s2s_ikev2_c.webp diff --git a/docs/_static/images/vrf-example-topology-01.png b/docs/_static/images/vrf-example-topology-01.png Binary files differdeleted file mode 100644 index 57357509..00000000 --- a/docs/_static/images/vrf-example-topology-01.png +++ /dev/null diff --git a/docs/_static/images/vrf-example-topology-01.webp b/docs/_static/images/vrf-example-topology-01.webp Binary files differnew file mode 100644 index 00000000..696abad1 --- /dev/null +++ b/docs/_static/images/vrf-example-topology-01.webp diff --git a/docs/_static/images/vyos-downloads.png b/docs/_static/images/vyos-downloads.png Binary files differdeleted file mode 100644 index 6bad2b19..00000000 --- a/docs/_static/images/vyos-downloads.png +++ /dev/null diff --git a/docs/_static/images/vyos-downloads.webp b/docs/_static/images/vyos-downloads.webp Binary files differnew file mode 100644 index 00000000..9d446701 --- /dev/null +++ b/docs/_static/images/vyos-downloads.webp diff --git a/docs/_static/images/vyos-logo-icon.webp b/docs/_static/images/vyos-logo-icon.webp Binary files differnew file mode 100644 index 00000000..d2867b8c --- /dev/null +++ b/docs/_static/images/vyos-logo-icon.webp diff --git a/docs/_static/images/vyos-logo.webp b/docs/_static/images/vyos-logo.webp Binary files differnew file mode 100644 index 00000000..d15112e7 --- /dev/null +++ b/docs/_static/images/vyos-logo.webp diff --git a/docs/_static/images/vyos-sr-isis.png b/docs/_static/images/vyos-sr-isis.png Binary files differdeleted file mode 100644 index 62430919..00000000 --- a/docs/_static/images/vyos-sr-isis.png +++ /dev/null diff --git a/docs/_static/images/vyos-sr-isis.webp b/docs/_static/images/vyos-sr-isis.webp Binary files differnew file mode 100644 index 00000000..8ecad813 --- /dev/null +++ b/docs/_static/images/vyos-sr-isis.webp diff --git a/docs/_static/images/vyos_1_4_nat66_simple.png b/docs/_static/images/vyos_1_4_nat66_simple.png Binary files differdeleted file mode 100644 index d7c54115..00000000 --- a/docs/_static/images/vyos_1_4_nat66_simple.png +++ /dev/null diff --git a/docs/_static/images/vyos_1_4_nat66_simple.webp b/docs/_static/images/vyos_1_4_nat66_simple.webp Binary files differnew file mode 100644 index 00000000..6dedc08c --- /dev/null +++ b/docs/_static/images/vyos_1_4_nat66_simple.webp diff --git a/docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.png b/docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.png Binary files differdeleted file mode 100644 index 297fdd11..00000000 --- a/docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.png +++ /dev/null diff --git a/docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.webp b/docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.webp Binary files differnew file mode 100644 index 00000000..352d1f08 --- /dev/null +++ b/docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.webp diff --git a/docs/_static/images/vyos_arista_bond_lacp.png b/docs/_static/images/vyos_arista_bond_lacp.png Binary files differdeleted file mode 100644 index 6c9ef8ec..00000000 --- a/docs/_static/images/vyos_arista_bond_lacp.png +++ /dev/null diff --git a/docs/_static/images/vyos_arista_bond_lacp.webp b/docs/_static/images/vyos_arista_bond_lacp.webp Binary files differnew file mode 100644 index 00000000..6ac71379 --- /dev/null +++ b/docs/_static/images/vyos_arista_bond_lacp.webp diff --git a/docs/_static/images/vyosnew-downloads.png b/docs/_static/images/vyosnew-downloads.png Binary files differdeleted file mode 100644 index 294a4589..00000000 --- a/docs/_static/images/vyosnew-downloads.png +++ /dev/null diff --git a/docs/_static/images/vyosnew-downloads.webp b/docs/_static/images/vyosnew-downloads.webp Binary files differnew file mode 100644 index 00000000..fbbb21c8 --- /dev/null +++ b/docs/_static/images/vyosnew-downloads.webp diff --git a/docs/_static/images/wireguard_qrcode.jpg b/docs/_static/images/wireguard_qrcode.jpg Binary files differdeleted file mode 100644 index 0a9a98c0..00000000 --- a/docs/_static/images/wireguard_qrcode.jpg +++ /dev/null diff --git a/docs/_static/images/wireguard_qrcode.webp b/docs/_static/images/wireguard_qrcode.webp Binary files differnew file mode 100644 index 00000000..7eb02d79 --- /dev/null +++ b/docs/_static/images/wireguard_qrcode.webp diff --git a/docs/_static/images/wireguard_site2site_diagram.jpg b/docs/_static/images/wireguard_site2site_diagram.jpg Binary files differdeleted file mode 100644 index fc305952..00000000 --- a/docs/_static/images/wireguard_site2site_diagram.jpg +++ /dev/null diff --git a/docs/_static/images/wireguard_site2site_diagram.webp b/docs/_static/images/wireguard_site2site_diagram.webp Binary files differnew file mode 100644 index 00000000..9f73ad4e --- /dev/null +++ b/docs/_static/images/wireguard_site2site_diagram.webp diff --git a/docs/_static/images/zone-policy-diagram.png b/docs/_static/images/zone-policy-diagram.png Binary files differdeleted file mode 100644 index 49e3e046..00000000 --- a/docs/_static/images/zone-policy-diagram.png +++ /dev/null diff --git a/docs/_static/images/zone-policy-diagram.webp b/docs/_static/images/zone-policy-diagram.webp Binary files differnew file mode 100644 index 00000000..850df285 --- /dev/null +++ b/docs/_static/images/zone-policy-diagram.webp diff --git a/docs/_swap.txt b/docs/_swap.txt new file mode 100644 index 00000000..274d072f --- /dev/null +++ b/docs/_swap.txt @@ -0,0 +1,214 @@ +# Incremental MyST swap list +# One page stem per line (relative to docs/, no extension) +# Pages listed here will render from MD instead of RST at build time. + +404 +automation/cloud-init +automation/command-scripting +automation/index +automation/terraform/index +automation/terraform/terraformAWS +automation/terraform/terraformAZ +automation/terraform/terraformGoogle +automation/terraform/terraformvSphere +automation/terraform/terraformvyos +automation/vyos-ansible +automation/vyos-api +automation/vyos-napalm +automation/vyos-netmiko +automation/vyos-salt +changelog/1.2.1 +changelog/1.2.2 +changelog/1.2.3 +changelog/1.2.4 +changelog/1.2.5 +changelog/1.2.6 +changelog/1.3 +changelog/1.4 +changelog/1.5 +changelog/index +configexamples/autotest/DHCPRelay_through_GRE/DHCPRelay_through_GRE +configexamples/autotest/L3VPN_EVPN/L3VPN_EVPN +configexamples/autotest/OpenVPN_with_LDAP/OpenVPN_with_LDAP +configexamples/autotest/Wireguard/Wireguard +configexamples/autotest/tunnelbroker/tunnelbroker +configexamples/azure-vpn-bgp +configexamples/azure-vpn-dual-bgp +configexamples/bgp-ipv6-unnumbered +configexamples/firewall +configexamples/fwall-and-vrf +configexamples/ha +configexamples/index +configexamples/inter-vrf-routing-vrf-lite +configexamples/ipsec-cisco-policy-based +configexamples/ipsec-cisco-route-based +configexamples/ipsec-pa-route-based +configexamples/l3vpn-hub-and-spoke +configexamples/lac-lns +configexamples/nmp +configexamples/ospf-unnumbered +configexamples/pppoe-ipv6-basic +configexamples/qos +configexamples/segment-routing-isis +configexamples/wan-load-balancing +configexamples/zone-policy +configuration/container/index +configuration/firewall/bridge +configuration/firewall/flowtables +configuration/firewall/global-options +configuration/firewall/groups +configuration/firewall/index +configuration/firewall/ipv4 +configuration/firewall/ipv6 +configuration/firewall/zone +configuration/highavailability/index +configuration/index +configuration/interfaces/bonding +configuration/interfaces/bridge +configuration/interfaces/dummy +configuration/interfaces/ethernet +configuration/interfaces/geneve +configuration/interfaces/index +configuration/interfaces/l2tpv3 +configuration/interfaces/loopback +configuration/interfaces/macsec +configuration/interfaces/openvpn +configuration/interfaces/pppoe +configuration/interfaces/pseudo-ethernet +configuration/interfaces/sstp-client +configuration/interfaces/tunnel +configuration/interfaces/virtual-ethernet +configuration/interfaces/vti +configuration/interfaces/vxlan +configuration/interfaces/wireguard +configuration/interfaces/wireless +configuration/interfaces/wwan +configuration/loadbalancing/index +configuration/loadbalancing/reverse-proxy +configuration/loadbalancing/wan +configuration/nat/index +configuration/nat/nat44 +configuration/nat/nat64 +configuration/nat/nat66 +configuration/pki/index +configuration/policy/access-list +configuration/policy/as-path-list +configuration/policy/community-list +configuration/policy/examples +configuration/policy/extcommunity-list +configuration/policy/index +configuration/policy/large-community-list +configuration/policy/local-route +configuration/policy/prefix-list +configuration/policy/route +configuration/policy/route-map +configuration/protocols/babel +configuration/protocols/bfd +configuration/protocols/bgp +configuration/protocols/failover +configuration/protocols/igmp-proxy +configuration/protocols/index +configuration/protocols/isis +configuration/protocols/mpls +configuration/protocols/ospf +configuration/protocols/pim +configuration/protocols/pim6 +configuration/protocols/rip +configuration/protocols/rpki +configuration/protocols/segment-routing +configuration/protocols/static +configuration/service/broadcast-relay +configuration/service/config-sync +configuration/service/conntrack-sync +configuration/service/console-server +configuration/service/dhcp-relay +configuration/service/dhcp-server +configuration/service/dns +configuration/service/eventhandler +configuration/service/https +configuration/service/ids +configuration/service/index +configuration/service/ipoe-server +configuration/service/lldp +configuration/service/mdns +configuration/service/monitoring +configuration/service/ntp +configuration/service/pppoe-server +configuration/service/router-advert +configuration/service/salt-minion +configuration/service/snmp +configuration/service/ssh +configuration/service/tftp-server +configuration/service/webproxy +configuration/system/acceleration +configuration/system/conntrack +configuration/system/console +configuration/system/default-route +configuration/system/flow-accounting +configuration/system/frr +configuration/system/host-name +configuration/system/index +configuration/system/ip +configuration/system/ipv6 +configuration/system/lcd +configuration/system/login +configuration/system/name-server +configuration/system/option +configuration/system/proxy +configuration/system/sflow +configuration/system/sysctl +configuration/system/syslog +configuration/system/task-scheduler +configuration/system/time-zone +configuration/system/updates +configuration/trafficpolicy/index +configuration/vpn/dmvpn +configuration/vpn/index +configuration/vpn/ipsec/index +configuration/vpn/ipsec/ipsec_general +configuration/vpn/ipsec/remoteaccess_ipsec +configuration/vpn/ipsec/site2site_ipsec +configuration/vpn/ipsec/troubleshooting_ipsec +configuration/vpn/l2tp +configuration/vpn/openconnect +configuration/vpn/pptp +configuration/vpn/rsa-keys +configuration/vpn/sstp +configuration/vrf/index +contributing/build-vyos +contributing/debugging +contributing/development +contributing/issues-features +contributing/testing +contributing/upstream-packages +coverage +documentation +index +installation/cloud/aws-ha +installation/cloud/aws-to-azure +installation/cloud/azure +installation/cloud/azure-ha +installation/cloud/gcp +installation/cloud/index +installation/cloud/oracel +installation/image +installation/index +installation/install +installation/update +installation/virtual/docker +installation/virtual/eve-ng +installation/virtual/gns3 +installation/virtual/index +installation/virtual/libvirt +installation/virtual/proxmox +installation/virtual/vmware +installation/vyos-on-baremetal +introducing/about +introducing/history +operation/boot-options +operation/index +operation/information +operation/password-recovery +operation/raid +quick-start +troubleshooting/index diff --git a/docs/automation/md-cloud-init.md b/docs/automation/md-cloud-init.md new file mode 100644 index 00000000..1b796c04 --- /dev/null +++ b/docs/automation/md-cloud-init.md @@ -0,0 +1,387 @@ +--- +lastproofread: '2021-07-12' +--- + +(cloud-init)= + +# VyOS cloud-init + +Cloud and virtualized instances of VyOS are initialized using the +industry-standard cloud-init. Via cloud-init, the system performs tasks such as +injecting SSH keys and configuring the network. In addition, the user can supply +a custom configuration at the time of instance launch. + +## Config Sources + +VyOS support three types of config sources. + +- Metadata - Metadata is sourced by the cloud platform or hypervisor. + In some clouds, there is implemented as an HTTP endpoint at + `http://169.254.169.254`. +- Network configuration - This config source informs the system about the + network settings like IP addresses, routes, DNS. Available only in several + cloud and virtualization platforms. +- User-data - User-data is specified by the user. This config source offers the + ability to insert any CLI configuration commands into the configuration before + the first boot. + +## User-data + +Major cloud providers offer a means of providing user-data at the time of +instance launch. It can be provided as plain text or as base64-encoded text, +depending on cloud provider. Also, it can be compressed using gzip, which makes +sense with a long configuration commands list, because of the hard limit to +\~16384 bytes for the whole user-data. + +The easiest way to configure the system via user-data is the Cloud-config syntax +described below. + +## Cloud-config modules + +In VyOS, by default, enables only two modules: + +- `write_files` - this module allows to insert any files into the filesystem + before the first boot, for example, pre-generated encryption keys, + certificates, or even a whole `config.boot` file. The format is described in the cloudinit documentation [Cloud-init-write_files]. +- `vyos_userdata` - the module accepts a list of CLI configuration commands in + a `vyos_config_commands` section, which gives an easy way to configure the + system during deployment. + +## cloud-config file format + +A cloud-config document is written in YAML. The file must begin +with `#cloud-config` line. The only supported top-level keys are +`vyos_config_commands` and `write_files`. The use of these keys is described +in the following two sections. + +## Initial Configuration + +The key used to designate a VyOS configuration is `vyos_config_commands`. +What follows is VyOS configuration using the "set-style" syntax. Both "set" +and "delete" commands are supported. + +Commands requirements: + +- One command per line. +- If command ends in a value, it must be inside single quotes. +- A single-quote symbol is not allowed inside command or value. + +The commands list produced by the `show configuration commands` command on a +VyOS router should comply with all the requirements, so it is easy to get a +proper commands list by copying it from another router. + +The configuration specified in the cloud-config document overwrites default +configuration values and values configured via Metadata. + +Here is an example cloud-config that appends configuration at the time of +first boot. + +```yaml +#cloud-config +vyos_config_commands: + - set system host-name 'vyos-prod-ashburn' + - set service ntp server 1.pool.ntp.org + - set service ntp server 2.pool.ntp.org + - delete interfaces ethernet eth1 address 'dhcp' + - set interfaces ethernet eth1 address '192.0.2.247/24' + - set protocols static route 198.51.100.0/24 next-hop '192.0.2.1' +``` + +### System Defaults/Fallbacks + +These are the VyOS defaults and fallbacks. + +- SSH is configured on port 22. +- `vyos`/`vyos` credentials if no others specified by data source. +- DHCP on first Ethernet interface if no network configuration is provided. + +All of these can be overridden using the configuration in user-data. + +## Command Execution at Initial Boot + +VyOS supports the execution of operational commands and linux commands at +initial boot. This is accomplished using `write_files` to certain +files in the /opt/vyatta/etc/config/scripts directory. Commands specified +in opt/vyatta/etc/config/scripts/vyos-preconfig-bootup.script are executed +prior to configuration. The +/opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script file contains +commands to be executed after configuration. In both cases, commands are +executed as the root user. + +Note that the /opt/vyatta/etc/config is used instead of the /config/scripts +directory referenced in the {ref}`command-scripting` section of the +documentation because the /config/script directory isn't mounted when the +`write_files` module executes. + +The following example shows how to execute commands after the initial +configuration. + +```yaml +#cloud-config +write_files: + - path: /opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script + owner: root:vyattacfg + permissions: '0775' + content: | + #!/bin/vbash + source /opt/vyatta/etc/functions/script-template + filename=/tmp/bgp_status_`date +"%Y_%m_%d_%I_%M_%p"`.log + run show ip bgp summary >> $filename +``` + +If you need to gather information from linux commands to configure VyOS, you +can execute commands and then configure VyOS in the same script. + +The following example sets the hostname based on the instance identifier +obtained from the EC2 metadata service. + +Please observe that the same configuration pitfall described in {ref}`command-scripting` +exists here when running `configure` in any context as without user group +'vyattacfg' will cause the error message `Set failed` to appear. +We therefore need to wrap it and have the script re-execute itself with the correct +group permissions. + +```yaml +#cloud-config +write_files: + - path: /opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script + owner: root:vyattacfg + permissions: '0775' + content: | + #!/bin/vbash + if [ "$(id -g -n)" != 'vyattacfg' ] ; then + exec sg vyattacfg -c "/bin/vbash $(readlink -f $0) $@" + fi + source /opt/vyatta/etc/functions/script-template + hostname=`curl -s http://169.254.169.254/latest/meta-data/instance-id` + configure + set system host-name $hostname + commit + exit +``` + +## NoCloud + +Injecting configuration data is not limited to cloud platforms. Users can +employ the NoCloud data source to inject user-data and meta-data on +virtualization platforms such as VMware, Hyper-V and KVM. + +While other methods exist, the most straightforward method for using the +NoCloud data source is creating a seed ISO and attaching it to the virtual +machine as a CD drive. The volume must be formatted as a vfat or ISO 9660 +file system with the label "cidata" or "CIDATA". + +Create text files named user-data and meta-data. On linux-based systems, +the mkisofs utility can be used to create the seed ISO. The following +syntax will add these files to the ISO 9660 file system. + +```none +mkisofs -joliet -rock -volid "cidata" -output seed.iso meta-data user-data +``` + +The seed.iso file can be attached to the virtual machine. As an example, +the method with KVM to attach the ISO as a CD drive follows. + +```none +$ virt-install -n vyos_r1 \ + --ram 4096 \ + --vcpus 2 \ + --cdrom seed.iso \ + --os-type linux \ + --os-variant debian10 \ + --network network=default \ + --graphics vnc \ + --hvm \ + --virt-type kvm \ + --disk path=/var/lib/libvirt/images/vyos_kvm.qcow2,bus=virtio \ + --import \ + --noautoconsole +``` + +For more information on the NoCloud data source, visit its [page](https://cloudinit.readthedocs.io/en/latest/reference/datasources/nocloud.html) +in the cloud-init documentation. + +## Troubleshooting + +If you encounter problems, verify that the cloud-config document contains +valid YAML. Online resources such as <https://www.yamllint.com/> provide +a simple tool for validating YAML. + +cloud-init logs to /var/log/cloud-init.log. This file can be helpful in +determining why the configuration varies from what you expect. You can fetch the +most important data filtering output for `vyos` keyword: + +```none +sudo grep vyos /var/log/cloud-init.log +``` + +## Cloud-init on Proxmox + +Before starting, please refer to cloud-init [network-config-docs] in order to +know how to import user and network configurations. + +Most important keys that needs to be considered: + +- VyOS configuration commands are defined in user-data file. + +- Networking configurations shouldn't be passed in user-data file. + +- If no networking configuration is provided, then dhcp client is going to be + enabled on first interface. Bare in mind that this configuration will be + inyected at an OS level, so don't expect to find dhcp client configuration + on vyos cli. Because of this behavior, in next example lab we will disable + dhcp-client configuration on eth0. + + Also, this lab considers: + +- Proxmox IP address: **192.168.0.253/24** + +- Storaged used: volume local, which is mounted on directory **/var/lib/vz**, + and contains all type of content, including snippets. + +- Remove default dhcp client on first interface, and load other + configuration during first boot, using cloud-init. + +### Generate qcow image + +A VyOS qcow image with cloud-init options is needed. This can be obtained +using [vyos-vm-images] repo. After cloning the repo, edit the file +**qemu.yml** and comment the **download-iso** role. + +In this lab, we are using 1.3.0 VyOS version and setting a disk of 10G. +Download VyOS .iso file and save it as `/tmp/vyos.iso`. Command used for +generating qcow image: + +```sh +sudo ansible-playbook qemu.yml -e disk_size=10 \ + -e iso_local=/tmp/vyos.iso -e grub_console=serial -e vyos_version=1.3.0 \ + -e cloud_init=true -e cloud_init_ds=NoCloud +``` + +File generated with previous command: +`/tmp/vyos-1.3.0-cloud-init-10G-qemu.qcow2` + +Now, that file needs to be copied to proxmox server: + +```sh +sudo scp /tmp/vyos-1.3.0-cloud-init-10G-qemu.qcow2 root@192.168.0.253:/tmp/ +``` + +### Prepare cloud-init files + +In Proxmox server three files are going to be used for this setup: + +- **network-config**: file that will indicate to avoid dhcp client on first + interface. +- **user-data**: includes vyos-commands. +- **meta-data**: empty file (required). + +In this lab, all files are located in `/tmp/`. So, before going on, lets +move to that directory: + +```sh +cd /tmp/ +``` + +**user-data** file must start with `#cloud-config` and contains +vyos-commands. For example: + +```none +#cloud-config +vyos_config_commands: + - set system host-name 'vyos-BRAS' + - set service ntp server 1.pool.ntp.org + - set service ntp server 2.pool.ntp.org + - delete interfaces ethernet eth0 address 'dhcp' + - set interfaces ethernet eth0 address '198.51.100.2/30' + - set interfaces ethernet eth0 description 'WAN - ISP01' + - set interfaces ethernet eth1 address '192.168.25.1/24' + - set interfaces ethernet eth1 description 'Comming through VLAN 25' + - set interfaces ethernet eth2 address '192.168.26.1/24' + - set interfaces ethernet eth2 description 'Comming through VLAN 26' + - set protocols static route 0.0.0.0/0 next-hop '198.51.100.1' +``` + +**network-config** file only has configuration that disables the automatic +dhcp client on first interface. + +Content of network-config file: + +```none +version: 2 +ethernets: + eth0: + dhcp4: false + dhcp6: false +``` + +Finally, file **meta-data** has no content, but it's required. + +### Create seed.iso + +Once the three files were created, it's time to generate the `seed.iso` +image, which needs to be mounted to the new VM as a cd. + +Command for generating `seed.iso` + +```sh +mkisofs -joliet -rock -volid "cidata" -output seed.iso meta-data \ +user-data network-config +``` + +**NOTE**: be careful while copying and pasting previous commands. Double +quotes may need to be corrected. + +### Creating the VM + +Notes for this particular example, that may need to be modified in other +setups: + +- VM ID: in this example, VM ID used is 555. +- VM Storage: `local` volume is used. +- ISO files storage: `local` volume is used for `.iso` file storage. In + this scenario `local` volume type is set to **directory**, abd attached to + `/var/lib/vz`. +- VM Resources: these parameters can be modified as needed. + +`seed.iso` was previously created in directory `/tmp/`. It's necessary to +move it to `/var/lib/vz/template/iso` + +```sh +mv /tmp/seed.iso /var/lib/vz/template/iso/ +``` + +On proxmox server: + +```none +## Create VM, import disk and define boot order +qm create 555 --name vyos-1.3.0-cloudinit --memory 1024 --net0 virtio,bridge=vmbr0 +qm importdisk 555 vyos-1.3.0-cloud-init-10G-qemu.qcow2 local +qm set 555 --virtio0 local:555/vm-555-disk-0.raw +qm set 555 --boot order=virtio0 + +## Import seed.iso for cloud init +qm set 555 --ide2 media=cdrom,file=local:iso/seed.iso + +## Since this server has 1 nic, lets add network intefaces (vlan 25 and 26) +qm set 555 --net1 virtio,bridge=vmbr0,firewall=1,tag=25 +qm set 555 --net2 virtio,bridge=vmbr0,firewall=1,tag=26 +``` + +### Power on VM and verifications + +From cli or GUI, power on VM, and after it boots, verify configuration + +### References + +- VyOS [cloud-init-docs]. +- Cloud-init [network-config-docs]. +- Proxmox [Cloud-init-Support]. + + + +[cloud-init-docs]: https://docs.vyos.io/en/equuleus/automation/cloud-init.html?highlight=cloud-init#vyos-cloud-init +[cloud-init-support]: https://pve.proxmox.com/pve-docs/pve-admin-guide.html#qm_cloud_init +[cloud-init-write_files]: https://cloudinit.readthedocs.io/en/latest/topics/examples.html#writing-out-arbitrary-files +[network-config-docs]: https://cloudinit.readthedocs.io/en/latest/topics/network-config.html +[vyos-vm-images]: https://github.com/vyos/vyos-vm-images diff --git a/docs/automation/md-command-scripting.md b/docs/automation/md-command-scripting.md new file mode 100644 index 00000000..941ba744 --- /dev/null +++ b/docs/automation/md-command-scripting.md @@ -0,0 +1,207 @@ +--- +lastproofread: '2023-01-16' +--- + +(command-scripting)= + +# Command Scripting + +VyOS supports executing configuration and operational commands non-interactively +from shell scripts. + +To include VyOS specific functions and aliases you need to `source +/opt/vyatta/etc/functions/script-template` files at the top of your script. + +```none +#!/bin/vbash +source /opt/vyatta/etc/functions/script-template +exit +``` + +## Run configuration commands + +Configuration commands are executed just like from a normal config session. For +example, if you want to disable a BGP peer on VRRP transition to backup: + +```none +#!/bin/vbash +source /opt/vyatta/etc/functions/script-template +configure +set protocols bgp system-as 65536 +set protocols bgp neighbor 192.168.2.1 shutdown +commit +exit +``` + +## Run operational commands + +Unlike a normal configuration session, all operational commands must be +prepended with `run`, even if you haven't created a session with configure. + +```none +#!/bin/vbash +source /opt/vyatta/etc/functions/script-template +run show interfaces +exit +``` + +## Run commands remotely + +Sometimes you simply want to execute a bunch of op-mode commands via SSH on +a remote VyOS system. + +```none +ssh 192.0.2.1 'vbash -s' <<EOF +source /opt/vyatta/etc/functions/script-template +run show interfaces +exit +EOF +``` + +Will return: + +```none +Welcome to VyOS +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +eth0 192.0.2.1/24 u/u +lo 127.0.0.1/8 u/u + ::1/128 +``` + +## Other script languages + +If you want to script the configs in a language other than bash you can have +your script output commands and then source them in a bash script. + +Here is a simple example: + +```python +#!/usr/bin/env python3 +print("delete firewall group address-group somehosts") +print("set firewall group address-group somehosts address '192.0.2.3'") +print("set firewall group address-group somehosts address '203.0.113.55'") +``` + +```none +#!/bin/vbash +source /opt/vyatta/etc/functions/script-template +configure +source < /config/scripts/setfirewallgroup.py +commit +``` + +## Executing Configuration Scripts + +There is a pitfall when working with configuration scripts. It is tempting to +call configuration scripts with "sudo" (i.e., temporary root permissions), +because that's the common way on most Linux platforms to call system commands. + +On VyOS this will cause the following problem: After modifying the configuration +via script like this once, it is not possible to manually modify the config +anymore: + +```none +sudo ./myscript.sh # Modifies config +configure +set ... # Any configuration parameter +``` + +This will result in the following error message: `Set failed` If this happens, +a reboot is required to be able to edit the config manually again. + +To avoid these problems, the proper way is to call a script with the +`vyattacfg` group, e.g., by using the `sg` (switch group) command: + +```none +sg vyattacfg -c ./myscript.sh +``` + +To make sure that a script is not accidentally called without the `vyattacfg` +group, the script can be safeguarded like this: + +```none +if [ "$(id -g -n)" != 'vyattacfg' ] ; then + exec sg vyattacfg -c "/bin/vbash $(readlink -f $0) $@" +fi +``` + +## Executing pre-hooks/post-hooks Scripts + +VyOS has the ability to run custom scripts before and after each commit + +The default directories where your custom Scripts should be located are: + +```none +/config/scripts/commit/pre-hooks.d - Directory with scripts that run before + each commit. + +/config/scripts/commit/post-hooks.d - Directory with scripts that run after + each commit. +``` + +Scripts are run in alphabetical order. Their names must consist entirely of +ASCII upper- and lower-case letters,ASCII digits, ASCII underscores, and +ASCII minus-hyphens.No other characters are allowed. + +:::{note} +Custom scripts are not executed with root privileges +(Use sudo inside if this is necessary). +::: + +A simple example is shown below, where the ops command executed in +the post-hook script is "show interfaces". + +```none +vyos@vyos# set interfaces ethernet eth1 address 192.0.2.3/24 +vyos@vyos# commit +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +eth0 198.51.100.10/24 u/u +eth1 192.0.2.3/24 u/u +eth2 - u/u +eth3 - u/u +lo 203.0.113.5/24 u/u +``` + +## Preconfig on boot + +The `/config/scripts/vyos-preconfig-bootup.script` script is called on boot +before the VyOS configuration during boot process. + +Any modifications were done to work around unfixed bugs and implement +enhancements that are not complete in the VyOS system can be placed here. + +The default file looks like this: + +```none +#!/bin/sh +# This script is executed at boot time before VyOS configuration is applied. +# Any modifications required to work around unfixed bugs or use +# services not available through the VyOS CLI system can be placed here. +``` + +## Postconfig on boot + +The `/config/scripts/vyos-postconfig-bootup.script` script is called on boot +after the VyOS configuration is fully applied. + +Any modifications were done to work around unfixed bugs and implement +enhancements that are not complete in the VyOS system can be placed here. + +The default file looks like this: + +```none +#!/bin/sh +# This script is executed at boot time after VyOS configuration is fully +# applied. Any modifications required to work around unfixed bugs or use +# services not available through the VyOS CLI system can be placed here. +``` + +:::{hint} +For configuration/upgrade management issues, modification of this +script should be the last option. Always try to find solutions based on CLI +commands first. +::: diff --git a/docs/automation/md-index.md b/docs/automation/md-index.md new file mode 100644 index 00000000..1296c160 --- /dev/null +++ b/docs/automation/md-index.md @@ -0,0 +1,15 @@ +# VyOS Automation + +```{eval-rst} +.. toctree:: + :maxdepth: 2 + + vyos-api + vyos-ansible + terraform/index + vyos-napalm + vyos-netmiko + vyos-salt + command-scripting + cloud-init +``` diff --git a/docs/automation/md-vyos-ansible.md b/docs/automation/md-vyos-ansible.md new file mode 100644 index 00000000..64efddb3 --- /dev/null +++ b/docs/automation/md-vyos-ansible.md @@ -0,0 +1,89 @@ +--- +lastproofread: '2023-01-16' +--- + +(vyos-ansible)= + +# Ansible + +VyOS supports configuration via ansible. +Need to install `ansible` and `python3-paramiko` module + +Structure of files + +```none +. +├── ansible.cfg +├── files +│ └── id_rsa_docker.pub +├── hosts +└── main.yml +``` + +## File contents + +ansible.cfg + +```none +[defaults] +host_key_checking = no +retry_files_enabled = False +ANSIBLE_INVENTORY_UNPARSED_FAILED = true +``` + +id_rsa_docker.pub. Needs to declare only public key exactly. + +```none +AAAAB3NzaC1yc2EAAAADAQABAAABAQCoDgfhQJuJRFWJijHn7ZinZ3NWp4hWVrt7HFcvn0kgtP/5PeCtMt +``` + +hosts + +```none +[vyos_hosts] +r11 ansible_ssh_host=192.0.2.11 + +[vyos_hosts:vars] +ansible_python_interpreter=/usr/bin/python3 +ansible_user=vyos +ansible_ssh_pass=vyos +ansible_network_os=vyos +ansible_connection=network_cli +``` + +main.yml + +```none +--- + +- hosts: r11 + + connection: network_cli + gather_facts: 'no' + + tasks: + - name: Configure remote r11 + vyos_config: + lines: + - set system host-name r11 + - set system name-server 203.0.113.254 + - set service ssh disable-host-validation + - set system login user vyos authentication public-keys docker@work type ssh-rsa + - set system login user vyos authentication public-keys docker@work key "{{ lookup('file', 'id_rsa_docker.pub') }}" + - set system time-zone America/Los_Angeles + - set interfaces ethernet eth0 description WAN +``` + +## Run ansible + +```none +$ ansible-playbook -i hosts main.yml + +PLAY [r11] ****************************************************************************************************************************************************************************************************** + +TASK [Configure remote r11] ************************************************************************************************************************************************************************************* +changed: [r11] + +PLAY RECAP ***************************************************************************************************************************************************************************************************** +r11 : ok=1 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 +``` diff --git a/docs/automation/md-vyos-api.md b/docs/automation/md-vyos-api.md new file mode 100644 index 00000000..df26aed9 --- /dev/null +++ b/docs/automation/md-vyos-api.md @@ -0,0 +1,383 @@ +--- +lastproofread: '2023-01-16' +--- + +(vyosapi)= + +# VyOS API + +For configuration and enabling the API see {ref}`http-api` + +## Authentication + +All endpoints only listen on HTTP POST requests and the API KEY must set as +`key` in the formdata. + +Below see one example for curl and one for python. +The rest of the documentation is reduced to curl. + +```none +curl --location --request POST 'https://vyos/retrieve' \ +--form data='{"op": "showConfig", "path": []}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' +``` + +```python +import requests +url = "https://vyos/retrieve" +payload={'data': '{"op": "showConfig", "path": []}', + 'key': 'MY-HTTPS-API-PLAINTEXT-KEY' + } +headers = {} +response = requests.request("POST", url, headers=headers, data=payload) +print(response.text) +``` + +## API Endpoints + +### /retrieve + +With the `retrieve` endpoint you get parts or the whole configuration. + +To get the whole configuration, pass an empty list to the `path` field + +```none +curl --location --request POST 'https://vyos/retrieve' \ +--form data='{"op": "showConfig", "path": []}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + + +response (shorted) +{ + "success": true, + "data": { + "interfaces": { + "ethernet": { + "eth0": { + "address": "dhcp", + "duplex": "auto", + "hw-id": "50:00:00:01:00:00", + "speed": "auto" + }, + "eth1": { + "duplex": "auto", + "hw-id": "50:00:00:01:00:01", + "speed": "auto" + ... + }, + "error": null +} +``` + +To only get a part of the configuration, for example `system syslog`. + +```none +curl -k --location --request POST 'https://vyos/retrieve' \ +--form data='{"op": "showConfig", "path": ["system", "syslog"]}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + + +response: +{ + "success": true, + "data": { + "global": { + "facility": { + "all": { + "level": "info" + }, + "protocols": { + "level": "debug" + } + } + } + }, + "error": null +} +``` + +if you just want the Value of a multi-valued node, use the `returnValues` +operation. + +For example, get the addresses of a `dum0` interface. + +```none +curl -k --location --request POST 'https://vyos/retrieve' \ +--form data='{"op": "returnValues", "path": ["interfaces","dummy","dum0","address"]}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +respone: +{ + "success": true, + "data": [ + "10.10.10.10/24", + "10.10.10.11/24", + "10.10.10.12/24" + ], + "error": null +} +``` + +To check existence of a configuration path, use the `exists` operation. + +For example, check an existing path: + +```none +curl -k --location --request POST 'https://vyos/retrieve' \ +--form data='{"op": "exists", "path": ["service","https","api"]}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +response: +{ + "success": true, + "data": true, + "error": null +} +``` + +versus a non-existent path: + +```none +curl -k --location --request POST 'https://vyos/retrieve' \ +--form data='{"op": "exists", "path": ["service","non","existent","path"]}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +response: +{ + "success": true, + "data": false, + "error": null +} +``` + +### /reset + +The `reset` endpoint run a `reset` command. + +```none +curl --location --request POST 'https://vyos/reset' \ +--form data='{"op": "reset", "path": ["ip", "bgp", "192.0.2.11"]}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +respone: +{ + "success": true, + "data": "", + "error": null +} +``` + +### /reboot + +To initiate a reboot use the `reboot` endpoint. + +```none +curl --location --request POST 'https://vyos/reboot' \ +--form data='{"op": "reboot", "path": ["now"]}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +respone: +{ + "success": true, + "data": "", + "error": null +} +``` + +### /poweroff + +To power off the system use the `poweroff` endpoint. + +```none +curl --location --request POST 'https://vyos/poweroff' \ +--form data='{"op": "poweroff", "path": ["now"]}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +respone: +{ + "success": true, + "data": "", + "error": null +} +``` + +### /image + +To add or delete an image, use the `/image` endpoint. + +add an image + +```none +curl -k --location --request POST 'https://vyos/image' \ +--form data='{"op": "add", "url": "https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso"}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +respone (shorted): +{ + "success": true, + "data": "Trying to fetch ISO file from https://downloads.vyos.io/rolling-latest.iso\n + ... + Setting up grub configuration...\nDone.\n", + "error": null +} +``` + +delete an image, for example `1.3-rolling-202006070117` + +```none +curl -k --location --request POST 'https://vyos/image' \ +--form data='{"op": "delete", "name": "1.3-rolling-202006070117"}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +response: +{ + "success": true, + "data": "Deleting the \"1.3-rolling-202006070117\" image...\nDone\n", + "error": null +} +``` + +### /show + +The `/show` endpoint is to show everything in the operational mode. + +For example, show which images are installed. + +```none +curl -k --location --request POST 'https://vyos/show' \ +--form data='{"op": "show", "path": ["system", "image"]}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +response: +{ + "success": true, + "data": "The system currently has the following image(s) installed:\n\n + 1: 1.4-rolling-202102280559 (default boot)\n + 2: 1.4-rolling-202102230218\n + 3: 1.3-beta-202102210443\n\n", + "error": null +} +``` + +### /generate + +The `generate` endpoint run a `generate` command. + +```none +curl -k --location --request POST 'https://vyos/generate' \ +--form data='{"op": "generate", "path": ["pki", "wireguard", "key-pair"]}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +response: +{ + "success": true, + "data": "Private key: CFZR2eyhoVZwk4n3JFPMJx3E145f1EYgDM+ubytXYVY=\n + Public key: jjtpPT8ycI1Q0bNtrWuxAkO4k88Xwzg5VHV9xGZ58lU=\n\n", + "error": null +} +``` + +### /configure + +You can pass a `set`, `delete` or `comment` command to the +`/configure` endpoint. + +`set` a single command + +```none +curl -k --location --request POST 'https://vyos/configure' \ +--form data='{"op": "set", "path": ["interfaces", "dummy", "dum1", "address", "10.11.0.1/32"]}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +response: +{ + "success": true, + "data": null, + "error": null +} +``` + +`delete` a single command + +```none +curl -k --location --request POST 'https://vyos/configure' \ +--form data='{"op": "delete", "path": ["interfaces", "dummy", "dum1", "address", "10.11.0.1/32"]}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +response: +{ + "success": true, + "data": null, + "error": null +} +``` + +The API pushes every request to a session and commit it. +But some of VyOS components like DHCP and PPPoE Servers, IPSec, VXLAN, and +other tunnels require full configuration for commit. +The endpoint will process multiple commands when you pass them as a list to +the `data` field. + +```none +curl -k --location --request POST 'https://vyos/configure' \ +--form data='[{"op": "set","path":["interfaces","vxlan","vxlan1","remote","203.0.113.99"]}, {"op": "set","path":["interfaces","vxlan","vxlan1","vni","1"]}]' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +response: +{ + "success": true, + "data": null, + "error": null +} +``` + +### /config-file + +The endpoint `/config-file` is to save or load a configuration. + +Save a running configuration to the startup configuration. +When you don't specify the file when saving, it saves to +`/config/config.boot`. + +```none +curl -k --location --request POST 'https://vyos/config-file' \ +--form data='{"op": "save"}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +response: +{ + "success": true, + "data": "Saving configuration to '/config/config.boot'...\nDone\n", + "error": null +} +``` + +Save a running configuration to a file. + +```none +curl -k --location --request POST 'https://vyos/config-file' \ +--form data='{"op": "save", "file": "/config/test.config"}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +response: +{ + "success": true, + "data": "Saving configuration to '/config/test.config'...\nDone\n", + "error": null +} +``` + +To Load a configuration file. + +```none +curl -k --location --request POST 'https://vyos/config-file' \ +--form data='{"op": "load", "file": "/config/test.config"}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +response: +{ + "success": true, + "data": null, + "error": null +} +``` diff --git a/docs/automation/md-vyos-napalm.md b/docs/automation/md-vyos-napalm.md new file mode 100644 index 00000000..8ca78813 --- /dev/null +++ b/docs/automation/md-vyos-napalm.md @@ -0,0 +1,142 @@ +--- +lastproofread: '2023-01-16' +--- + +(vyos-napalm)= + +# Napalm + +VyOS supports some [napalm] functions for configuration and op-mode. +It requires more tests. + +Install `napalm-vyos` module + +```none +apt install python3-pip +pip3 install napalm +pip3 install napalm-vyos +``` + +## Op-mode + +```none +#!/usr/bin/env python3 + +import json +from napalm import get_network_driver + +driver = get_network_driver('vyos') + +vyos_router = driver( + hostname="192.0.2.1", + username="vyos", + password="vyospass", + optional_args={"port": 22}, +) + +vyos_router.open() +output = vyos_router.get_facts() +print(json.dumps(output, indent=4)) + +output = vyos_router.get_arp_table() +print(json.dumps(output, indent=4)) + +vyos_router.close() +``` + +Output op-mode + +```none +$ ./vyos-napalm.py +{ + "uptime": 7185, + "vendor": "VyOS", + "os_version": "1.3.0-rc5", + "serial_number": "", + "model": "Standard PC (Q35 + ICH9, 2009)", + "hostname": "r4-1.3", + "fqdn": "vyos.local", + "interface_list": [ + "eth0", + "eth1", + "eth2", + "lo", + "vtun10" + ] +} +[ + { + "interface": "eth1", + "mac": "52:54:00:b2:38:2c", + "ip": "192.0.2.2", + "age": 0.0 + }, + { + "interface": "eth0", + "mac": "52:54:00:a2:b9:5b", + "ip": "203.0.113.11", + "age": 0.0 + } +] +``` + +## Configuration + +We need 2 files, commands.conf and script itself. + +Content of commands.conf + +```none +set service ssh disable-host-validation +set service ssh port '2222' +set system name-server '192.0.2.8' +set system name-server '203.0.113.8' +set interfaces ethernet eth1 description 'FOO' +``` + +Script vyos-napalm.py + +```none +#!/usr/bin/env python3 + +from napalm import get_network_driver + +driver = get_network_driver('vyos') + +vyos_router = driver( + hostname="192.0.2.1", + username="vyos", + password="vyospass", + optional_args={"port": 22}, +) + +vyos_router.open() +vyos_router.load_merge_candidate(filename='commands.conf') +diffs = vyos_router.compare_config() + +if bool(diffs) == True: + print(diffs) + vyos_router.commit_config() +else: + print('No configuration changes to commit') + vyos_router.discard_config() + +vyos_router.close() +``` + +Output + +```none +$./vyos-napalm.py +[edit interfaces ethernet eth1] ++description FOO +[edit service ssh] ++disable-host-validation ++port 2222 +[edit system] ++name-server 192.0.2.8 ++name-server 203.0.113.8 +[edit] +``` + +[napalm]: https://napalm.readthedocs.io/en/latest/base.html diff --git a/docs/automation/md-vyos-netmiko.md b/docs/automation/md-vyos-netmiko.md new file mode 100644 index 00000000..da042b6c --- /dev/null +++ b/docs/automation/md-vyos-netmiko.md @@ -0,0 +1,72 @@ +--- +lastproofread: '2023-01-16' +--- + +(vyos-netmiko)= + +# Netmiko + +VyOS supports configuration via [netmiko]. +It requires to install `python3-netmiko` module. + +## Example + +```none +#!/usr/bin/env python3 + +from netmiko import ConnectHandler + +vyos_router = { + "device_type": "vyos", + "host": "192.0.2.1", + "username": "vyos", + "password": "vyospass", + "port": 22, + } + +net_connect = ConnectHandler(**vyos_router) + +config_commands = [ + 'set interfaces ethernet eth0 description WAN', + 'set interfaces ethernet eth1 description LAN', + ] + +# set configuration +output = net_connect.send_config_set(config_commands, exit_config_mode=False) +print(output) + +# commit configuration +output = net_connect.commit() +print(output) + +# op-mode commands +output = net_connect.send_command("run show interfaces") +print(output) +``` + +Output + +```none +$ ./vyos-netmiko.py +configure +set interfaces ethernet eth0 description WAN +[edit] +vyos@r4-1.3# set interfaces ethernet eth1 description LAN +[edit] +vyos@r4-1.3# +commit +[edit] +vyos@r4-1.3# +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +eth0 203.0.113.1/24 u/u WAN +eth1 192.0.2.1/30 u/u LAN +eth2 - u/u +lo 127.0.0.1/8 u/u + ::1/128 +vtun10 10.10.0.1/24 u/u +[edit] +``` + +[netmiko]: https://github.com/ktbyers/netmiko diff --git a/docs/automation/md-vyos-salt.md b/docs/automation/md-vyos-salt.md new file mode 100644 index 00000000..42e7bd6e --- /dev/null +++ b/docs/automation/md-vyos-salt.md @@ -0,0 +1,209 @@ +--- +lastproofread: '2023-01-16' +--- + +(vyos-salt)= + +```{include} /_include/need_improvement.txt +``` + +# Salt + +VyOS supports op-mode and configuration via [salt]. + +Without proxy it requires VyOS minion configuration +and supports op-mode data: + +```none +set service salt-minion id 'r14' +set service salt-minion master '192.0.2.250' +``` + +Check salt-keys on the salt master + +```none +/ # salt-key --list-all +Accepted Keys: +r11 +Denied Keys: +Unaccepted Keys: +r14 +Rejected Keys: +``` + +Accept minion key + +```none +/ # salt-key --accept r14 +The following keys are going to be accepted: +Unaccepted Keys: +r14 +Proceed? [n/Y] y +Key for minion r14 accepted. +``` + +Check that salt master can communicate with minions + +```none +/ # salt '*' test.ping +r14: + True +r11: + True +``` + +At this step we can get some op-mode information from VyOS nodes: + +```none +/ # salt '*' network.interface eth0 +r11: + |_ + ---------- + address: + 192.0.2.11 + broadcast: + 192.0.2.255 + label: + eth0 + netmask: + 255.255.255.0 +r14: + |_ + ---------- + address: + 192.0.2.14 + broadcast: + 192.0.2.255 + label: + eth0 + netmask: + 255.255.255.0 + + +/ # salt r14 network.arp +r14: + ---------- + aa:bb:cc:dd:f3:db: + 192.0.2.1 + aa:bb:cc:dd:2e:80: + 203.0.113.1 +``` + +## Netmiko-proxy + +It is possible to configure VyOS via [netmiko] proxy module. +It requires a minion with installed packet `python3-netmiko` module +who has a connection to VyOS nodes. Salt-minion have to communicate +with salt master + +### Configuration + +Salt master configuration: + +```none +/ # cat /etc/salt/master +file_roots: + base: + - /srv/salt/states + +pillar_roots: + base: + - /srv/salt/pillars +``` + +Structure of /srv/salt: + +```none +/ # tree /srv/salt/ +/srv/salt/ +|___ pillars +| |__ r11-proxy.sls +| |__ top.sls +|___ states + |__ commands.txt +``` + +top.sls + +```none +/ # cat /srv/salt/pillars/top.sls +base: + r11-proxy: + - r11-proxy +``` + +r11-proxy.sls Includes parameters for connecting to salt-proxy minion + +```none +/ # cat /srv/salt/pillars/r11-proxy.sls +proxy: + proxytype: netmiko # how to connect to proxy minion, change it + device_type: vyos # + host: 192.0.2.250 + username: user + password: secret_passwd +``` + +commands.txt + +```none +/ # cat /srv/salt/states/commands.txt +set interfaces ethernet eth0 description 'WAN' +set interfaces ethernet eth1 description 'LAN' +``` + +Check that proxy minion is alive: + +```none +/ # salt r11-proxy test.ping +r11-proxy: + True +/ # +``` + +### Examples + +Example of op-mode: + +```none +/ # salt r11-proxy netmiko.send_command 'show interfaces ethernet eth0 brief' host=192.0.2.14 device_type=vyos username=vyos password=vyos +r11-proxy: + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 192.0.2.14/24 u/u Upstream +/ # +``` + +Example of configuration: + +```none +/ # salt r11-proxy netmiko.send_config config_commands=['set interfaces ethernet eth0 description Link_to_WAN'] commit=True host=192.0.2.14 device_type=vyos username=vyos password=vyos +r11-proxy: + configure + set interfaces ethernet eth0 description Link_to_WAN + [edit] + vyos@r14# commit + [edit] + vyos@r14# +/ # +``` + +Example of configuration commands from the file "/srv/salt/states/commands.txt" + +```none +/ # salt r11-proxy netmiko.send_config config_file=salt://commands.txt commit=True host=192.0.2.11 device_type=vyos username=vyos password=vyos +r11-proxy: + configure + set interfaces ethernet eth0 description 'WAN' + [edit] + vyos@r1# set interfaces ethernet eth1 description 'LAN' + [edit] + vyos@r1# commit + [edit] + vyos@r1# +/ # +``` + +[netmiko]: https://docs.saltproject.io/en/latest/ref/modules/all/salt.modules.netmiko_mod.html#module-salt.modules.netmiko_mod +[salt]: https://docs.saltproject.io/en/latest/contents.html diff --git a/docs/automation/terraform/md-index.md b/docs/automation/terraform/md-index.md new file mode 100644 index 00000000..6cadd918 --- /dev/null +++ b/docs/automation/terraform/md-index.md @@ -0,0 +1,13 @@ +# VyOS Terraform + +```{eval-rst} +.. toctree:: + :maxdepth: 1 + :caption: Content + + terraformvyos + terraformAWS + terraformAZ + terraformvSphere + terraformGoogle +``` diff --git a/docs/automation/terraform/md-terraformAWS.md b/docs/automation/terraform/md-terraformAWS.md new file mode 100644 index 00000000..4a29fba3 --- /dev/null +++ b/docs/automation/terraform/md-terraformAWS.md @@ -0,0 +1,519 @@ +--- +lastproofread: '2024-01-11' +--- + +(terraformaws)= + +# Deploying VyOS in the AWS cloud + +With the help of Terraform, you can quickly deploy VyOS-based infrastructure in the AWS cloud. If necessary, the infrastructure can be removed using terraform. +Also we will make provisioning using Ansible. + +```{image} /_static/images/aws.png +:align: center +:alt: Network Topology Diagram +:width: 50% +``` + +In this case, we'll create the necessary files for Terraform and Ansible next using Terraform we'll create a single instance on the AWS cloud and make provisioning using Ansible. + +## Preparation steps for deploying VyOS on AWS + +How to create a single instance and install your configuration using Terraform+Ansible+AWS +Step by step: + +AWS + +1 Create an account with AWS and get your "access_key", "secret key" + +2 Create a key [pair] and download your .pem key + +```{image} /_static/images/keypairs.png +:align: center +:alt: Network Topology Diagram +:width: 50% +``` + +3 Create a security [group] for the new VyOS instance and open all traffic + +```{image} /_static/images/sg.png +:align: center +:alt: Network Topology Diagram +:width: 50% +``` + +```{image} /_static/images/traffic.png +:align: center +:alt: Network Topology Diagram +:width: 50% +``` + +Terraform + +> 1 Create an UNIX or Windows instance +> +> 2 Download and install Terraform +> +> 3 Create the folder for example /root/awsterraform + +```none +mkdir /root/awsterraform + + 4 Copy all files into your Terraform project "/root/awsterraform" (vyos.tf, var.tf, terraform.tfvars,version.tf), more detailed see `Structure of files Terrafom for AWS`_ + + 5 Type the commands : +``` + +```none +cd /<your folder> +terraform init +``` + +Ansible + +> 1 Create an UNIX instance whenever you want (local, cloud, and so on) +> +> 2 Download and install Ansible +> +> 3 Create the folder for example /root/aws/ +> +> 4 Copy all files into your Ansible project "/root/aws/" (ansible.cfg, instance.yml, mykey.pem and "all"), more detailed see [Structure of files Ansible for AWS] + +mykey.pem you have to get using step 1.2 + +Start + +Type the commands on your Terrafom instance: + +```none +cd /<your folder> +terraform plan +terraform apply +yes +``` + +## Start creating an AWS instance and check the result + +```none +root@localhost:~/awsterraform# terraform apply + +Terraform used the selected providers to generate the following execution plan. +Resource actions are indicated with the following symbols: + + create + +Terraform will perform the following actions: + + # aws_instance.myVyOSec2 will be created + + resource "aws_instance" "myVyOSec2" { + + ami = "ami-************62c2d" + + arn = (known after apply) + + associate_public_ip_address = (known after apply) + + availability_zone = (known after apply) + + cpu_core_count = (known after apply) + + cpu_threads_per_core = (known after apply) + + disable_api_stop = (known after apply) + + disable_api_termination = (known after apply) + + ebs_optimized = (known after apply) + + get_password_data = false + + host_id = (known after apply) + + host_resource_group_arn = (known after apply) + + iam_instance_profile = (known after apply) + + id = (known after apply) + + instance_initiated_shutdown_behavior = (known after apply) + + instance_lifecycle = (known after apply) + + instance_state = (known after apply) + + instance_type = "t2.micro" + + ipv6_address_count = (known after apply) + + ipv6_addresses = (known after apply) + + key_name = "awsterraform" + + monitoring = (known after apply) + + outpost_arn = (known after apply) + + password_data = (known after apply) + + placement_group = (known after apply) + + placement_partition_number = (known after apply) + + primary_network_interface_id = (known after apply) + + private_dns = (known after apply) + + private_ip = (known after apply) + + public_dns = (known after apply) + + public_ip = (known after apply) + + secondary_private_ips = (known after apply) + + security_groups = [ + + "awsterraformsg", + ] + + source_dest_check = true + + spot_instance_request_id = (known after apply) + + subnet_id = (known after apply) + + tags = { + + "name" = "VyOS System" + } + + tags_all = { + + "name" = "VyOS System" + } + + tenancy = (known after apply) + + user_data = (known after apply) + + user_data_base64 = (known after apply) + + user_data_replace_on_change = false + + vpc_security_group_ids = (known after apply) + } + + # local_file.ip will be created + + resource "local_file" "ip" { + + content = (known after apply) + + content_base64sha256 = (known after apply) + + content_base64sha512 = (known after apply) + + content_md5 = (known after apply) + + content_sha1 = (known after apply) + + content_sha256 = (known after apply) + + content_sha512 = (known after apply) + + directory_permission = "0777" + + file_permission = "0777" + + filename = "ip.txt" + + id = (known after apply) + } + + # null_resource.SSHconnection1 will be created + + resource "null_resource" "SSHconnection1" { + + id = (known after apply) + } + + # null_resource.SSHconnection2 will be created + + resource "null_resource" "SSHconnection2" { + + id = (known after apply) + } + +Plan: 4 to add, 0 to change, 0 to destroy. + +Changes to Outputs: + + my_IP = (known after apply) + +Do you want to perform these actions? + Terraform will perform the actions described above. + Only 'yes' will be accepted to approve. + + Enter a value: yes + +aws_instance.myVyOSec2: Creating... +aws_instance.myVyOSec2: Still creating... [10s elapsed] +aws_instance.myVyOSec2: Still creating... [20s elapsed] +aws_instance.myVyOSec2: Still creating... [30s elapsed] +aws_instance.myVyOSec2: Still creating... [40s elapsed] +aws_instance.myVyOSec2: Creation complete after 44s [id=i-09edfca15aac2fe0a] +null_resource.SSHconnection1: Creating... +null_resource.SSHconnection2: Creating... +null_resource.SSHconnection1: Provisioning with 'file'... +null_resource.SSHconnection2: Provisioning with 'remote-exec'... +null_resource.SSHconnection2 (remote-exec): Connecting to remote host via SSH... +null_resource.SSHconnection2 (remote-exec): Host: 10.217.80.104 +null_resource.SSHconnection2 (remote-exec): User: root +null_resource.SSHconnection2 (remote-exec): Password: true +null_resource.SSHconnection2 (remote-exec): Private key: false +null_resource.SSHconnection2 (remote-exec): Certificate: false +null_resource.SSHconnection2 (remote-exec): SSH Agent: false +null_resource.SSHconnection2 (remote-exec): Checking Host Key: false +null_resource.SSHconnection2 (remote-exec): Target Platform: unix +local_file.ip: Creating... +local_file.ip: Creation complete after 0s [id=e8e91f2e24579cd28b92e2d152c0c24c3bf4b52c] +null_resource.SSHconnection2 (remote-exec): Connected! +null_resource.SSHconnection1: Creation complete after 0s [id=7070868940858935600] + +null_resource.SSHconnection2 (remote-exec): PLAY [integration of terraform and ansible] ************************************ + +null_resource.SSHconnection2 (remote-exec): TASK [Wait 300 seconds, but only start checking after 60 seconds] ************** +null_resource.SSHconnection2: Still creating... [10s elapsed] +null_resource.SSHconnection2: Still creating... [20s elapsed] +null_resource.SSHconnection2: Still creating... [30s elapsed] +null_resource.SSHconnection2: Still creating... [40s elapsed] +null_resource.SSHconnection2: Still creating... [50s elapsed] +null_resource.SSHconnection2: Still creating... [1m0s elapsed] +null_resource.SSHconnection2 (remote-exec): ok: [54.xxx.xxx.xxx] + +null_resource.SSHconnection2 (remote-exec): TASK [Configure general settings for the vyos hosts group] ********************* +null_resource.SSHconnection2: Still creating... [1m10s elapsed] +null_resource.SSHconnection2 (remote-exec): changed: [54.xxx.xxx.xxx] + +null_resource.SSHconnection2 (remote-exec): PLAY RECAP ********************************************************************* +null_resource.SSHconnection2 (remote-exec): 54.xxx.xxx.xxx : ok=2 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + +null_resource.SSHconnection2: Creation complete after 1m16s [id=4902256962410024771] + +Apply complete! Resources: 4 added, 0 changed, 0 destroyed. + +Outputs: + +my_IP = "54.xxx.xxx.xxx" +``` + +After executing all the commands you will have your VyOS instance on the AWS cloud with your configuration, it's a very convenient desition. +If you need to delete the instance please type the command: + +```none +terraform destroy +``` + +## Troubleshooting + +1 Ansible doesn't connect via SSH to your AWS instance: you have to check that your SSH key has copied into the path /root/aws/. +Also, increase the time in the file instance.yml from 300 sec to 500 sec or more. (It depends on your location). +Make sure that you have opened access to the instance in the security group. + +> 2 Terraform doesn't connect via SSH to your Ansible instance: you have to check the correct login and password in the part of the file VyOS. tf + +```none +connection { + type = "ssh" + user = "root" # open root access using login and password on your Ansible + password = var.password # check password in the file terraform.tfvars isn't empty + host = var.host # check the correct IP address of your Ansible host +} +``` + +Make sure that Ansible is pinging from Terrafom. + +## Structure of files Terrafom for AWS + +```none +. +├── vyos.tf # The main script +├── var.tf # The file of all variables in "vyos.tf" +├── versions.tf # File for the changing version of Terraform. +└── terraform.tfvars # The value of all variables (passwords, login, ip adresses and so on) +``` + +## File contents of Terrafom for AWS + +vyos.tf + +```none +############################################################################## +# Build an VyOS VM from the Marketplace +# To finde nessesery AMI image_ in AWS +# +# In the script vyos.tf we'll use default values (you can chang it as you need) +# AWS Region = "us-east-1" +# AMI = "standard AMI of VyOS from AWS Marketplace" +# Size of VM = "t2.micro" +# AWS Region = "us-east-1" +# After deploying the AWS instance and getting an IP address, the IP address is copied into the file +#"ip.txt" and copied to the Ansible node for provisioning. +############################################################################## + +provider "aws" { + access_key = var.access + secret_key = var.secret + region = var.region +} + +variable "region" { + default = "us-east-1" + description = "AWS Region" +} + +variable "ami" { + default = "ami-**************3b3" # ami image please enter your details + description = "Amazon Machine Image ID for VyOS" +} + +variable "type" { + default = "t2.micro" + description = "Size of VM" +} + +# my resource for VyOS + +resource "aws_instance" "myVyOSec2" { + ami = var.ami + key_name = "awsterraform" # Please enter your details from 1.2 of Preparation steps for deploying VyOS on AWS + security_groups = ["awsterraformsg"] # Please enter your details from 1.3 of Preparation steps for deploying VyOS on AWS + instance_type = var.type + tags = { + name = "VyOS System" + } +} + +############################################################################## +# specific variable (to getting type "terraform plan"): +# aws_instance.myVyOSec2.public_ip - the information about public IP address +# of our instance, needs for provisioning and ssh connection from Ansible +############################################################################## + +output "my_IP"{ +value = aws_instance.myVyOSec2.public_ip +} + +############################################################################## +# +# IP of aws instance copied to a file ip.txt in local system Terraform +# ip.txt looks like: +# cat ./ip.txt +# ххх.ххх.ххх.ххх +############################################################################## + +resource "local_file" "ip" { + content = aws_instance.myVyOSec2.public_ip + filename = "ip.txt" +} + +#connecting to the Ansible control node using SSH connection + +############################################################################## +# Steps "SSHconnection1" and "SSHconnection2" need to get file ip.txt from the terraform node and start remotely the playbook of Ansible. +############################################################################## + +resource "null_resource" "SSHconnection1" { +depends_on = [aws_instance.myVyOSec2] +connection { + type = "ssh" + user = "root" + password = var.password + host = var.host +} + +#copying the ip.txt file to the Ansible control node from local system + + provisioner "file" { + source = "ip.txt" + destination = "/root/aws/ip.txt" # The folder of your Ansible project + } +} + +resource "null_resource" "SSHconnection2" { +depends_on = [aws_instance.myVyOSec2] +connection { + type = "ssh" + user = "root" + password = var.password + host = var.host +} +#command to run Ansible playbook on remote Linux OS +provisioner "remote-exec" { + inline = [ + "cd /root/aws/", + "ansible-playbook instance.yml" # more detailed in "File contents of Ansible for AWS" +] +} +} +``` + +var.tf + +```none +variable "password" { + description = "pass for Ansible" + type = string + sensitive = true +} +variable "host"{ + description = "The IP of my Ansible" + type = string +} +variable "access" { + description = "my access_key for AWS" + type = string + sensitive = true +} +variable "secret" { + description = "my secret_key for AWS" + type = string + sensitive = true +} +``` + +versions.tf + +```none + terraform { + required_providers { + aws = { + source = "hashicorp/aws" + version = "~> 5.0" + } + } +} +``` + +terraform.tfvars + +```none +password = "" # password for Ansible SSH +host = "" # IP of my Ansible +access = "" # access_key for AWS +secret = "" # secret_key for AWS +``` + +## Structure of files Ansible for AWS + +```none +. +├── group_vars + └── all +├── ansible.cfg +├── mykey.pem +└── instance.yml +``` + +## File contents of Ansible for AWS + +ansible.cfg + +```none +[defaults] +inventory = /root/aws/ip.txt +host_key_checking= False +private_key_file = /root/aws/awsterraform.pem # check the name +remote_user=vyos +``` + +mykey.pem + +```none +Copy your key.pem from AWS +``` + +instance.yml + +```none +############################################################################## +# About tasks: +# "Wait 300 seconds, but only start checking after 60 seconds" - try to make ssh connection every 60 seconds until 300 seconds +# "Configure general settings for the VyOS hosts group" - make provisioning into AWS VyOS node +# You have to add all necessary cammans of VyOS under the block "lines:" +############################################################################## + + +- name: integration of terraform and ansible + hosts: all + gather_facts: 'no' + + tasks: + + - name: "Wait 300 seconds, but only start checking after 60 seconds" + wait_for_connection: + delay: 60 + timeout: 300 + + - name: "Configure general settings for the VyOS hosts group" + vyos_config: + lines: + - set system name-server xxx.xxx.xxx.xxx + save: + true +``` + +group_vars/all + +```none +ansible_connection: ansible.netcommon.network_cli +ansible_network_os: vyos.vyos.vyos +ansible_user: vyos +``` + +## Sourse files for AWS from GIT + +All files about the article can be found [here] + +[group]: https://docs.aws.amazon.com/cli/latest/userguide/cli-services-ec2-sg.html +[here]: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/AWS_terraform_ansible_single_vyos_instance-main +[image]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html +[install]: https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli +[link]: https://developer.hashicorp.com/terraform/intro +[pair]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/create-key-pairs.html diff --git a/docs/automation/terraform/md-terraformAZ.md b/docs/automation/terraform/md-terraformAZ.md new file mode 100644 index 00000000..0e195be9 --- /dev/null +++ b/docs/automation/terraform/md-terraformAZ.md @@ -0,0 +1,470 @@ +--- +lastproofread: '2024-03-03' +--- + +(terraformaz)= + +# Deploying VyOS in the Azure cloud + +With the help of Terraform, you can quickly deploy VyOS-based infrastructure in the Azure cloud. If necessary, the infrastructure can be removed using terraform. +Also we will make provisioning using Ansible. + +In this case, we'll create the necessary files for Terraform and Ansible next using Terraform we'll create a single instance on the Azure cloud and make provisioning using Ansible. + +## Preparation steps for deploying VyOS on Azure + +How to create a single instance and install your configuration using Terraform+Ansible+Azure +Step by step: + +Azure + +> 1 Create an account with Azure + +Terraform + +> 1 Create an UNIX or Windows instance +> +> 2 Download and install Terraform +> +> 3 Create the folder for example /root/azvyos/ + +```none +mkdir /root/azvyos + + 4 Copy all files into your Terraform project "/root/azvyos" (vyos.tf, var.tf, terraform.tfvars), more detailed see `Structure of files Terrafom for Azure`_ + + 5 Login with Azure using the command +``` + +```none +az login +``` + +2.6 Type the commands : + +```none +cd /<your folder> +terraform init +``` + +Ansible + +> 1 Create an UNIX instance whenever you want (local, cloud, and so on) +> +> 2 Download and install Ansible +> +> 3 Create the folder for example /root/az/ +> +> 4 Copy all files into your Ansible project "/root/az/" (ansible.cfg, instance.yml,"all"), more detailed see [Structure of files Ansible for Azure] + +Start + +Type the commands on your Terrafom instance: + +```none +cd /<your folder> +terraform plan +terraform apply +yes +``` + +After executing all the commands you will have your VyOS instance on the Azure cloud with your configuration, it's a very convenient desition. +If you need to delete the instance please type the command: + +```none +terraform destroy +``` + +## Structure of files Terrafom for Azure + +```none +. +├── vyos.tf # The main script +├── var.tf # File for the changing version of Terraform. +└── terraform.tfvars # The value of all variables (passwords, login, ip adresses and so on) +``` + +## File contents of Terrafom for Azure + +vyos.tf + +```none +############################################################################## +# HashiCorp Guide to Using Terraform on Azure +# This Terraform configuration will create the following: +# Resource group with a virtual network and subnet +# An VyOS server without ssh key (only login+password) +############################################################################## + +# Chouse a provider + +provider "azurerm" { + features {} +} + +# Create a resource group. In Azure every resource belongs to a +# resource group. + +resource "azurerm_resource_group" "azure_vyos" { + name = "${var.resource_group}" + location = "${var.location}" +} + +# The next resource is a Virtual Network. + +resource "azurerm_virtual_network" "vnet" { + name = "${var.virtual_network_name}" + location = "${var.location}" + address_space = ["${var.address_space}"] + resource_group_name = "${var.resource_group}" +} + +# Build a subnet to run our VMs in. + +resource "azurerm_subnet" "subnet" { + name = "${var.prefix}subnet" + virtual_network_name = "${azurerm_virtual_network.vnet.name}" + resource_group_name = "${var.resource_group}" + address_prefixes = ["${var.subnet_prefix}"] +} + +############################################################################## +# Build an VyOS VM from the Marketplace +# To finde nessesery image use the command: +# +# az vm image list --offer vyos --all +# +# Now that we have a network, we'll deploy an VyOS server. +# An Azure Virtual Machine has several components. In this example we'll build +# a security group, a network interface, a public ip address, a storage +# account and finally the VM itself. Terraform handles all the dependencies +# automatically, and each resource is named with user-defined variables. +############################################################################## + + +# Security group to allow inbound access on port 22 (ssh) + +resource "azurerm_network_security_group" "vyos-sg" { + name = "${var.prefix}-sg" + location = "${var.location}" + resource_group_name = "${var.resource_group}" + + security_rule { + name = "SSH" + priority = 100 + direction = "Inbound" + access = "Allow" + protocol = "Tcp" + source_port_range = "*" + destination_port_range = "22" + source_address_prefix = "${var.source_network}" + destination_address_prefix = "*" + } +} + +# A network interface. + +resource "azurerm_network_interface" "vyos-nic" { + name = "${var.prefix}vyos-nic" + location = "${var.location}" + resource_group_name = "${var.resource_group}" + + ip_configuration { + name = "${var.prefix}ipconfig" + subnet_id = "${azurerm_subnet.subnet.id}" + private_ip_address_allocation = "Dynamic" + public_ip_address_id = "${azurerm_public_ip.vyos-pip.id}" + } +} + +# Add a public IP address. + +resource "azurerm_public_ip" "vyos-pip" { + name = "${var.prefix}-ip" + location = "${var.location}" + resource_group_name = "${var.resource_group}" + allocation_method = "Dynamic" +} + +# Build a virtual machine. This is a standard VyOS instance from Marketplace. + +resource "azurerm_virtual_machine" "vyos" { + name = "${var.hostname}-vyos" + location = "${var.location}" + resource_group_name = "${var.resource_group}" + vm_size = "${var.vm_size}" + + network_interface_ids = ["${azurerm_network_interface.vyos-nic.id}"] + delete_os_disk_on_termination = "true" + +# To finde an information about the plan use the command: +# az vm image list --offer vyos --all + + plan { + publisher = "sentriumsl" + name = "vyos-1-3" + product = "vyos-1-2-lts-on-azure" + } + + storage_image_reference { + publisher = "${var.image_publisher}" + offer = "${var.image_offer}" + sku = "${var.image_sku}" + version = "${var.image_version}" + } + + storage_os_disk { + name = "${var.hostname}-osdisk" + managed_disk_type = "Standard_LRS" + caching = "ReadWrite" + create_option = "FromImage" + } + + os_profile { + computer_name = "${var.hostname}" + admin_username = "${var.admin_username}" + admin_password = "${var.admin_password}" + } + + os_profile_linux_config { + disable_password_authentication = false + } +} + +data "azurerm_public_ip" "example" { + depends_on = ["azurerm_virtual_machine.vyos"] + name = "vyos-ip" + resource_group_name = "${var.resource_group}" +} +output "public_ip_address" { + value = data.azurerm_public_ip.example.ip_address +} + +# IP of AZ instance copied to a file ip.txt in local system + +resource "local_file" "ip" { + content = data.azurerm_public_ip.example.ip_address + filename = "ip.txt" +} + +#Connecting to the Ansible control node using SSH connection + +resource "null_resource" "nullremote1" { +depends_on = ["azurerm_virtual_machine.vyos"] +connection { + type = "ssh" + user = "root" + password = var.password + host = var.host +} + +# Copying the ip.txt file to the Ansible control node from local system + + provisioner "file" { + source = "ip.txt" + destination = "/root/az/ip.txt" + } +} + +resource "null_resource" "nullremote2" { +depends_on = ["azurerm_virtual_machine.vyos"] +connection { + type = "ssh" + user = "root" + password = var.password + host = var.host +} + +# Command to run ansible playbook on remote Linux OS + +provisioner "remote-exec" { + + inline = [ + "cd /root/az/", + "ansible-playbook instance.yml" +] +} +} +``` + +var.tf + +```none +############################################################################## +# Variables File +# +# Here is where we store the default values for all the variables used in our +# Terraform code. +############################################################################## + +variable "resource_group" { + description = "The name of your Azure Resource Group." + default = "my_resource_group" +} + +variable "prefix" { + description = "This prefix will be included in the name of some resources." + default = "vyos" +} + +variable "hostname" { + description = "Virtual machine hostname. Used for local hostname, DNS, and storage-related names." + default = "vyos_terraform" +} + +variable "location" { + description = "The region where the virtual network is created." + default = "centralus" +} + +variable "virtual_network_name" { + description = "The name for your virtual network." + default = "vnet" +} + +variable "address_space" { + description = "The address space that is used by the virtual network. You can supply more than one address space. Changing this forces a new resource to be created." + default = "10.0.0.0/16" +} + +variable "subnet_prefix" { + description = "The address prefix to use for the subnet." + default = "10.0.10.0/24" +} + +variable "storage_account_tier" { + description = "Defines the storage tier. Valid options are Standard and Premium." + default = "Standard" +} + +variable "storage_replication_type" { + description = "Defines the replication type to use for this storage account. Valid options include LRS, GRS etc." + default = "LRS" +} + +# The most chippers size + +variable "vm_size" { + description = "Specifies the size of the virtual machine." + default = "Standard_B1s" +} + +variable "image_publisher" { + description = "Name of the publisher of the image (az vm image list)" + default = "sentriumsl" +} + +variable "image_offer" { + description = "Name of the offer (az vm image list)" + default = "vyos-1-2-lts-on-azure" +} + +variable "image_sku" { + description = "Image SKU to apply (az vm image list)" + default = "vyos-1-3" +} + +variable "image_version" { + description = "Version of the image to apply (az vm image list)" + default = "1.3.3" +} + +variable "admin_username" { + description = "Administrator user name" + default = "vyos" +} + +variable "admin_password" { + description = "Administrator password" + default = "Vyos0!" +} + +variable "source_network" { + description = "Allow access from this network prefix. Defaults to '*'." + default = "*" +} + +variable "password" { + description = "pass for Ansible" + type = string + sensitive = true +} +variable "host"{ + description = "IP of my Ansible" +} +``` + +terraform.tfvars + +```none +password = "" # password for Ansible SSH +host = "" # IP of my Ansible +``` + +## Structure of files Ansible for Azure + +```none +. +├── group_vars + └── all +├── ansible.cfg +└── instance.yml +``` + +## File contents of Ansible for Azure + +ansible.cfg + +```none +[defaults] +inventory = /root/az/ip.txt +host_key_checking= False +remote_user=vyos +``` + +instance.yml + +```none +############################################################################## +# About tasks: +# "Wait 300 seconds, but only start checking after 60 seconds" - try to make ssh connection every 60 seconds until 300 seconds +# "Configure general settings for the VyOS hosts group" - make provisioning into Azure VyOS node +# You have to add all necessary cammans of VyOS under the block "lines:" +############################################################################## + + +- name: integration of terraform and ansible + hosts: all + gather_facts: 'no' + + tasks: + + - name: "Wait 300 seconds, but only start checking after 60 seconds" + wait_for_connection: + delay: 60 + timeout: 300 + + - name: "Configure general settings for the VyOS hosts group" + vyos_config: + lines: + - set system name-server xxx.xxx.xxx.xxx + save: + true +``` + +group_vars/all + +```none +ansible_connection: ansible.netcommon.network_cli +ansible_network_os: vyos.vyos.vyos + +# user and password gets from terraform variables "admin_username" and "admin_password" in the file /root/azvyos/var.tf +ansible_user: vyos +ansible_ssh_pass: Vyos0! +``` + +## Sourse files for Azure from GIT + +All files about the article can be found [here] + +[here]: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/Azure_terraform_ansible_single_vyos_instance-main diff --git a/docs/automation/terraform/md-terraformGoogle.md b/docs/automation/terraform/md-terraformGoogle.md new file mode 100644 index 00000000..e69de29b --- /dev/null +++ b/docs/automation/terraform/md-terraformGoogle.md diff --git a/docs/automation/terraform/md-terraformvSphere.md b/docs/automation/terraform/md-terraformvSphere.md new file mode 100644 index 00000000..55b9860b --- /dev/null +++ b/docs/automation/terraform/md-terraformvSphere.md @@ -0,0 +1,377 @@ +--- +lastproofread: '2024-03-03' +--- + +(terraformvsphere)= + +# Deploying VyOS in the vSphere infrastructure + +With the help of Terraform, you can quickly deploy VyOS-based infrastructure in the vSphere. +Also we will make provisioning using Ansible. + +In this case, we'll create the necessary files for Terraform and Ansible next using Terraform we'll create a single instance on the vSphere cloud and make provisioning using Ansible. + +## Preparation steps for deploying VyOS on vSphere + +How to create a single instance and install your configuration using Terraform+Ansible+vSphere +Step by step: + +vSphere + +> 1 Collect all data in to file "terraform.tfvars" and create resources for example "terraform" + +Terraform + +> 1 Create an UNIX or Windows instance +> +> 2 Download and install Terraform +> +> 3 Create the folder for example /root/vsphereterraform + +```none +mkdir /root/vsphereterraform + + + 4 Copy all files into your Terraform project "/root/vsphereterraform" (vyos.tf, var.tf, terraform.tfvars,version.tf), more detailed see `Structure of files Terrafom for vSphere`_ + + 5 Type the commands : +``` + +```none +cd /<your folder> +terraform init +``` + +Ansible + +> 1 Create an UNIX instance whenever you want (local, cloud, and so on) +> +> 2 Download and install Ansible +> +> 3 Create the folder for example /root/vsphereterraform/ +> +> 4 Copy all files into your Ansible project "/root/vsphereterraform/" (ansible.cfg, instance.yml,"all"), more detailed see [Structure of files Ansible for vSphere] + +Start + +Type the commands on your Terrafom instance: + +```none +cd /<your folder> +terraform plan +terraform apply +yes +``` + +After executing all the commands you will have your VyOS instance on the vSphere with your configuration, it's a very convenient desition. +If you need to delete the instance please type the command: + +```none +terraform destroy +``` + +## Structure of files Terrafom for vSphere + +```none +. +├── vyos.tf # The main script +├── versions.tf # File for the changing version of Terraform. +├── var.tf # File for the changing version of Terraform. +└── terraform.tfvars # The value of all variables (passwords, login, ip adresses and so on) +``` + +## File contents of Terrafom for vSphere + +vyos.tf + +```none +provider "vsphere" { + user = var.vsphere_user + password = var.vsphere_password + vsphere_server = var.vsphere_server + allow_unverified_ssl = true +} + +data "vsphere_datacenter" "datacenter" { + name = var.datacenter +} + +data "vsphere_datastore" "datastore" { + name = var.datastore + datacenter_id = data.vsphere_datacenter.datacenter.id +} + +data "vsphere_compute_cluster" "cluster" { + name = var.cluster + datacenter_id = data.vsphere_datacenter.datacenter.id +} + +data "vsphere_resource_pool" "default" { + name = format("%s%s", data.vsphere_compute_cluster.cluster.name, "/Resources/terraform") # set as you need + datacenter_id = data.vsphere_datacenter.datacenter.id +} + +data "vsphere_host" "host" { + name = var.host + datacenter_id = data.vsphere_datacenter.datacenter.id +} + +data "vsphere_network" "network" { + name = var.network_name + datacenter_id = data.vsphere_datacenter.datacenter.id +} + +# Deployment of VM from Remote OVF +resource "vsphere_virtual_machine" "vmFromRemoteOvf" { + name = var.remotename + datacenter_id = data.vsphere_datacenter.datacenter.id + datastore_id = data.vsphere_datastore.datastore.id + host_system_id = data.vsphere_host.host.id + resource_pool_id = data.vsphere_resource_pool.default.id + network_interface { + network_id = data.vsphere_network.network.id + } + wait_for_guest_net_timeout = 2 + wait_for_guest_ip_timeout = 2 + + ovf_deploy { + allow_unverified_ssl_cert = true + remote_ovf_url = var.url_ova + disk_provisioning = "thin" + ip_protocol = "IPv4" + ip_allocation_policy = "dhcpPolicy" + ovf_network_map = { + "Network 1" = data.vsphere_network.network.id + "Network 2" = data.vsphere_network.network.id + } + } + vapp { + properties = { + "password" = "12345678", + "local-hostname" = "terraform_vyos" + } + } +} + +output "ip" { + description = "default ip address of the deployed VM" + value = vsphere_virtual_machine.vmFromRemoteOvf.default_ip_address +} + +# IP of vSphere instance copied to a file ip.txt in local system + +resource "local_file" "ip" { + content = vsphere_virtual_machine.vmFromRemoteOvf.default_ip_address + filename = "ip.txt" +} + +#Connecting to the Ansible control node using SSH connection + +resource "null_resource" "nullremote1" { +depends_on = ["vsphere_virtual_machine.vmFromRemoteOvf"] +connection { + type = "ssh" + user = "root" + password = var.ansiblepassword + host = var.ansiblehost + +} + +# Copying the ip.txt file to the Ansible control node from local system + + provisioner "file" { + source = "ip.txt" + destination = "/root/vsphere/ip.txt" + } +} + +resource "null_resource" "nullremote2" { +depends_on = ["vsphere_virtual_machine.vmFromRemoteOvf"] +connection { + type = "ssh" + user = "root" + password = var.ansiblepassword + host = var.ansiblehost +} + +# Command to run ansible playbook on remote Linux OS + +provisioner "remote-exec" { + + inline = [ + "cd /root/vsphere/", + "ansible-playbook instance.yml" +] +} +} +``` + +versions.tf + +```none +# Copyright (c) HashiCorp, Inc. +# SPDX-License-Identifier: MPL-2.0 + +terraform { + required_providers { + vsphere = { + source = "hashicorp/vsphere" + version = "2.4.0" + } + } +} +``` + +var.tf + +```none +# Copyright (c) HashiCorp, Inc. +# SPDX-License-Identifier: MPL-2.0 + +variable "vsphere_server" { + description = "vSphere server" + type = string +} + +variable "vsphere_user" { + description = "vSphere username" + type = string +} + +variable "vsphere_password" { + description = "vSphere password" + type = string + sensitive = true +} + +variable "datacenter" { + description = "vSphere data center" + type = string +} + +variable "cluster" { + description = "vSphere cluster" + type = string +} + +variable "datastore" { + description = "vSphere datastore" + type = string +} + +variable "network_name" { + description = "vSphere network name" + type = string +} + +variable "host" { + description = "name if yor host" + type = string +} + +variable "remotename" { + description = "the name of you VM" + type = string +} + +variable "url_ova" { + description = "the URL to .OVA file or cloude store" + type = string +} + +variable "ansiblepassword" { + description = "Ansible password" + type = string +} + +variable "ansiblehost" { + description = "Ansible host name or IP" + type = string +} +``` + +terraform.tfvars + +```none +vsphere_user = "" +vsphere_password = "" +vsphere_server = "" +datacenter = "" +datastore = "" +cluster = "" +network_name = "" +host = "" +url_ova = "" +ansiblepassword = "" +ansiblehost = "" +remotename = "" +``` + +## Structure of files Ansible for vSphere + +```none +. +├── group_vars + └── all +├── ansible.cfg +└── instance.yml +``` + +## File contents of Ansible for vSphere + +ansible.cfg + +```none +[defaults] +inventory = /root/vsphere/ip.txt +host_key_checking= False +remote_user=vyos +``` + +instance.yml + +```none +############################################################################## +# About tasks: +# "Wait 300 seconds, but only start checking after 60 seconds" - try to make ssh connection every 60 seconds until 300 seconds +# "Configure general settings for the VyOS hosts group" - make provisioning into vSphere VyOS node +# You have to add all necessary cammans of VyOS under the block "lines:" +############################################################################## + + +- name: integration of terraform and ansible + hosts: all + gather_facts: 'no' + + tasks: + + - name: "Wait 300 seconds, but only start checking after 60 seconds" + wait_for_connection: + delay: 60 + timeout: 300 + + - name: "Configure general settings for the VyOS hosts group" + vyos_config: + lines: + - set system name-server 8.8.8.8 + save: + true +``` + +group_vars/all + +```none +ansible_connection: ansible.netcommon.network_cli +ansible_network_os: vyos.vyos.vyos + +# user and password gets from terraform variables "admin_username" and "admin_password" +ansible_user: vyos +# get from vyos.tf "vapp" +ansible_ssh_pass: 12345678 +``` + +## Sourse files for vSphere from GIT + +All files about the article can be found [here] + +[here]: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/Vsphere_terraform_ansible_single_vyos_instance-main diff --git a/docs/automation/terraform/md-terraformvyos.md b/docs/automation/terraform/md-terraformvyos.md new file mode 100644 index 00000000..cb1ca1ee --- /dev/null +++ b/docs/automation/terraform/md-terraformvyos.md @@ -0,0 +1,37 @@ +--- +lastproofread: '2024-03-03' +--- + +(terraformvyos)= + +# Terraform for VyOS + +VyOS supports development infrastructure via Terraform and provisioning via Ansible. +Terraform allows you to automate the process of deploying instances on many cloud and virtual platforms. +In this article, we will look at using terraforms to deploy VyOS on platforms - AWS, Azure, and vSphere. +For more details about Terraform please have a look here [link]. + +Need to [install] Terraform + +Structure of files in the standard Terraform project: + +```none +. +├── main.tf # The main script +├── version.tf # File for the changing version of Terraform. +├── variables.tf # The file of all variables in "main.tf" +└── terraform.tfvars # The value of all variables (passwords, login, ip adresses and so on) +``` + +General commands that we will use for running Terraform scripts + +```none +cd /<your folder> # go to the Terrafom project +terraform init # install all addons and provider (aws az and so on) +terraform plan # show what is changing +terraform apply # run script +yes # apply running +``` + +[install]: https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli +[link]: https://developer.hashicorp.com/terraform/intro diff --git a/docs/changelog/md-1.2.1.md b/docs/changelog/md-1.2.1.md new file mode 100644 index 00000000..967d566e --- /dev/null +++ b/docs/changelog/md-1.2.1.md @@ -0,0 +1,50 @@ +# 1.2.1 + +VyOS 1.2.1 is a maintenance release made in April 2019. + +## Resolved issues + +- Package updates: kernel 4.19.32, open-vm-tools 10.3, latest Intel NIC drivers +- {vytask}`T1326` The kernel now includes drivers for various USB serial + adapters, which allows people to add a serial console to a machine without + onboard RS232, or connect to something else from the router +- The collection of network card firmware is now much more extensive +- {vytask}`T1271` VRRP now correctly uses a virtual rather than physical MAC + addresses in the RFC-compliant mode +- {vytask}`T1330` DHCP WPAD URL option works correctly again +- {vytask}`T1312` Many to many NAT rules now can use source/destination and + translation networks of non-matching size. If 1:1 network bits translation is + desired, it's now users responsibility to check if prefix length matches. +- {vytask}`T1290` IPv6 network prefix translation is fixed +- {vytask}`T1308` Non-alphanumeric characters such as `>` can now be safely + used in PPPoE passwords +- {vytask}`T1305` `show | commands` no longer fails when a config section ends + with a leaf node such as `timezone` in `show system | commands` +- {vytask}`T1235` `show | commands` correctly works in config mode now +- {vytask}`T1298` VTI is now compatible with the DHCP-interface IPsec option +- {vytask}`T1277` `show dhcp server statistics` command was broken in latest + Crux +- {vytask}`T1261` An issue with TFTP server refusing to listen on addresses + other than loopback was fixed +- {vytask}`T1224` Template issue that might cause UDP broadcast relay fail to + start is fixed +- {vytask}`T1067` VXLAN value validation is improved +- {vytask}`T1211` Blank hostnames in DHCP updates no longer can crash DNS + forwarding +- {vytask}`T1322` Correct configuration is now generated for DHCPv6 relays with + more than one upstream interface +- {vytask}`T1234` `relay-agents-packets` option works correctly now +- {vytask}`T1231` Dynamic DNS data is now cleaned on configuration change +- {vytask}`T1282` Remote Syslog can now use a fully qualified domain name +- {vytask}`T1279` ACPI power off works again +- {vytask}`T1247` Negation in WAN load balancing rules works again +- {vytask}`T1218` FRR staticd now starts on boot correctly +- {vytask}`T1296` The installer now correctly detects SD card devices +- {vytask}`T1225` Wireguard peers can be disabled now +- {vytask}`T1217` The issue with Wireguard interfaces impossible to delete + is fixed +- {vytask}`T1160` Unintended IPv6 access is fixed in SNMP configuration +- {vytask}`T1060` It's now possible to exclude hosts from the transparent + web proxy +- {vytask}`T484` An issue with rules impossible to delete from the zone-based + firewall is fixed diff --git a/docs/changelog/md-1.2.2.md b/docs/changelog/md-1.2.2.md new file mode 100644 index 00000000..972a38be --- /dev/null +++ b/docs/changelog/md-1.2.2.md @@ -0,0 +1,43 @@ +# 1.2.2 + +1.2.2 is a maintenance release made in July 2019. + +## New features + +- Options for per-interface MSS clamping. +- BGP extended next-hop capability +- Relaxed BGP multipath option +- Internal and external options for "remote-as" (accept any AS as long as it's + the same to this router or different, respectively) +- "Unnumbered" (interface-based) BGP peers +- BGP no-prepend option +- Additive BGP community option +- OSPFv3 network type option +- Custom arguments for VRRP scripts +- A script for querying values from config files + +## Resolved issues + +- Linux kernel 4.19.54, including a fix for the TCP SACK vulnerability +- {vytask}`T1371` VRRP health-check scripts now can use arguments +- {vytask}`T1497` DNS server addresses coming from a DHCP server are now + correctly propagated to resolv.conf +- {vytask}`T1469` Domain-specific name servers in DNS forwarding are now used + for recursive queries +- {vytask}`T1433` `run show dhcpv6 server leases` now display leases correctly +- {vytask}`T1461` Deleting `firewall options` node no longer causes errors +- {vytask}`T1458` Correct hostname is sent to remote syslog again +- {vytask}`T1438` Board serial number from DMI is correctly displayed in + `show version` +- {vytask}`T1358`, {vytask}`T1355`, {vytask}`T1294` Multiple corrections in + remote syslog config +- {vytask}`T1255` Fixed missing newline in `/etc/hosts` +- {vytask}`T1174` `system domain-name` is correctly included in + `/etc/resolv.conf` +- {vytask}`T1465` Fixed priority inversion in `interfaces vti vtiX ip` + settings +- {vytask}`T1446` Fixed errors when installing with RAID1 on UEFI machines +- {vytask}`T1387` Fixed an error on disabling an interfaces that has no address +- {vytask}`T1367` Fixed deleting VLAN interface with non-default MTU +- {vytask}`T1505` vyos.config `return_effective_values()` function now + correctly returns a list rather than a string diff --git a/docs/changelog/md-1.2.3.md b/docs/changelog/md-1.2.3.md new file mode 100644 index 00000000..96ca1818 --- /dev/null +++ b/docs/changelog/md-1.2.3.md @@ -0,0 +1,58 @@ +# 1.2.3 + +1.2.3 is a maintenance and feature backport release made in September 2019. + +## New features + +- HTTP API +- {vytask}`T1524` "set service dns forwarding allow-from \<IPv4 net|IPv6 net>" + option for limiting queries to specific client networks +- {vytask}`T1503` Functions for checking if a commit is in progress +- {vytask}`T1543` "set system contig-mangement commit-archive source-address" + option +- {vytask}`T1554` Intel NIC drivers now support receive side scaling and + multiqueue + +## Resolved issues + +- {vytask}`T1209` OSPF max-metric values over 100 no longer causes commit + errors +- {vytask}`T1333` Fixes issue with DNS forwarding not performing recursive + lookups on domain specific forwarders +- {vytask}`T1362` Special characters in VRRP passwords are handled correctly +- {vytask}`T1377` BGP weight is applied properly +- {vytask}`T1420` Fixed permission for log files +- {vytask}`T1425` Wireguard interfaces now support /31 addresses +- {vytask}`T1428` Wireguard correctly handles firewall marks +- {vytask}`T1439` DHCPv6 static mappings now work correctly +- {vytask}`T1450` Flood ping commands now works correctly +- {vytask}`T1460` Op mode "show firewall" commands now support counters longer + than 8 digits (T1460) +- {vytask}`T1465` Fixed priority inversion in VTI commands +- {vytask}`T1468` Fixed remote-as check in the BGP route-reflector-client option +- {vytask}`T1472` It's now possible to re-create VRRP groups with RFC + compatibility mode enabled +- {vytask}`T1527` Fixed a typo in DHCPv6 server help strings +- {vytask}`T1529` Unnumbered BGP peers now support VLAN interfaces +- {vytask}`T1530` Fixed "set system syslog global archive file" command +- {vytask}`T1531` Multiple fixes in cluster configuration scripts +- {vytask}`T1537` Fixed missing help text for "service dns" +- {vytask}`T1541` Fixed input validation in DHCPv6 relay options +- {vytask}`T1551` It's now possible to create a QinQ interface and a firewall + assigned to it in one commit +- {vytask}`T1559` URL filtering now uses correct rule database path and works + again +- {vytask}`T1579` "show log vpn ipsec" command works again +- {vytask}`T1576` "show arp interface \<intf>" command works again +- {vytask}`T1605` Fixed regression in L2TP/IPsec server +- {vytask}`T1613` Netflow/sFlow captures IPv6 traffic correctly +- {vytask}`T1616` "renew dhcpv6" command now works from op mode +- {vytask}`T1642` BGP remove-private-as option iBGP vs eBGP check works + correctly now +- {vytask}`T1540`, {vytask}`T1360`, {vytask}`T1264`, {vytask}`T1623` Multiple + improvements in name servers and hosts configuration handling + +## Internals + +`/etc/resolv.conf` and `/etc/hosts` files are now managed by the +*vyos-hostsd* service that listens on a ZMQ socket for update messages. diff --git a/docs/changelog/md-1.2.4.md b/docs/changelog/md-1.2.4.md new file mode 100644 index 00000000..bc098699 --- /dev/null +++ b/docs/changelog/md-1.2.4.md @@ -0,0 +1,75 @@ +# 1.2.4 + +1.2.4 is a maintenance release made in December 2019. + +## Resolved issues + +- {vytask}`T258` Can not configure wan load-balancing on vyos-1.2 +- {vytask}`T818` SNMP v3 - remove required engineid from user node +- {vytask}`T1030` Upgrade ddclient from 3.8.2 to 3.9. + (support Cloudflare API v4) +- {vytask}`T1183` BFD Support via FRR +- {vytask}`T1299` Allow SNMPd to be extended with custom scripts +- {vytask}`T1351` accel-pppoe adding CIDR based IP pool option +- {vytask}`T1391` In route-map set community additive +- {vytask}`T1394` syslog systemd and host_name.py race condition +- {vytask}`T1401` Copying files with the FTP protocol fails if the passwor + contains special characters +- {vytask}`T1421` OpenVPN client push-route stopped working, needs added quotes + to fix +- {vytask}`T1430` Add options for custom DHCP client-id and hostname +- {vytask}`T1447` Python subprocess called without import in host_name.py +- {vytask}`T1470` improve output of "show dhcpv6 server leases" +- {vytask}`T1485` Enable 'AdvIntervalOpt' option in for radvd.conf +- {vytask}`T1496` Separate rolling release and LTS kernel builds +- {vytask}`T1560` "set load-balancing wan rule 0" causes segfault and prevent + load balancing from starting +- {vytask}`T1568` strip-private command improvement for additional masking o + IPv6 and MAC address +- {vytask}`T1578` completion offers "show table", but show table does not exist +- {vytask}`T1593` Support ip6gre +- {vytask}`T1597` /usr/sbin/rsyslogd after deleting "system syslog" +- {vytask}`T1638` vyos-hostsd not setting system domain name +- {vytask}`T1678` hostfile-update missing line feed +- {vytask}`T1694` NTPd: Do not listen on all interfaces by default +- {vytask}`T1701` Delete domain-name and domain-search won't work +- {vytask}`T1705` High CPU usage by bgpd when snmp is active +- {vytask}`T1707` DHCP static mapping and exclude address not working +- {vytask}`T1708` Update Rolling Release Kernel to 4.19.76 +- {vytask}`T1709` Update WireGuard to 0.0.20190913 +- {vytask}`T1716` Update Intel NIC drivers to recent versions +- {vytask}`T1726` Update Linux Firmware binaries to a more recen + version 2019-03-14 -> 2019-10-07 +- {vytask}`T1728` Update Linux Kernel to 4.19.79 +- {vytask}`T1737` SNMP tab completion missing +- {vytask}`T1738` Copy SNMP configuration from node to node raises exception +- {vytask}`T1740` Broken OSPFv2 virtual-link authentication +- {vytask}`T1742` NHRP unable to commit. +- {vytask}`T1745` dhcp-server commit fails with "DHCP range stop address + must be greater or equal to the range start address y!" when static mapping + has same IP as range stop +- {vytask}`T1749` numeric validator doesn't support multiple ranges +- {vytask}`T1769` Remove complex SNMPv3 Transport Security Model (TSM) +- {vytask}`T1772` \<regex> constraints in XML are partially broken +- {vytask}`T1778` Kilobits/Megabits difference in configuration Vyos/FRR +- {vytask}`T1780` Adding ipsec ike closeaction +- {vytask}`T1786` disable-dhcp-nameservers is missed in current host_name.p + implementation +- {vytask}`T1788` Intel QAT (QuickAssist Technology ) implementation +- {vytask}`T1792` Update WireGuard to Debian release 0.0.20191012-1 +- {vytask}`T1800` Update Linux Kernel to v4.19.84 +- {vytask}`T1809` Wireless: SSID scan does not work in AP mode +- {vytask}`T1811` Upgrade from 1.1.8: Config file migratio + failed: module=l2tp +- {vytask}`T1812` DHCP: hostnames of clients not resolving afte + update v1.2.3 -> 1.2-rolling +- {vytask}`T1819` Reboot kills SNMPv3 configuration +- {vytask}`T1822` Priority inversion wireless interface dhcpv6 +- {vytask}`T1825` Improve DHCP configuration error message +- {vytask}`T1836` import-conf-mode-commands in vyos-1x/scripts fails + to create an xml +- {vytask}`T1839` LLDP shows "VyOS unknown" instead of "VyOS" +- {vytask}`T1841` PPP ipv6-up.d direcotry missing +- {vytask}`T1893` igmp-proxy: Do not allow adding unknown interface +- {vytask}`T1903` Implementation udev predefined interface naming +- {vytask}`T1904` update eth1 and eth2 link files for the vep4600 diff --git a/docs/changelog/md-1.2.5.md b/docs/changelog/md-1.2.5.md new file mode 100644 index 00000000..4e0c67bb --- /dev/null +++ b/docs/changelog/md-1.2.5.md @@ -0,0 +1,68 @@ +# 1.2.5 + +1.2.5 is a maintenance release made in April 2020. + +## Resolved issues + +- {vytask}`T1020` OSPF Stops distributing default route after a while +- {vytask}`T1228` pppoe default-route force option not working (Rel 1.2.0-rc11) +- {vytask}`T1301` bgp peer-groups don't work when "no-ipv4-unicast" is enabled. +- {vytask}`T1341` Adding rate-limiter for pppoe server users +- {vytask}`T1376` Incorrect DHCP lease counting +- {vytask}`T1392` Large firewall rulesets cause the system to lose configuration + and crash at startup +- {vytask}`T1416` 2 dhcp server run in failover mode can't sync hostname with + each other +- {vytask}`T1452` accel-pppoe - add vendor option to shaper +- {vytask}`T1490` BGP configuration (is lost|not applied) when updating + 1.1.8 -> 1.2.1 +- {vytask}`T1780` Adding ipsec ike closeaction +- {vytask}`T1803` Unbind NTP while it's not requested... +- {vytask}`T1821` "authentication mode radius" has no effect for PPPoE server +- {vytask}`T1827` Increase default gc_thresh +- {vytask}`T1828` Missing completion helper for "set system syslog host + 192.0.2.1 facility all protocol" +- {vytask}`T1832` radvd adding feature DNSSL branch.example.com example.com to + existing package +- {vytask}`T1837` PPPoE unrecognized option 'replacedefaultroute' +- {vytask}`T1851` wireguard - changing the pubkey on an existing peer seems to + destroy the running config. +- {vytask}`T1858` l2tp: Delete depricated outside-nexthop and add gateway-address +- {vytask}`T1864` Lower IPSec DPD timeout lower limit from 10s -> 2s +- {vytask}`T1879` Extend Dynamic DNS XML definition value help strings and + validators +- {vytask}`T1881` Execute permissions are removed from custom SNMP scripts at + commit time +- {vytask}`T1884` Keeping VRRP transition-script native behaviour and adding + stop-script +- {vytask}`T1891` Router announcements broken on boot +- {vytask}`T1900` Enable SNMP for VRRP. +- {vytask}`T1902` Add redistribute non main table in bgp +- {vytask}`T1909` Incorrect behaviour of static routes with overlapping networks +- {vytask}`T1913` "system ipv6 blacklist" command has no effect +- {vytask}`T1914` IPv6 multipath hash policy does not apply +- {vytask}`T1917` Update WireGuard to Debian release 0.0.20191219-1 +- {vytask}`T1934` Change default hostname when deploy from OVA without params. +- {vytask}`T1935` NIC identification and usage problem in Hyper-V environments +- {vytask}`T1936` pppoe-server CLI control features +- {vytask}`T1964` SNMP Script-extensions allows names with spaces, but commit + fails +- {vytask}`T1967` BGP parameter "enforce-first-as" does not work anymore +- {vytask}`T1970` Correct adding interfaces on boot +- {vytask}`T1971` Missing modules in initrd.img for PXE boot +- {vytask}`T1998` Update FRR to 7.3 +- {vytask}`T2001` Error when router reboot +- {vytask}`T2032` Monitor bandwidth bits +- {vytask}`T2059` Set source-validation on bond vif don't work +- {vytask}`T2066` PPPoE interface can be created multiple times - last wins +- {vytask}`T2069` PPPoE-client does not works with service-name option +- {vytask}`T2077` ISO build from crux branch is failing +- {vytask}`T2079` Update Linux Kernel to v4.19.106 +- {vytask}`T2087` Add maxfail 0 option to pppoe configuration. +- {vytask}`T2100` BGP route adverisement wih checks rib +- {vytask}`T2120` "reset vpn ipsec-peer" doesn't work with named peers +- {vytask}`T2197` Cant add vif-s interface into a bridge +- {vytask}`T2228` WireGuard does not allow ports < 1024 to be used +- {vytask}`T2252` HTTP API add system image can return '504 Gateway Time-out' +- {vytask}`T2272` Set system flow-accounting disable-imt has syntax error +- {vytask}`T2276` PPPoE server vulnerability diff --git a/docs/changelog/md-1.2.6.md b/docs/changelog/md-1.2.6.md new file mode 100644 index 00000000..0815bb05 --- /dev/null +++ b/docs/changelog/md-1.2.6.md @@ -0,0 +1,104 @@ +# 1.2.6-S1 + +1.2.6-S1 is a security release release made in September 2020. + +## Resolved issues + +VyOS 1.2.6 release was found to be suspectible to CVE-2020-10995. It's a low- +impact vulnerability in the PowerDNS recursor that allows an attacker to cause +performance degradation via a specially crafted authoritative DNS server reply. + +- {vytask}`T2899` remote syslog server migration error on update + +# 1.2.6 + +1.2.6 is a maintenance release made in September 2020. + +(resovled-issues-1-2-6)= + +## Resolved issues + +- {vytask}`T103` DHCP server prepends shared network name to hostnames +- {vytask}`T125` Missing PPPoE interfaces in l2tp configuration +- {vytask}`T1194` cronjob is being setup even if not saved +- {vytask}`T1205` module pcspkr missing +- {vytask}`T1219` Redundant active-active configuration, asymmetric routing and + conntrack-sync cache +- {vytask}`T1220` Show transceiver information from plugin modules, e.g SFP+, + QSFP +- {vytask}`T1221` BGP - Default route injection is not processed by the specific + route-map +- {vytask}`T1241` Remove of policy route throws CLI error +- {vytask}`T1291` Under certain conditions the VTI will stay forever down +- {vytask}`T1463` Missing command `show ip bgp scan` appears in command + completion +- {vytask}`T1575` `show snmp mib ifmib` crashes with IndexError +- {vytask}`T1699` Default net.ipv6.route.max_size 32768 is too low +- {vytask}`T1729` PIM (Protocol Independent Multicast) implementation +- {vytask}`T1901` Semicolon in values is interpreted as a part of the shell + command by validators +- {vytask}`T1934` Change default hostname when deploy from OVA without params. +- {vytask}`T1938` syslog doesn't start automatically +- {vytask}`T1949` Multihop IPv6 BFD is unconfigurable +- {vytask}`T1953` DDNS service name validation rejects valid service names +- {vytask}`T1956` PPPoE server: support PADO-delay +- {vytask}`T1973` Allow route-map to match on BGP local preference value +- {vytask}`T1974` Allow route-map to set administrative distance +- {vytask}`T1982` Increase rotation for atop.acct +- {vytask}`T1983` Expose route-map when BGP routes are programmed in to FIB +- {vytask}`T1985` pppoe: Enable ipv6 modules without configured ipv6 pools +- {vytask}`T2000` strongSwan does not install routes to table 220 in certain + cases +- {vytask}`T2021` OSPFv3 doesn't support decimal area syntax +- {vytask}`T2062` Wrong dhcp-server static route subnet bytes +- {vytask}`T2091` swanctl.conf file is not generated properly is more than one + IPsec profile is used +- {vytask}`T2131` Improve syslog remote host CLI definition +- {vytask}`T2224` Update Linux Kernel to v4.19.114 +- {vytask}`T2286` IPoE server vulnerability +- {vytask}`T2303` Unable to delete the image version that came from OVA +- {vytask}`T2305` Add release name to "show version" command +- {vytask}`T2311` Statically configured name servers may not take precedence + over ones from DHCP +- {vytask}`T2327` Unable to create syslog server entry with different port +- {vytask}`T2332` Backport node option for a syslog server +- {vytask}`T2342` Bridge l2tpv3 + ethX errors +- {vytask}`T2344` PPPoE server client static IP assignment silently fails +- {vytask}`T2385` salt-minion: improve completion helpers +- {vytask}`T2389` BGP community-list unknown command +- {vytask}`T2398` op-mode "dhcp client leases interface" completion helper + misses interfaces +- {vytask}`T2402` Live ISO should warn when configuring that changes won't + persist +- {vytask}`T2443` NHRP: Add debugging information to syslog +- {vytask}`T2448` `monitor protocol bgp` subcommands fail with 'command + incomplete' +- {vytask}`T2458` Update FRR to 7.3.1 +- {vytask}`T2476` Bond member description change leads to network outage +- {vytask}`T2478` login radius: use NAS-IP-Address if defined source address +- {vytask}`T2482` Update PowerDNS recursor to 4.3.1 for CVE-2020-10995 +- {vytask}`T2517` vyos-container: link_filter: No such file or directory +- {vytask}`T2526` Wake-On-Lan CLI implementation +- {vytask}`T2528` "update dns dynamic" throws FileNotFoundError excepton +- {vytask}`T2536` "show log dns forwarding" still refers to dnsmasq +- {vytask}`T2538` Update Intel NIC drivers to recent release (preparation for + Kernel >=5.4) +- {vytask}`T2545` Show physical device offloading capabilities for specified + ethernet interface +- {vytask}`T2563` Wrong interface binding for Dell VEP 1445 +- {vytask}`T2605` SNMP service is not disabled by default +- {vytask}`T2625` Provide generic Library for package builds +- {vytask}`T2686` FRR: BGP: large-community configuration is not applied + properly after upgrading FRR to 7.3.x series +- {vytask}`T2701` `vpn ipsec pfs enable` doesn't work with IKE groups +- {vytask}`T2728` Protocol option ignored for IPSec peers in transport mode +- {vytask}`T2734` WireGuard: fwmark CLI definition is inconsistent +- {vytask}`T2757` "show system image version" contains additional new-line + character breaking output +- {vytask}`T2797` Update Linux Kernel to v4.19.139 +- {vytask}`T2822` Update Linux Kernel to v4.19.141 +- {vytask}`T2829` PPPoE server: mppe setting is implemented as node instead of + leafNode +- {vytask}`T2831` Update Linux Kernel to v4.19.142 +- {vytask}`T2852` rename dynamic dns interface breaks ddclient.cache permissions +- {vytask}`T2853` Intel QAT acceleration does not work diff --git a/docs/changelog/md-1.3.md b/docs/changelog/md-1.3.md new file mode 100644 index 00000000..70eeea87 --- /dev/null +++ b/docs/changelog/md-1.3.md @@ -0,0 +1,4317 @@ +# 1.3 Equuleus + +% Please don't add anything by hand. +% This file is managed by the script: +% _ext/releasenotes.py + +## 2024-04-25 + +- {vytask}`T6249` `(default): ISO builder fails because of changed buster-backport repository` + +## 2024-04-23 + +- {vytask}`T6261` `(default): Typo in op_mode connect_disconnect print statement for check_ppp_running` + +## 2024-04-17 + +- {vytask}`T6243` `(bug): Update vyos-http-api-tools for package idna security advisory` + +## 2024-04-12 + +- {vytask}`T3437` `(bug): BGP Confederation Addition Causes Error` + +## 2024-04-10 + +- {vytask}`T6124` `(bug): Docker equuleus build image doesn't build due to fpm` + +## 2024-04-08 + +- {vytask}`T6196` `(bug): Route-map and summary-only do not work in BGP aggregation at the same time` + +## 2024-04-07 + +- {vytask}`T1244` `(default): Support for StartupResync in conntrackd` + +## 2024-04-05 + +- {vytask}`T2590` `(bug): DHCPv6 not updating nameservers and search domains since replacing isc-dhcp-client with WIDE dhcp6c` + +## 2024-04-04 + +- {vytask}`T4146` `(bug): Nginx should not listen on port 80` +- {vytask}`T1976` `(default): deleting address-family under neighbor will disable neighbor` +- {vytask}`T5625` `(default): "restart vpn" does not work if ipsec-interfaces is not set` +- {vytask}`T3020` `(bug): The "scp" example is wrong in the bash-completion for "set system config-management commit-archive location"` +- {vytask}`T2250` `(default): vyos-build "make iso" error if configure was ran outside of the docker container` +- {vytask}`T2139` `(default): openvpn: allow "dh-file none" to disable DH for ECDH keys` +- {vytask}`T2014` `(default): Use vendor specific NTP Pool hostname` +- {vytask}`T1118` `(bug): Obsolete "utc" option in time selector in firewall` +- {vytask}`T948` `(feature): integrate aws cloud watch scripts into AMI` + +## 2024-04-02 + +- {vytask}`T6150` `(bug): Impossible to set a static IP address via Radius in IPoE` + +## 2024-04-01 + +- {vytask}`T6193` `(bug): dhcp-client: invalid warning "is not a DHCP interface but uses DHCP name-server option" for VLAN interfaces` + +## 2024-03-22 + +- {vytask}`T6110` `(bug): dhcp server - If failover is defined, range is required` +- {vytask}`T5624` `(default): Remove /etc/debian_version from the image` + +## 2024-03-11 + +- {vytask}`T2998` `(bug): SNMP v3 oid "exclude" option doesn't work` +- {vytask}`T6096` `(bug): Config commits are not synced properly because 00vyos-sync is deleted by vyos-router` +- {vytask}`T6057` `(feature): Add ability to disable syslog for conntrackd` +- {vytask}`T5504` `(feature): Keepalived VRRP ability to set more than one peer-address` + +## 2024-03-07 + +- {vytask}`T3992` `(bug): Traceback on adding interface to bridge with configured ip address` + +## 2024-03-06 + +- {vytask}`T6088` `(bug): Configuration corrupted after saving and powercut or force reboot` + +## 2024-02-16 + +- {vytask}`T2113` `(bug): OpenVPN Options error: you cannot use --verify-x509-name with --compat-names or --no-name-remapping` +- {vytask}`T5418` `(bug): PPPoE-Server Client IP pool Subnet` + +## 2024-02-15 + +- {vytask}`T2612` `(bug): HTTPS API, changing API key fails but goes through` +- {vytask}`T656` `(enhancment): Rewrite wirelessmodem in new style XML interface definition` + +## 2024-02-14 + +- {vytask}`T2044` `(bug): RPKI doesn't boot properly` + +## 2024-02-08 + +- {vytask}`T6014` `(feature): Bump keepalived version` + +## 2024-02-07 + +- {vytask}`T6017` `(bug): Update vyos-http-api-tools for security advisory` + +## 2024-02-02 + +- {vytask}`T5914` `(bug): CVE-2023-48795 - Terrapin vulnerability` +- {vytask}`T5739` `(bug): Password recovery does not work if public keys are configured` + +## 2024-02-01 + +- {vytask}`T5967` `(bug): Multi-hop BFD connections can't be established; please add minimum-ttl option.` + +## 2024-01-22 + +- {vytask}`T4721` `(feature): Static IPv6 Route Tags Missing` + +## 2024-01-20 + +- {vytask}`T5187` `(bug): Update Realtek r8152 driver` +- {vytask}`T5182` `(bug): Update Intel ice driver` +- {vytask}`T5180` `(bug): initramfs-tools ignores firmware from updates directory` +- {vytask}`T4990` `(bug): Commit results may not be properly saved if power is cut immediately after a successful commit` +- {vytask}`T4039` `(feature): Rsyslog to use 'protocol23format' for protocol UDP` +- {vytask}`T3813` `(bug): Some custom sysctl parameters can't be applied bug` +- {vytask}`T2579` `(feature): The root task for VRF features` +- {vytask}`T2546` `(feature): The root task for rewriting [op-mode] to XML` +- {vytask}`T2452` `(default): Serial console related issues` + +## 2024-01-19 + +- {vytask}`T5543` `(bug): Fix source address handling in static joins` + +## 2024-01-14 + +- {vytask}`T5715` `(bug): IPSec VPN: restart vpn is not working` + +## 2024-01-13 + +- {vytask}`T5924` `(bug): Build cannot pass the smoketest dialup-router-medium-vpn` + +## 2024-01-11 + +- {vytask}`T5275` `(default): Add op mode commands for exporting certificates to PEM files with correct headers` +- {vytask}`T5274` `(default): Add a deprecation warning for OpenVPN site-to-site with pre-shared secret` +- {vytask}`T3191` `(bug): PAM RADIUS freezing when accounting does not configured on RADIUS server` + +## 2024-01-10 + +- {vytask}`T4646` `(bug): USB serial output console does not work` +- {vytask}`T4466` `(bug): intel i225-v nic does not detect link after boot` +- {vytask}`T4222` `(feature): Support for TWAMP as round-trip metric` +- {vytask}`T1369` `(bug): GCP Networking Failure` + +## 2024-01-09 + +- {vytask}`T3242` `(bug): PPPoE Server overhead on virtual interfaces creation` +- {vytask}`T2755` `(default): Requirements for partial interface setup` +- {vytask}`T2494` `(bug): systemd dependencies issues` +- {vytask}`T2343` `(feature): Disable memory ballooning in VM templates` +- {vytask}`T2254` `(default): Provide more information on the build branch in the version data` +- {vytask}`T2223` `(feature): convert operational show interfaces to python/XML` +- {vytask}`T1925` `(bug): DMVPN is always listed as down in "show vpn ipsec sa"` +- {vytask}`T1297` `(feature): Add GARP settings to VRRP/keepalived` + +## 2024-01-08 + +- {vytask}`T5318` `(bug): Security Vulnerabilities for VyOS 1.3.3` +- {vytask}`T3980` `(bug): vrrp transition-script validator makes warning fatal and also causes a python NameError exception` +- {vytask}`T2799` `(feature): VyOS Certificates Manager` + +## 2023-12-29 + +- {vytask}`T5852` `(bug): Reboots fail with eapol WAN interface` + +## 2023-12-22 + +- {vytask}`T4760` `(bug): VyOS does not support running multiple instances of DHCPv6 clients` + +## 2023-12-21 + +- {vytask}`T5714` `(bug): IPSec VPN: op-mode: "show log vpn" does not show results` +- {vytask}`T3039` `(feature): Resize a root partition and filesystem automatically during deployment in virtual environments` +- {vytask}`T2404` `(bug): Cannot change MTU` +- {vytask}`T2353` `(bug): Interface [conf_mode] errors parent task` +- {vytask}`T5796` `(bug): Openconnect - HTTPS security headers are missing` + +## 2023-12-19 + +- {vytask}`T2116` `(feature): Processing configuration via Cloud-init User-Data` + +## 2023-12-18 + +- {vytask}`T2191` `(feature): Using tallow to block sshd probes` + +## 2023-12-15 + +- {vytask}`T5824` `(bug): busybox cannot connect some websites from initramfs` + +## 2023-12-12 + +- {vytask}`T5817` `(bug): Show openvpn server fails in some cases` +- {vytask}`T5413` `(default): Deny the opportunity to use one public/private key pair on both wireguard peers.` + +## 2023-11-30 + +- {vytask}`T4601` `(bug): dhcp : relay agent IP address issue.` + +## 2023-11-28 + +- {vytask}`T5777` `(bug): frr: backport and upstream recent bgpd daemon crashes` + +## 2023-11-27 + +- {vytask}`T5763` `(bug): Fix imprecise check for remote file name in vyos-load-config.py` + +## 2023-11-25 + +- {vytask}`T5655` `(bug): commit-archive: Ctrl+C should not eror out with stack trace, signal should be cought` + +## 2023-11-24 + +- {vytask}`T5402` `(bug): VRRP router with rfc3768-compatibility sends multiple ARP replies` + +## 2023-11-22 + +- {vytask}`T5578` `(bug): "ikev2-reauth" description contains outdated information` + +## 2023-11-15 + +- {vytask}`T5661` `(enhancment): Add show show ssh dynamic-protection attacker and show log ssh dynamic-protection` +- {vytask}`T1276` `(bug): dhcp relay + VLAN fails` + +## 2023-11-07 + +- {vytask}`T5586` `(feature): Disable by default SNMP for Keepalived VRRP` + +## 2023-11-06 + +- {vytask}`T4269` `(feature): node.def generator should automatically add default values` + +## 2023-10-26 + +- {vytask}`T5684` `(bug): services using VRF generates the error "Failed to load BPF prog: 'Operation not permitted'" when the system boots.` +- {vytask}`T5594` `(bug): VRRP - Error if using IPv6 Link Local as hello source address` + +## 2023-10-21 + +- {vytask}`T5670` `(bug): bridge: missing member interface validator` +- {vytask}`T5191` `(default): Replace underscores with hyphens in command-line options generated by vyos.opmode` +- {vytask}`T4402` `(bug): OpenVPN client-ip-pool option is broken` +- {vytask}`T2719` `(feature): Standardized op mode script structure` + +## 2023-10-19 + +- {vytask}`T5669` `(bug): VXLAN interface changing port does not work` + +## 2023-10-17 + +- {vytask}`T5235` `(bug): SSH keys with special characters cannot be applied via Cloud-init` + +## 2023-10-08 + +- {vytask}`T5630` `(feature): pppoe: allow to specify MRU in addition to already configurable MTU` + +## 2023-10-06 + +- {vytask}`T5576` `(feature): Add bgp remove-private-as all option` + +## 2023-10-04 + +- {vytask}`T5632` `(feature): Add jq package to parse JSON files` + +## 2023-09-25 + +- {vytask}`T5533` `(bug): Keepalived VRRP IPv6 group enters in FAULT state` + +## 2023-09-20 + +- {vytask}`T5271` `(default): Add support for peer-fingerprint to OpenVPN` + +## 2023-09-11 + +- {vytask}`T5557` `(bug): bgp: Use treat-as-withdraw for tunnel encapsulation attribute CVE-2023-38802` +- {vytask}`T3424` `(default): PPPoE IA-PD doesn't work in VRF` + +## 2023-09-10 + +- {vytask}`T5555` `(bug): Fix timezone migrator (system 13-to-14)` +- {vytask}`T5545` `(bug): sflow is not working` + +## 2023-09-08 + +- {vytask}`T4426` `(default): Add arpwatch to the image` + +## 2023-09-05 + +- {vytask}`T5524` `(feature): Add config directory to liveCD` +- {vytask}`T2958` `(bug): DHCP server doesn't work from a live CD` +- {vytask}`T5428` `(bug): dhcp: client renewal fails when running inside VRF` + +## 2023-09-04 + +- {vytask}`T5506` `(bug): Container bridge interfaces do not have a link-local address` + +## 2023-08-31 + +- {vytask}`T5190` `(feature): Cloud-Init cannot fetch Meta-data on machines where the main Ethernet interface is not eth0` +- {vytask}`T5140` `(bug): Firewall network-group problems` +- {vytask}`T4895` `(bug): Tag nodes are overwritten when configured by Cloud-Init from User-Data` +- {vytask}`T4874` `(default): Add Warning message to Equuleus` +- {vytask}`T4855` `(bug): Trying to create more than one tunnel of the same type to the same address causes unhandled exception` +- {vytask}`T4776` `(bug): NVME storage is not detected properly during installation` +- {vytask}`T3546` `(feature): Add support for running scripts on PPPoE server session events` +- {vytask}`T738` `(feature): Add local-port and resolver port options for powerdns in CLI configuration tree` + +## 2023-08-30 + +- {vytask}`T5221` `(bug): BGP as-override behavior differs from new FRR and other vendors` +- {vytask}`T4933` `(default): Malformed lines cause vyos.util.colon_separated_to_dict fail with a nondescript error` +- {vytask}`T4790` `(bug): RADIUS login does not work if sum of timeouts more than 50s` +- {vytask}`T4475` `(bug): route-map does not support ipv6 peer` +- {vytask}`T4459` `(bug): API service with VRF doesn't work in 1.3.1` +- {vytask}`T4407` `(bug): Network-config v2 is broken in Cloud-init 22.1 and VyOS 1.3` +- {vytask}`T4113` `(bug): Incorrect GRUB configuration parsing` +- {vytask}`T1764` `(bug): Use lists instead of whitespace-separated strings in vyos.config` +- {vytask}`T4121` `(bug): Nameservers from DHCP client cannot be used in specific cases` +- {vytask}`T4151` `(feature): IPV6 local PBR Support` +- {vytask}`T4306` `(default): Do not check for ditry repository when building release images` + +## 2023-08-29 + +- {vytask}`T3940` `(bug): DHCP client does not remove IP address when stopped by the 02-vyos-stopdhclient hook` +- {vytask}`T3713` `(default): Create a meta-package for user utilities` +- {vytask}`T3339` `(bug): Cloud-Init domain search setting not applied` +- {vytask}`T2640` `(feature): Running VyOS inside Docker containers` +- {vytask}`T3577` `(bug): Generating vpn x509 key pair fails with command not found` + +## 2023-08-28 + +- {vytask}`T4745` `(bug): CLI TAB issue with values with '-' at the beginning in conf mode` +- {vytask}`T2611` `(bug): Prefix list names are shared between ipv4 and ipv6` +- {vytask}`T2296` `(default): Upgrade WALinux to 2.2.41` +- {vytask}`T2123` `(default): Configure 3 NTP servers` +- {vytask}`T469` `(bug): Problem after commit with errors` + +## 2023-08-25 + +- {vytask}`T4412` `(bug): commit archive: reboot not working with sftp` +- {vytask}`T3702` `(feature): Policy: Allow routing by fwmark` +- {vytask}`T3536` `(default): Unable to list all available routes` + +## 2023-08-24 + +- {vytask}`T5006` `(bug): Http api segfault with concurrent requests` +- {vytask}`T5305` `(bug): REST API configure operation should not be defined as async` + +## 2023-08-23 + +- {vytask}`T5387` `(feature): dhcp6c: add a no release option` + +## 2023-08-20 + +- {vytask}`T5470` `(bug): wlan: can not disable interface if SSID is not configured` + +## 2023-08-17 + +- {vytask}`T5486` `(bug): Service dns dynamic cannot pass the smoketest` +- {vytask}`T5223` `(bug): tunnel key doesn't clear` + +## 2023-08-15 + +- {vytask}`T5273` `(default): Add op mode commands for displaying certificate details and fingerprints` +- {vytask}`T5270` `` (default): Make OpenVPN `tls dh-params` optional `` + +## 2023-08-10 + +- {vytask}`T5329` `(bug): Wireguard interface as GRE tunnel source causes configuration error on boot` + +## 2023-07-24 + +- {vytask}`T5354` `(feature): Add sshguard to protect against brut-forces for 1.3` + +## 2023-07-17 + +- {vytask}`T2051` `(bug): Throughput anomalies` + +## 2023-07-14 + +- {vytask}`T305` `(default): loadbalancing does not work with one pppoe connection and another connection of either dhcp or static` + +## 2023-07-13 + +- {vytask}`T3045` `(bug): Changes to Conntrack-Sync don't apply correctly (Mutlicast->UDP)` +- {vytask}`T971` `(bug): authentication public-keys options quoting issue` + +## 2023-07-12 + +- {vytask}`T5009` `(bug): op-mode command: restart dhcp relay-agent not working` +- {vytask}`T4927` `(bug): Need to change restart to reload-or-restart in Webproxy module` +- {vytask}`T3835` `(bug): vyos router 1.2.7 snmp Dos bug` +- {vytask}`T4959` `(feature): Add container registry authentication config for containers` +- {vytask}`T425` `(feature): AWS CloudWatch monitoring scripts` + +## 2023-07-11 + +- {vytask}`T4862` `(bug): webproxy domain-block does not work` +- {vytask}`T4844` `(bug): Incorrect permissions of the safeguard DB directory` +- {vytask}`T4262` `(bug): install image doesn't respect chosen root partition size` +- {vytask}`T3810` `(bug): webproxy squidguard rules don't work properly after rewriting to python.` +- {vytask}`T1928` `(bug): Is the 'Welcome to VyOS' message when using SSH an information leak?` +- {vytask}`T4737` `(bug): FRRouting/zebra 7.5.1 does not redistribute routes to other protocols` +- {vytask}`T3852` `(bug): DHCP client issue - interface has two dhclient processes when link is unpluged and then plug again` +- {vytask}`T2118` `(bug): Failure to boot after power outage due to dirty filesystem and no fsck in initramfs` + +## 2023-07-05 + +- {vytask}`T5331` `(bug): ath10k_pci not functioning` + +## 2023-06-30 + +- {vytask}`T5315` `(feature): vrrp: add support for version 3` +- {vytask}`T5313` `(bug): UDP broadcast relay - missing verify() that relay interfaces have an IP address assigned` + +## 2023-06-26 + +- {vytask}`T5272` `(default): Upgrade OpenVPN to 2.6 in Equuleus` +- {vytask}`T5265` `(bug): WAN load-balancing: missing completion helpers` + +## 2023-06-25 + +- {vytask}`T5240` `(bug): Service router-advert failed to start radvd with more then 3 name-servers` + +## 2023-06-21 + +- {vytask}`T5280` `(bug): Update Expired keys (2023-06-08) for PowerDNS` + +## 2023-06-13 + +- {vytask}`T5213` `(feature): Accel-ppp sending accounting interim updates acct-interim-interval option` + +## 2023-05-29 + +- {vytask}`T5243` `(bug): Default route is inactive if an interface has multiple ip addresses of the same subnet in 1.3.2 Equuleus` + +## 2023-05-19 + +- {vytask}`T5186` `(bug): QoS test cannot pass for 1.3` + +## 2023-05-12 + +- {vytask}`T2769` `(feature): Add VRF support for syslog` + +## 2023-05-08 + +- {vytask}`T5212` `(bug): snmp community name -error with special carracter` + +## 2023-04-27 + +- {vytask}`T5175` `(bug): http-api: error in MultiPart parser for FastAPI version >= 0.91.0` +- {vytask}`T5176` `(bug): http-api: update vyos-http-api-tools for FastAPI security vulnerability` + +## 2023-04-13 + +- {vytask}`T5152` `(bug): Telegraf agent hostname isn't qualified` +- {vytask}`T4727` `(feature): Add RADIUS rate limit support to PPTP server` +- {vytask}`T4939` `(bug): VRRP command no-preempt not work as expected` +- {vytask}`T3608` `(default): Standardize warnings from configure scripts` + +## 2023-04-05 + +- {vytask}`T4975` `(bug): CLI does not work after cutting off the power or reset` +- {vytask}`T5136` `(bug): Possible config corruption on upgrade` + +## 2023-04-01 + +- {vytask}`T5047` `(bug): Recreate only a specific container` + +## 2023-03-31 + +- {vytask}`T5111` `(bug): pppd-dns.service startup failed` + +## 2023-03-29 + +- {vytask}`T5033` `(bug): generate-public-key command fails for address with multiple public keys like GitHub` +- {vytask}`T5097` `(bug): the operational command "show interfaces ethernet ethx" doesn't reflect a call to 'clear counters'` + +## 2023-03-21 + +- {vytask}`T5098` `(feature): PPPoE client holdoff configuration` + +## 2023-03-19 + +- {vytask}`T4925` `(feature): Need to add the possibility to configure Pseudo-Random Functions (PRF) in IKEv2` + +## 2023-03-16 + +- {vytask}`T3083` `(feature): Add feature event-handler` +- {vytask}`T2516` `(bug): vyos-container: cannot configure ethernet interface` + +## 2023-03-09 + +- {vytask}`T5066` `(bug): Different GRE tunnel but same tunnel keys error` + +## 2023-03-08 + +- {vytask}`T4381` `(default): OpenVPN: Add "Tunnel IP" column in "show openvpn server" operational command` +- {vytask}`T4872` `(bug): Op-mode show openvpn misses a case when parsing for tunnel IP` + +## 2023-03-07 + +- {vytask}`T2838` `(bug): Ethernet device names changing, multiple hw-id being added` +- {vytask}`T2649` `(default): Ensure configration mode scripts conform to coding guidelines` +- {vytask}`T4900` `(default): Cache intermediary results of get_config_diff in Config instance` + +## 2023-03-03 + +- {vytask}`T4625` `(enhancment): Update ocserv to current revision (1.1.6)` + +## 2023-02-28 + +- {vytask}`T4955` `(bug): Openconnect radiusclient.conf generating with extra authserver` +- {vytask}`T4219` `(feature): support incoming-interface (iif) in local PBR` + +## 2023-02-25 + +- {vytask}`T5008` `(bug): MACsec CKN of 32 chars is not allowed in CLI, but works fine` +- {vytask}`T5007` `(bug): Interface multicast setting is invalid` +- {vytask}`T5017` `(bug): Bug with validator interface-name` +- {vytask}`T4992` `(bug): Incorrect check is_local_address for bgp neighbor with option ip_nonlocal_bind set` +- {vytask}`T4978` `(bug): KeyError: 'memory' container_config['memory'] on upgrading to 1.4-rolling-202302041536` +- {vytask}`T4948` `(feature): pppoe: add CLI option to allow definition of host-uniq flag` + +## 2023-02-22 + +- {vytask}`T5011` `(bug): Some interface drivers don't support min_mtu and max_mtu and verify_mtu check should be skipped` + +## 2023-02-18 + +- {vytask}`T4743` `(feature): Enable IPv6 address for Dynamic DNS` + +## 2023-02-16 + +- {vytask}`T4971` `(feature): Radius attribute "Framed-Pool" for PPPoE` + +## 2023-02-15 + +- {vytask}`T4993` `(bug): Can't delete conntrack ignore rule` + +## 2023-02-14 + +- {vytask}`T4999` `(feature): vyos.util backport dict_search_recursive` +- {vytask}`T1993` `(feature): Extended pppoe rate-limiter` + +## 2023-02-13 + +- {vytask}`T4153` `(bug): Monitor bandwidth-test initiate not working` + +## 2023-02-11 + +- {vytask}`T2603` `(feature): pppoe-server: reduce min MTU` + +## 2023-02-08 + +- {vytask}`T1288` `(feature): FRR: rewrite staticd backend (/opt/vyatta/share/vyatta-cfg/templates/protocols/static/*)` + +## 2023-02-07 + +- {vytask}`T4117` `(bug): Does not possible to configure PoD/CoA for L2TP vpn` + +## 2023-02-01 + +- {vytask}`T4970` `(default): pin OCaml pcre package to avoid JIT support` + +## 2023-01-30 + +- {vytask}`T4954` `(bug): DNS cannot be configured via Network-Config v1 received from ConfigDrive / Cloud-Init` + +## 2023-01-24 + +- {vytask}`T4949` `(feature): Backport "monitor log" and "show log" op-mode definitions from current to equuleus` +- {vytask}`T4947` `(feature): Support mounting container volumes as ro or rw` + +## 2023-01-23 + +- {vytask}`T4798` `(default): Migrate the file-exists validator away from Python` +- {vytask}`T4683` `(enhancment): Add kitty-terminfo package to build` +- {vytask}`T4875` `(default): Replace Python validator 'interface-name' to avoid Python startup cost` +- {vytask}`T4664` `(bug): Add validation to reject whitespace in tag node value names` + +## 2023-01-22 + +- {vytask}`T4906` `(bug): ipsec connections shows only one connection as up` + +## 2023-01-21 + +- {vytask}`T4896` `(bug): ospfv3: Fix broken not-advertise option` +- {vytask}`T4799` `(bug): PowerDNS >= 4.7 does not get reloaded by vyos-hostsd` + +## 2023-01-17 + +- {vytask}`T4902` `(bug): snmpd: exclude container storage from monitoring` + +## 2023-01-15 + +- {vytask}`T4832` `(feature): dhcp: Add IPv6-only dhcp option support (RFC 8925)` +- {vytask}`T4918` `(bug): Odd show interface behavior` + +## 2023-01-09 + +- {vytask}`T4922` `(feature): Add ssh-client source-interface CLI option` + +## 2023-01-07 + +- {vytask}`T4884` `(bug): Missing a community6 in snmpd config` + +## 2023-01-05 + +- {vytask}`T3937` `(default): Rewrite "show system memory" in Python to make it usable as a library function` + +## 2023-01-03 + +- {vytask}`T4869` `` (bug): A network with `/32` or `/128` mask cannot be removed from a network-group `` + +## 2022-12-31 + +- {vytask}`T4898` `(feature): Add mtu config option for dummy interfaces` + +## 2022-12-26 + +- {vytask}`T4511` `(bug): IPv6 DNS lookup` +- {vytask}`T4809` `(feature): radvd: Allow use of AdvRASrcAddress` + +## 2022-12-18 + +- {vytask}`T4709` `(bug): TCP MSS clamping broken in equuleus` + +## 2022-12-15 + +- {vytask}`T4671` `(bug): linux-firmware package is missing symlinks defined in WHENCE file` + +## 2022-12-04 + +- {vytask}`T4825` `(feature): interfaces veth/veth-pairs -standalone used` + +## 2022-12-02 + +- {vytask}`T4122` `(bug): interface ip address config missing after upgrade from 1.2.8 to 1.3.0 (when redirect is configured?)` +- {vytask}`T1024` `(feature): Policy Based Routing by DSCP` + +## 2022-11-23 + +- {vytask}`T4793` `(feature): Create warning message about disable-route-autoinstall when ipsec vti is used` + +## 2022-11-21 + +- {vytask}`T4812` `(feature): IPsec ability to show all configured connections` + +## 2022-11-06 + +- {vytask}`T2913` `(bug): Failure to install fpm while building builder docker image` + +## 2022-11-04 + +- {vytask}`T2417` `(feature): Python validator cleanup` + +## 2022-11-01 + +- {vytask}`T4177` `(bug): Strip-private doesn't work for service monitoring` + +## 2022-10-31 + +- {vytask}`T1875` `(feature): Add the ability to use network address as BGP neighbor (bgp listen range)` +- {vytask}`T4785` `(feature): snmp: Allow !, @, * and # in community name` + +## 2022-10-21 + +- {vytask}`T2189` `(bug): Adding a large port-range will take ~ 20 minutes to commit` + +## 2022-10-18 + +- {vytask}`T4533` `(bug): Radius clients don’t have simple permissions` + +## 2022-10-13 + +- {vytask}`T4312` `(bug): Telegraf configuration doesn't accept IPs for URL` + +## 2022-10-12 + +- {vytask}`T4730` `(bug): Conntrack-sync error - listen-address is not the correct type in config as it should be` + +## 2022-10-11 + +- {vytask}`T4680` `(bug): Telegraf prometheus-client listen-address invalid format` + +## 2022-10-04 + +- {vytask}`T4702` `(bug): Wireguard peers configuration is not synchronized with CLI` +- {vytask}`T4652` `(feature): Upgrade PowerDNS recursor to 4.7 series` +- {vytask}`T4648` `(default): PPPoE: Ignore default router from RA when PPPoE default-route is set to none` +- {vytask}`T4582` `(default): Router-advert: Preferred lifetime cannot equal valid lifetime in PIOs` + +## 2022-09-17 + +- {vytask}`T4666` `(bug): EAP-TLS no longer allows TLSv1.0 after T4537, T4584` + +## 2022-09-15 + +- {vytask}`T4679` `(bug): OpenVPN site-to-site incorrect check for IPv6 local and remote address` +- {vytask}`T4630` `(bug): Prevent attempts to use the same interface as a source interface for pseudo-ethernet and MACsec at the same time` + +## 2022-09-12 + +- {vytask}`T4647` `(feature): Add Google Virtual NIC (gVNIC) support` + +## 2022-09-05 + +- {vytask}`T4668` `(bug): Adding/removing members from bond doesn't work/results in incorrect interface state` +- {vytask}`T4628` `(bug): ConfigTree() throws ValueError() if tagNode contains whitespaces` + +## 2022-08-29 + +- {vytask}`T4653` `(bug): Interface offload options are not applied correctly` +- {vytask}`T4061` `(default): Add util function to check for completion of boot config` +- {vytask}`T4654` `(bug): RPKI cache incorrect description` +- {vytask}`T4572` `(bug): Add an option to force interface MTU to the value received from DHCP` + +## 2022-08-26 + +- {vytask}`T4642` `(bug): proxy: hyphen not allowed in proxy URL` + +## 2022-08-23 + +- {vytask}`T4618` `(bug): Traffic policy not set on virtual interfaces` +- {vytask}`T4538` `(bug): Macsec does not work correctly when the interface status changes.` + +## 2022-08-22 + +- {vytask}`T4629` `(bug): Raised ConfigErrors contain dict instead of only the dict key` +- {vytask}`T4632` `(bug): VLAN-aware bridge not working` + +## 2022-08-19 + +- {vytask}`T4616` `(bug): openconnect: KeyError: 'local_users'` +- {vytask}`T4614` `(feature): OpenConnect split-dns directive` + +## 2022-08-16 + +- {vytask}`T4592` `(bug): macsec: can not create two interfaces using the same source-interface` +- {vytask}`T4584` `(bug): hostap: create custom package build` +- {vytask}`T4537` `(bug): MACsec not working with cipher gcm-aes-256` + +## 2022-08-15 + +- {vytask}`T4565` `(bug): vlan aware bridge not working with - Kernel: T3318: update Linux Kernel to v5.4.205 #249` +- {vytask}`T4206` `(bug): Policy Based Routing with DHCP Interface Issue` +- {vytask}`T2763` `(feature): New SNMP resource request - SNMP over TCP` + +## 2022-08-14 + +- {vytask}`T4579` `(bug): bridge: can not delete member interface CLI option when VLAN is enabled` +- {vytask}`T4421` `(default): Add support for floating point numbers in the numeric validator` +- {vytask}`T4415` `(bug): Include license/copyright files in the image but remove user documentation from /usr/share/doc to reduce its size` +- {vytask}`T4313` `(bug): "generate public-key-command" throws unhandled exceptions when it cannot retrieve the key` +- {vytask}`T4082` `(bug): Add op mode command to restart ldpd` +- {vytask}`T3714` `(bug): Some sysctl custom parameters disappear after reboot` +- {vytask}`T4260` `(bug): Extend vyos.configdict.node_changed() to support recursiveness` +- {vytask}`T3785` `(default): Add unicode support to configtree backend` +- {vytask}`T3507` `(bug): Bond with mode LACP show u/u in show interfaces even if peer is not configured` + +## 2022-08-11 + +- {vytask}`T4476` `(default): Next steps after installation is not communicated properly to new users` + +## 2022-08-02 + +- {vytask}`T4515` `(default): Reduce telegraf binary size` + +## 2022-07-30 + +- {vytask}`T4575` `(feature): vyos.utill add new wrapper "rc_cmd" to get the return code and output` +- {vytask}`T4532` `(bug): Flow-accounting IPv6 server/receiver bug` + +## 2022-07-27 + +- {vytask}`T4571` `(bug): Sflow with vrf configured does not use vrf to validate agent-address IP from vrf-configured interfaces` + +## 2022-07-18 + +- {vytask}`T4228` `(bug): bond: OS error thrown when two bonds use the same member` +- {vytask}`T4534` `(bug): bond: bridge: error out if member interface is assigned to a VRF instance` +- {vytask}`T4525` `(bug): Delete interface from VRF and add it to bonding error` +- {vytask}`T4522` `(feature): bond: add ability to specify mii monitor interval via CLI` +- {vytask}`T4521` `(bug): bond: ARP monitor interval is not configured despite set via CLI` + +## 2022-07-14 + +- {vytask}`T4491` `(bug): Use empty string for internal name of root node of config_tree` + +## 2022-07-13 + +- {vytask}`T1375` `(feature): Add clear dhcp server lease function` + +## 2022-07-12 + +- {vytask}`T4527` `(bug): Prevent to create VRF name default` +- {vytask}`T4084` `(default): Dehardcode the default login banner` +- {vytask}`T3864` `(enhancment): Add Edgecore build to VyOS 1.3 Equuleus` + +## 2022-07-09 + +- {vytask}`T4507` `(feature): IPoE-server add multiplier option for shaper` +- {vytask}`T4468` `(bug): web-proxy source group cannot start with a number bug` +- {vytask}`T4373` `(feature): PPPoE-server add multiplier option for shaper` + +## 2022-07-07 + +- {vytask}`T4456` `(bug): NTP client in VRF tries to bind to interfaces outside VRF, logs many messages` +- {vytask}`T4509` `(feature): Feature Request: DNS64` + +## 2022-07-06 + +- {vytask}`T4513` `(bug): Webproxy monitor commands do not work` + +## 2022-07-05 + +- {vytask}`T4510` `(bug): set system static-host-mapping doesn't allow IPv4 and IPv6 for same name.` +- {vytask}`T2654` `(bug): Multiple names unable to be assigned to the same static mapping` +- {vytask}`T2683` `(default): no dual stack in system static-host-mapping host-name` + +## 2022-07-01 + +- {vytask}`T4489` `(bug): MPLS sysctl not persistent for tunnel interfaces` + +## 2022-06-20 + +- {vytask}`T1856` `(feature): Support configuring IPSec SA bytes` + +## 2022-06-16 + +- {vytask}`T3866` `(bug): Configs with DNS forwarding listening on OpenVPN interfaces or interfaces without a fixed address cannot be migrated to the new syntax` + +## 2022-06-15 + +- {vytask}`T1890` `(feature): Metatask: rewrite flow-accounting to XML and Python` + +## 2022-06-09 + +- {vytask}`T2580` `(feature): Support for ip pools for ippoe` + +## 2022-06-08 + +- {vytask}`T4447` `` (bug): DHCPv6 prefix delegation `sla-id` limited to 128 `` +- {vytask}`T4350` `(bug): DMVPN opennhrp spokes dont work behind NAT` + +## 2022-05-30 + +- {vytask}`T4315` `(feature): Telegraf - Output to prometheus` + +## 2022-05-27 + +- {vytask}`T4441` `(bug): wwan: connection not possible after a change added after 1.3.1-S1 release` + +## 2022-05-26 + +- {vytask}`T4442` `(feature): HTTP API add action "reset"` + +## 2022-05-25 + +- {vytask}`T2194` `(default): "show firewall" garbled output` + +## 2022-05-19 + +- {vytask}`T4430` `(bug): Show firewall output with visual shift default rule` + +## 2022-05-16 + +- {vytask}`T4377` `(default): generate tech-support archive includes previous archives` + +## 2022-05-12 + +- {vytask}`T4100` `(feature): Firewall increase maximum number of rules` + +## 2022-05-11 + +- {vytask}`T4405` `` (bug): DHCP client sometimes ignores `no-default-route` option of an interface `` + +## 2022-05-10 + +- {vytask}`T1972` `(feature): Allow setting interface name for virtual_ipaddress in VRRP VRID` + +## 2022-05-07 + +- {vytask}`T4361` `` (bug): `vyos.config.exists()` does not work for nodes with multiple values `` +- {vytask}`T4354` `(bug): Slave interfaces fall out from bonding during configuration change` + +## 2022-05-03 + +- {vytask}`T4395` `(feature): Extend show vpn debug` + +## 2022-05-01 + +- {vytask}`T4369` `(bug): OpenVPN: daemon not restarted on changes to "openvpn-option" CLI node` +- {vytask}`T4363` `(bug): salt-minion: default mine_interval option is not set` + +## 2022-04-29 + +- {vytask}`T4388` `(bug): dhcp-server: missing constraint on tftp-server-name option` +- {vytask}`T4366` `(bug): geneve: interface is removed on changes to e.g. description` + +## 2022-04-26 + +- {vytask}`T4235` `(default): Add config tree diff algorithm` + +## 2022-04-19 + +- {vytask}`T4344` `(bug): DHCP statistics not matching, conf-mode generates incorrect pool name with dash` +- {vytask}`T4268` `(bug): Elevated LA while using VyOS monitoring feature` + +## 2022-04-08 + +- {vytask}`T4331` `(bug): IPv6 link local addresses are not configured when an interface is in a VRF` +- {vytask}`T4339` `(bug): wwan: tab-completion results in "No such file or directory" if there is no WWAN interface` +- {vytask}`T4338` `(bug): wwan: changing interface description should not trigger reconnect` +- {vytask}`T4324` `(bug): wwan: check alive script should only be run via cron if a wwan interface is configured at all` + +## 2022-04-07 + +- {vytask}`T4330` `(bug): MTU settings cannot be applied when IPv6 is disabled` +- {vytask}`T4346` `(feature): Deprecate "system ipv6 disable" option to disable address family within OS kernel` +- {vytask}`T4337` `(bug): isis: IETF SPF delay algorithm can not be configured - results in vyos.frr.CommitError` +- {vytask}`T4319` `(bug): The command "set system ipv6 disable" doesn't work as expected.` +- {vytask}`T4341` `(feature): login: disable user-account prior to deletion and wait until deletion is complete` +- {vytask}`T4336` `(feature): isis: add support for MD5 authentication password on a circuit` + +## 2022-04-06 + +- {vytask}`T4308` `(feature): Op-comm "Show log frr" to view specific protocol logs` + +## 2022-03-29 + +- {vytask}`T3686` `(bug): Bridging OpenVPN tap with no local-address breaks` + +## 2022-03-24 + +- {vytask}`T4294` `(bug): Adding a new openvpn-option does not restart the OpenVPN process` +- {vytask}`T4230` `(bug): OpenVPN server configuration deleted after reboot when using a VRRP virtual-address` + +## 2022-03-21 + +- {vytask}`T4311` `(bug): CVE-2021-4034: local privilege escalation in PolKit` +- {vytask}`T4310` `(bug): CVE-2022-0778: infinite loop in OpenSSL certificate parsing` + +## 2022-03-12 + +- {vytask}`T4296` `(bug): Interface config injected by Cloud-Init may interfere with VyOS native` +- {vytask}`T4002` `(default): firewall group network-group long names restriction incorrect behavior` + +## 2022-03-11 + +- {vytask}`T4297` `(bug): Interface configuration saving fails for ice/iavf based interfaces because they can't change speed/duplex settings` + +## 2022-03-05 + +- {vytask}`T4259` `(bug): The conntrackd daemon can be started wrongly` + +## 2022-02-28 + +- {vytask}`T4273` `(bug): ssh: Upgrade from 1.2.X to 1.3.0 breaks config` +- {vytask}`T4115` `(bug): reboot in <x> not working as expected` + +## 2022-02-24 + +- {vytask}`T4267` `(bug): Error - Missing required "ip key" parameter` + +## 2022-02-23 + +- {vytask}`T4264` `(bug): vxlan: interface is destroyed and rebuild on description change` +- {vytask}`T4263` `(bug): vyos.util.leaf_node_changed() dos not honor valueLess nodes` + +## 2022-02-21 + +- {vytask}`T4120` `(feature): [VXLAN] add ability to set multiple unicast-remotes` + +## 2022-02-20 + +- {vytask}`T4261` `(feature): MACsec: add DHCP client support` +- {vytask}`T4203` `(bug): Reconfigure DHCP client interface causes brief outages` + +## 2022-02-19 + +- {vytask}`T4258` `(bug): [DHCP-SERVER] error parameter on Failover` + +## 2022-02-17 + +- {vytask}`T4241` `(bug): ocserv openconnect looks broken in recent bulds of 1.3 Equuleus` +- {vytask}`T4255` `(bug): Unexpected print of dict bridge on delete` +- {vytask}`T4240` `(bug): Cannot add wlan0 to bridge via configure` +- {vytask}`T4154` `(bug): Error add second gre tunnel with the same source interface` + +## 2022-02-16 + +- {vytask}`T4237` `(bug): Conntrack-sync error - error adding listen-address command` + +## 2022-02-15 + +- {vytask}`T4201` `(bug): Firewall - ICMPv6 matches not working as expected on 1.3.0` +- {vytask}`T3006` `(bug): Accel-PPP & vlan-mon config get invalid VLAN` +- {vytask}`T3494` `(bug): DHCPv6 leases traceback when PD using` + +## 2022-02-13 + +- {vytask}`T4242` `(bug): ethernet speed/duplex can never be switched back to auto/auto` +- {vytask}`T4191` `(bug): Lost access to host after VRF re-creating` + +## 2022-02-11 + +- {vytask}`T3872` `(feature): Add configurable telegraf monitoring service` +- {vytask}`T4234` `(bug): Show firewall partly broken in 1.3.x` + +## 2022-02-10 + +- {vytask}`T4165` `(bug): Custom conntrack rules cannot be deleted` + +## 2022-02-08 + +- {vytask}`T4227` `(bug): Typo in help completion of hello-time option of bridge interface` + +## 2022-02-07 + +- {vytask}`T4233` `(bug): ssh: sync regex for allow/deny usernames to "system login"` +- {vytask}`T4087` `(feature): IPsec IKE-group proposals limit of 10 pieces` + +## 2022-02-05 + +- {vytask}`T4226` `(bug): VRRP transition-script does not work for groups name which contains -(minus) sign` + +## 2022-02-04 + +- {vytask}`T4196` `(bug): DHCP server client-prefix-length parameter results in non-functional leases` + +## 2022-02-03 + +- {vytask}`T3643` `(bug): show vpn ipsec sa doesn't show tunnels in "down" state` + +## 2022-02-01 + +- {vytask}`T4198` `(bug): Error shown on commit` + +## 2022-01-28 + +- {vytask}`T4184` `(bug): NTP allow-clients address doesn't work it allows to use ntp server for all addresses` + +## 2022-01-24 + +- {vytask}`T4204` `(feature): Update Accel-PPP to a newer revision` + +## 2022-01-17 + +- {vytask}`T3164` `(bug): console-server ssh does not work with RADIUS PAM auth` + +## 2022-01-15 + +- {vytask}`T4183` `(feature): IPv6 link-local address not accepted as wireguard peer` +- {vytask}`T4110` `(feature): [IPV6-SSH/DNS} enable IPv6 link local adresses as listen-address %eth0` + +## 2022-01-12 + +- {vytask}`T4168` `(bug): IPsec VPN is impossible to restart when DMVPN is configured` +- {vytask}`T4167` `(bug): DMVPN apply wrong param on the first configuration` +- {vytask}`T4152` `(bug): NHRP shortcut-target holding-time does not work` + +## 2022-01-10 + +- {vytask}`T3299` `(bug): Allow the web proxy service to listen on all IP addresses` +- {vytask}`T3115` `(feature): Add support for firewall on L3 VIF bridge interface` + +## 2022-01-09 + +- {vytask}`T3822` `` (bug): OpenVPN processes do not have permission to read key files generated with `run generate openvpn key` `` +- {vytask}`T4142` `(bug): Input ifbX interfaces not displayed in op-mode` +- {vytask}`T3914` `(bug): VRRP rfc3768-compatibility doesn't work with unicast peers` + +## 2022-01-07 + +- {vytask}`T3924` `(bug): VRRP stops working with VRF` + +## 2022-01-06 + +- {vytask}`T4141` `(bug): Set high-availability vrrp sync-group without members error` + +## 2022-01-03 + +- {vytask}`T4065` `(bug): IPSEC configuration error: connection to unix:///var/run/charon.ctl failed: No such file or directory` +- {vytask}`T4052` `(bug): Validator return traceback on VRRP configuration with the script path not in config dir` +- {vytask}`T4128` `(bug): keepalived: Upgrade package to add VRF support` + +## 2021-12-31 + +- {vytask}`T4081` `(bug): VRRP health-check script stops working when setting up a sync group` + +## 2021-12-29 + +- {vytask}`T2922` `` (bug): The `vpn ipsec logging log-modes` miss the IPSec daemons state check `` +- {vytask}`T2695` `(bug): Flow-accounting bug with subinterfaces` +- {vytask}`T2400` `(default): OpenVPN: dont restart server if no need` +- {vytask}`T4086` `(default): system login banner is not removed on deletion.` + +## 2021-12-28 + +- {vytask}`T3380` `(bug): "show vpn ike sa" does not display IPv6 peers` +- {vytask}`T2933` `(feature): VRRP add option virtual_ipaddress_excluded` + +## 2021-12-27 + +- {vytask}`T2566` `(bug): sstp not able to run tunnels ipv6 only` +- {vytask}`T4093` `(bug): SNMPv3 snmpd.conf generation bug` +- {vytask}`T2764` `(enhancment): Increase maximum number of NAT rules` + +## 2021-12-26 + +- {vytask}`T4104` `(bug): RAID1: "add raid md0 member sda1" does not restore boot sector` + +## 2021-12-25 + +- {vytask}`T4101` `(bug): commit-archive: Use of uninitialized value $source_address in concatenation` +- {vytask}`T4055` `(feature): Add VRF support for HTTP(S) API service` + +## 2021-12-24 + +- {vytask}`T3854` `(bug): Missing op-mode commands for conntrack-sync` + +## 2021-12-23 + +- {vytask}`T4092` `(bug): IKEv2 mobike commit failed with DMVPN nhrp` +- {vytask}`T3354` `(default): Convert strip-private script from Perl to Python` + +## 2021-12-22 + +- {vytask}`T3356` `(feature): Script for remote file transfers` + +## 2021-12-21 + +- {vytask}`T4053` `(bug): VRRP impossible to set scripts out of the /config directory` +- {vytask}`T4013` `(bug): Add pkg cloudwatch for AWS images` +- {vytask}`T3913` `(bug): VRF traffic fails after upgrade from 1.3.0-RC6 to 1.3.0-EPA1/2` + +## 2021-12-20 + +- {vytask}`T4088` `(default): Fix typo in login banner` + +## 2021-12-19 + +- {vytask}`T3912` `(default): Use a more informative default post-login banner` + +## 2021-12-17 + +- {vytask}`T3176` `(bug): Ordering of ports on EdgeCore SAF51015I is mixed up?` +- {vytask}`T4059` `(bug): VRRP sync-group transition script does not persist after reboot` + +## 2021-12-16 + +- {vytask}`T4046` `(feature): Sflow - Add Source address parameter` +- {vytask}`T2615` `(default): Provide an explicit option for server fingerprint in commit archive, and make insecure the default` +- {vytask}`T4076` `(enhancment): Allow setting CORS options in HTTP API` +- {vytask}`T3378` `(bug): commit-archive source-address broken for IPv6 addresses` + +## 2021-12-15 + +- {vytask}`T4077` `(bug): op-mode: bfd: drop "show protocols bfd" in favour of "show bfd"` +- {vytask}`T4073` `(bug): "show protocols bfd peer <>" shows incorrect peer information.` + +## 2021-12-14 + +- {vytask}`T4071` `(feature): Allow HTTP API to bind to unix domain socket` + +## 2021-12-12 + +- {vytask}`T4036` `(bug): VXLAN incorrect raiseError if set multicast network instead of singe address` + +## 2021-12-10 + +- {vytask}`T4068` `(feature): Python: ConfigError should insert line breaks into the error message` + +## 2021-12-09 + +- {vytask}`T4033` `(bug): VRRP - Error security when setting scripts` +- {vytask}`T4064` `(bug): IP address for vif is not removed from the system when deleted in configuration` +- {vytask}`T4063` `(bug): VRRP log error - /usr/libexec/vyos/vyos-vrrp-conntracksync.sh - No such file or directory` +- {vytask}`T4060` `(enhancment): Extend configquery for use before boot configuration is complete` + +## 2021-12-08 + +- {vytask}`T4024` `(bug): Access-lists and prefix-lists disappear when setting ldp hello-ipv4-interval` + +## 2021-12-07 + +- {vytask}`T4041` `(servicerequest): "transition-script" doesn't work on "sync-group"` + +## 2021-12-06 + +- {vytask}`T4012` `(feature): Add VRF support for TFTP` + +## 2021-12-05 + +- {vytask}`T4034` `(bug): "make xcp-ng-iso" still includes vyos-xe-guest-utilities` +- {vytask}`T2076` `(feature): RAID install: sfdisk change-id is deprecated in favor of --part-type` +- {vytask}`T1126` `(bug): Reusing a RAID from a BIOS install in an EFI install causes a failure to boot` + +## 2021-12-04 + +- {vytask}`T4049` `(feature): support command-style output with compare command` +- {vytask}`T4047` `(bug): Wrong regex validation in XML definitions` +- {vytask}`T4045` `(bug): Unable to "format disk <new> like <old>"` + +## 2021-12-02 + +- {vytask}`T4035` `(bug): Geneve interfaces aren't displayed by operational mode commands` + +## 2021-12-01 + +- {vytask}`T3695` `(bug): OpenConnect reports commit success when ocserv fails to start due to SSL cert/key file issues` + +## 2021-11-30 + +- {vytask}`T3725` `(feature): show configuration in json format` + +## 2021-11-29 + +- {vytask}`T2661` `(bug): SSTP wrong certificates check` +- {vytask}`T3946` `(enhancment): Automatically resize the root partition if the drive has extra space` + +## 2021-11-28 + +- {vytask}`T3999` `(bug): show lldp neighbor Traceback error` + +## 2021-11-26 + +- {vytask}`T4019` `(bug): Smoketests for SSTP and openconnect fails` + +## 2021-11-25 + +- {vytask}`T4005` `(feature): Feature Request: IPsec IKEv1 + IKEv2 for one peer` + +## 2021-11-24 + +- {vytask}`T4015` `(feature): Update Accel-PPP to a newer revision` +- {vytask}`T1083` `(feature): Implement persistent/random address and port mapping options for NAT rules` + +## 2021-11-23 + +- {vytask}`T3990` `(bug): WATCHFRR: crashlog and per-thread log buffering unavailable (due to files left behind in /var/tmp/frr/ after reboot)` + +## 2021-11-20 + +- {vytask}`T4004` `(bug): IPsec ike-group parameters are not saved correctly (after reboot)` + +## 2021-11-19 + +- {vytask}`T4003` `(bug): API for "show interfaces ethernet" does not include the interface description` +- {vytask}`T4011` `(bug): ethernet: deleting interface should place interface in admin down state` + +## 2021-11-18 + +- {vytask}`T3995` `(feature): OpenVPN: do not stop/start service on configuration change` +- {vytask}`T4008` `(feature): dhcp: change client retry interval form 300 -> 60 seconds` +- {vytask}`T3795` `(bug): WWAN: issues with non connected interface / no signal` + +## 2021-11-17 + +- {vytask}`T3350` `(bug): OpenVPN config file generation broken` +- {vytask}`T3996` `(bug): SNMP service error in log` + +## 2021-11-15 + +- {vytask}`T3934` `(bug): Openconnect VPN broken: ocserv-worker general protection fault on client connect` +- {vytask}`T3724` `(feature): Allow setting host-name in l2tp section of accel-ppp` + +## 2021-11-14 + +- {vytask}`T3974` `(bug): route-map commit fails if interface does not exist` + +## 2021-11-11 + +- {vytask}`T1349` `(bug): L2TP remote-access vpn terminated and not showing as connected` +- {vytask}`T1058` `(default): hw-id is ignored when naming interfaces` +- {vytask}`T914` `(feature): Extend list_interfaces.py to support multiple interface types` +- {vytask}`T688` `(enhancment): Move component versions used for config migration purposes into vyos-1x` + +## 2021-11-10 + +- {vytask}`T3982` `(bug): DHCP server commit fails if static-mapping contains + or .` + +## 2021-11-09 + +- {vytask}`T3962` `(bug): Image cannot be built without open-vm-tools` +- {vytask}`T2088` `(bug): Increased boot time from 1.2.4 -> 1.3 rolling by 100%` +- {vytask}`T2136` `(bug): XML command definition convertor doesn't disallow tag nodes with multi flag on` + +## 2021-11-07 + +- {vytask}`T2874` `(feature): Add MTU and TCP-MSS discovery tool` +- {vytask}`T3626` `(bug): Configuring and disabling DHCP Server` + +## 2021-11-06 + +- {vytask}`T3971` `(feature): Ability to build ISO images for XCP-NG hypervisor` +- {vytask}`T3514` `(bug): NIC flap at any interface change` + +## 2021-11-05 + +- {vytask}`T3972` `(bug): Removing vif-c interface raises KeyError` + +## 2021-11-04 + +- {vytask}`T3964` `(bug): SSTP: local-user static-ip CLI node accepts invalid IPv4 addresses` + +## 2021-11-03 + +- {vytask}`T3610` `(bug): DHCP-Server creation for not primary IP address fails` + +## 2021-11-01 + +- {vytask}`T3846` `(bug): dmvpn configuration not reapllied after "restart vpn"` +- {vytask}`T3956` `(bug): GRE tunnel - unable to move from source-interface to source-address, commit error` + +## 2021-10-31 + +- {vytask}`T3945` `(feature): Add route-map for bgp aggregate-address` +- {vytask}`T3341` `(bug): Wrong behavior of the "reset vpn ipsec-peer XXX tunnel XXX" command` +- {vytask}`T3954` `(bug): FTDI cable makes VyOS sagitta latest hang, /dev/serial unpopulated, config system error` +- {vytask}`T3943` `(bug): "netflow source-ip" prevents image upgrades if IP address does not exist locally` + +## 2021-10-29 + +- {vytask}`T3942` `(feature): Generate IPSec debug archive from op-mode` + +## 2021-10-28 + +- {vytask}`T3941` `(bug): "show vpn ipsec sa" shows established time of parent SA not child SA's` + +## 2021-10-27 + +- {vytask}`T3944` `(bug): VRRP fails over when adding new group to master` + +## 2021-10-25 + +- {vytask}`T3935` `(bug): Update from rc5 to EPA2 failed` + +## 2021-10-22 + +- {vytask}`T3188` `(bug): Tunnel local-ip to dhcp-interface Change Fails to Update` + +## 2021-10-21 + +- {vytask}`T3920` `(bug): dhclient exit hook script 01-vyos-cleanup causes too many arguments error` +- {vytask}`T3926` `(bug): strip-private does not sanitize "cisco-authentication" from NHRP configuration` +- {vytask}`T3925` `(feature): Tunnel: dhcp-interface not implemented - use source-interface instead` +- {vytask}`T3927` `(feature): Kernel: Enable kernel support for HW offload of the TLS protocol` + +## 2021-10-20 + +- {vytask}`T3922` `(bug): NHRP: delete fails` +- {vytask}`T3918` `(bug): DHCPv6 prefix delegation incorrect verify error` +- {vytask}`T3921` `(bug): tunnel: KeyError when using dhcp-interface` + +## 2021-10-19 + +- {vytask}`T3396` `(bug): syslog can't be configured with an ipv6 literal destination in 1.2.x` +- {vytask}`T690` `(feature): Allow OpenVPN servers to push routes with custom metric values` + +## 2021-10-17 + +- {vytask}`T3786` `(bug): GRE tunnel source address 0.0.0.0 error` +- {vytask}`T3425` `(bug): Scripts from the /config/scripts/ folder do not run on live system` +- {vytask}`T3217` `(default): Save FRR configuration on each commit` +- {vytask}`T3076` `(bug): Router reboot adds unwanted 'conntrack-sync mcast-group '225.0.0.50'' line to configuration` +- {vytask}`T2800` `(bug): Pseudo-Ethernet: source-interface must not be member of a bridge` +- {vytask}`T3422` `(bug): Dynamic DNS doesn't allow zone field with cloudflare protocol` +- {vytask}`T3381` `(bug): Change GRE tunnel failed` +- {vytask}`T3254` `(bug): Dynamic DNS status shows incorrect last update time` +- {vytask}`T3253` `(bug): rpki: multiple peers cannot be configured` +- {vytask}`T3219` `(default): Typo in openvpn server client config for IPv6 iroute` +- {vytask}`T2100` `(feature): BGP route adverisement wih checks rib` +- {vytask}`T1663` `(enhancment): T1656 equuleus: buster: arm64/aarch64: ipaddrcheck does not complete testing` +- {vytask}`T1243` `(bug): BGP local-as accept wrong values` +- {vytask}`T770` `(bug): Bonded interfaces get updated with incorrect hw-id in config.` +- {vytask}`T697` `(bug): Clean up and sanitize package dependencies` +- {vytask}`T3837` `(default): OpenConnect: Fix typo in help property` +- {vytask}`T1440` `(bug): Creating two DHCPv6 shared-network-names with the same subnet is allowed, causes dhcpd to fail to start.` +- {vytask}`T578` `(feature): Support Linux Container` + +## 2021-10-16 + +- {vytask}`T3879` `(bug): GPG key verification fails when upgrading from a 1.3 beta version` +- {vytask}`T3851` `(bug): Missing ospf and rip options for bridge vifs` + +## 2021-10-13 + +- {vytask}`T3904` `(bug): NTP pool associations silently fail` +- {vytask}`T3277` `(feature): DNS Forwarding - reverse zones` + +## 2021-10-11 + +- {vytask}`T2607` `(feature): Support for pppoe-server radius mode auth and config radius accouting port` + +## 2021-10-10 + +- {vytask}`T3750` `(bug): pdns-recursor 4.4 issue with dont-query and private DNS servers` +- {vytask}`T3885` `(default): dhcpv6-pd: randomly generated DUID is not persisted` +- {vytask}`T3899` `(enhancment): Add support for hd44780 LCD displays` + +## 2021-10-09 + +- {vytask}`T3894` `` (bug): Tunnel Commit Failed if system does not have `eth0` `` + +## 2021-10-08 + +- {vytask}`T3893` `(bug): MGRE Tunnel commit crash If sit tunnel available` + +## 2021-10-04 + +- {vytask}`T3888` `(bug): Incorrect warning when poweroff command executed from configure mode.` +- {vytask}`T3890` `(feature): dhcp(v6): provide op-mode commands to retrieve both server and client logfiles` +- {vytask}`T3889` `(feature): Migrate to journalctl when reading daemon logs` + +## 2021-10-03 + +- {vytask}`T3880` `(bug): EFI boot shows error on display` + +## 2021-10-02 + +- {vytask}`T3882` `(feature): Upgrade PowerDNs recursor to 4.5 series` +- {vytask}`T3883` `(bug): VRF - Delette vrf config on interface` + +## 2021-10-01 + +- {vytask}`T3877` `(bug): VRRP always enabled rfc3768-compatibility even when not specified` + +## 2021-09-30 + +- {vytask}`T3874` `(bug): D-Link Ethernet Interface not working.` + +## 2021-09-27 + +- {vytask}`T3858` `(bug): Deleting OSPFv3 process yields: Unknown command: no router-id` + +## 2021-09-26 + +- {vytask}`T3860` `(bug): Error on pppoe, tunnel and wireguard interfaces for IPv6 EUI64 addresses` +- {vytask}`T3857` `(feature): reboot: send wall message to all users for information` +- {vytask}`T3867` `(bug): vxlan: multicast group address is not validated` +- {vytask}`T3859` `(bug): Add "log-adjacency-changes" to ospfv3 process` + +## 2021-09-23 + +- {vytask}`T3850` `(bug): Dots are no longer allowed in SSH public key names` + +## 2021-09-21 + +- {vytask}`T2602` `(bug): pptp/sstp/l2tp add possibility enable or disable CCP` + +## 2021-09-19 + +- {vytask}`T3841` `(feature): dhcp-server: add ping-check option to CLI` +- {vytask}`T2738` `(bug): Modifying configuration in the "interfaces" section from VRRP transition scripts causes configuration lockup and high CPU utilization` +- {vytask}`T3842` `(feature): Backport DHCP server improvements from VyOS 1.4 sagitta to 1.3 equuleus` +- {vytask}`T3840` `(feature): dns forwarding: Cache size should allow values > 10k` +- {vytask}`T3672` `(bug): DHCP-FO with multiple subnets results in invalid/non-functioning dhcpd.conf configuration file output` + +## 2021-09-11 + +- {vytask}`T3402` `(feature): Add VyOS programming library for operational level commands` + +## 2021-09-10 + +- {vytask}`T3802` `(bug): Commit fails if ethernet interface doesn't support flow control` +- {vytask}`T3819` `(bug): Upgrade Salt Stack 3002.3 -> 3003 release train` +- {vytask}`T3421` `(bug): MTR/Traceroute broken in 1.3-beta` +- {vytask}`T3820` `(feature): PowerDNS recursor - update from 4.3 -> 4.4 to sync with current` +- {vytask}`T1770` `(bug): webproxy breaks commit and http access on routed client` +- {vytask}`T915` `(feature): MPLS Support` + +## 2021-09-09 + +- {vytask}`T3816` `(bug): Error after entering outbound-interface command in NAT` +- {vytask}`T3814` `(bug): wireguard: commit error showing incorrect peer name from the configured name` +- {vytask}`T3805` `(bug): OpenVPN insufficient privileges for rtnetlink when closing TUN/TAP interface` + +## 2021-09-07 + +- {vytask}`T2322` `(bug): CLI [op-mode] bugs. Root task` +- {vytask}`T1894` `(bug): FRR config not loaded after daemons segfault or restart` +- {vytask}`T3807` `(bug): Op Command "show interfaces wireguard" does not show the output` +- {vytask}`T3808` `(default): ipsec is mistakenly restarted after delete` + +## 2021-09-06 + +- {vytask}`T3806` `(bug): Don't set link local ipv6 address if MTU less then 1280` +- {vytask}`T3803` `(default): Add source-address option to the ping CLI` +- {vytask}`T3431` `(bug): Show version all bug` +- {vytask}`T3362` `(bug): 1.3 - RC1 ifb redirect failing to commit` +- {vytask}`T3291` `(bug): Fault on setting offload RPS with single-core CPU` +- {vytask}`T2920` `(bug): Commit crash when adding the second mGRE tunnel with the same key` +- {vytask}`T2895` `(bug): VPN IPsec "leftsubnet" declared 2 times` +- {vytask}`T2019` `(bug): LLDP wrong config generation for interface 'all'` + +## 2021-09-05 + +- {vytask}`T3804` `(feature): cli: Migrate and merge "system name-servers-dhcp" into "system name-server"` + +## 2021-09-04 + +- {vytask}`T3697` `(bug): Impossible to delete IPsec completely` +- {vytask}`T3619` `(bug): Performance Degradation 1.2 --> 1.3 | High ksoftirqd CPU usage` +- {vytask}`T1785` `(bug): Deleting partitions on disks (Raid1) with default value 'no'` + +## 2021-09-03 + +- {vytask}`T3788` `(bug): Keys are not allowed with ipip and sit tunnels` +- {vytask}`T3683` `(bug): VXLAN not accept ipv6 and source-interface options and mtu bug` +- {vytask}`T3634` `(feature): Add op command option for ping for do not fragment bit to be set` + +## 2021-09-02 + +- {vytask}`T3792` `(bug): login: A hypen present in a username from "system login user" is replaced by an underscore` +- {vytask}`T3790` `(bug): Does not possible to configure PPTP static ip-address to users` + +## 2021-09-01 + +- {vytask}`T2434` `(bug): Duplicate Address Detection Breaks Interfaces` + +## 2021-08-31 + +- {vytask}`T3789` `(feature): Add custom validator for base64 encoded CLI data` +- {vytask}`T3782` `(default): Ingress Shaping with IFB No Longer Functional with 1.3` + +## 2021-08-30 + +- {vytask}`T3777` `(bug): adding IPv6 EUI64 address fails commit in 1.3.0-rc6` +- {vytask}`T3768` `(default): Remove early syntaxVersion implementation` +- {vytask}`T2558` `` (feature): Add some CPU information to `show version` + fix broken hypervisor detection `` +- {vytask}`T2430` `(default): cannot delete specific route static next-hop` +- {vytask}`T1350` `(bug): VRRP transition script will be executed once only` +- {vytask}`T2941` `(default): Using a non-ASCII character in the description field causes UnicodeDecodeError in configsource.py` +- {vytask}`T3787` `(bug): Remove deprecated UDP fragmentation offloading option` +- {vytask}`T3677` `(feature): "sipcalc" not included in 1.3` + +## 2021-08-29 + +- {vytask}`T3708` `(bug): isisd and gre-bridge commit error` +- {vytask}`T3783` `(bug): "set protocols isis spf-delay-ietf" is not working` +- {vytask}`T2750` `(default): Use m4 as a template processor` + +## 2021-08-27 + +- {vytask}`T3182` `(bug): Main blocker Task for FRR 7.4/7.5 series update` +- {vytask}`T2108` `(default): Use minisign/signify instead of GPG for release signing` + +## 2021-08-26 + +- {vytask}`T3781` `(bug): Revert the NAT implementation in 1.3 back to iptables` +- {vytask}`T3776` `(default): Rename FRR daemon restart op-mode commands` +- {vytask}`T3779` `(feature): Backport all 1.4 IS-IS features and configuration to 1.3 except VRF` + +## 2021-08-25 + +- {vytask}`T3773` `(bug): Delete the "show system integrity" command (to prepare for a re-implementation)` +- {vytask}`T1514` `(default): Add ability to restart frr processes` + +## 2021-08-24 + +- {vytask}`T3772` `(bug): VRRP virtual interfaces are not shown in show interfaces` + +## 2021-08-23 + +- {vytask}`T2555` `(bug): XML op-mode generation scripts silently discard XML nodes` + +## 2021-08-21 + +- {vytask}`T3682` `(bug): Remove running dhclient from ether-resume.py` + +## 2021-08-20 + +- {vytask}`T1950` `(default): Store VyOS configuration syntax version data in JSON file` + +## 2021-08-19 + +- {vytask}`T2759` `(bug): validate-value prints error messages from validators that fail even if overall validation succeeds` +- {vytask}`T3234` `(bug): multi_to_list fails in certain cases, with root cause an element redundancy in XML interface-definitions` +- {vytask}`T3732` `(feature): override-default helper should support adding defaultValues to default less nodes` +- {vytask}`T1962` `(default): Add syntax version to schema` + +## 2021-08-17 + +- {vytask}`T2525` `(bug): OSPFv3 missing route map, not establishing` +- {vytask}`T508` `(bug): ISC DHCP incorrect UDP checksum generation` +- {vytask}`T1643` `(bug): Deleting all firewall zones failed and locked out box` +- {vytask}`T1550` `(bug): Add support for Large BGP Community show commands` + +## 2021-08-16 + +- {vytask}`T3738` `(default): openvpn fails if server and authentication are configured` +- {vytask}`T1594` `(bug): l2tpv3 error on IPv6 local-ip` + +## 2021-08-15 + +- {vytask}`T3756` `(default): VyOS generates invalid QR code for wireguard clients` + +## 2021-08-14 + +- {vytask}`T3745` `(feature): op-mode IPSec show vpn ipse sa sorting` +- {vytask}`T521` `(bug): Network services may fail if vyatta-router.service startup takes longer than a few seconds` + +## 2021-08-13 + +- {vytask}`T3740` `(bug): HTTPs API breaks when the address is IPv6` + +## 2021-08-12 + +- {vytask}`T3731` `(bug): verify_accel_ppp_base_service return wrong config error for SSP` +- {vytask}`T3405` `(feature): PPPoE server unit-cache` +- {vytask}`T2432` `(default): dhcpd: Can't create new lease file: Permission denied` +- {vytask}`T3746` `(feature): Inform users logging into the system about a pending reboot` +- {vytask}`T3744` `(default): Dns forwarding statistics formatting missing a new line` + +## 2021-08-10 + +- {vytask}`T3730` `(bug): op-mode conntrack-sync miss some functions` + +## 2021-08-09 + +- {vytask}`T1501` `(bug): VPN Commit Errors` + +## 2021-08-08 + +- {vytask}`T2027` `(bug): get_config_dict is failing when the configuration section is empty/missing` +- {vytask}`T169` `(feature): Image install should put correct serial console device in created GRUB menu entry` + +## 2021-08-07 + +- {vytask}`T548` `(feature): BGP IPv6 multipath support` + +## 2021-08-06 + +- {vytask}`T1153` `(bug): VyOS 1.2.0RC10, RAID-1, fresh install, unable to save config` + +## 2021-08-05 + +- {vytask}`T696` `(feature): Rewrite conntrack sync to XML` + +## 2021-08-04 + +- {vytask}`T3704` `(feature): Add ability to interact with Areca RAID adapers` +- {vytask}`T320` `(default): OSPF does not redistribute connected routes associated with virtual tunnel interfaces` + +## 2021-08-02 + +- {vytask}`T2623` `(bug): Creating sit tunnel fails with “Can not set “local” for tunnel sit tun1 at tunnel creation”` +- {vytask}`T2161` `(default): snmpd cannot start if ipv6 disabled` +- {vytask}`T3601` `(default): Error in ssh keys for vmware cloud-init if ssh keys is left empty.` + +## 2021-08-01 + +- {vytask}`T3707` `(bug): Ping incorrect ip host checks` + +## 2021-07-31 + +- {vytask}`T3716` `(feature): Linux kernel parameters ignore_routes_with_link_down- ignore disconnected routing connections` +- {vytask}`T1626` `(bug): BGP exchanges prefixes without specified address-family` + +## 2021-07-30 + +- {vytask}`T1176` `(default): FRR - BGP replicating routes` +- {vytask}`T1123` `(bug): Inconsistency in community-list naming validation` + +## 2021-07-29 + +- {vytask}`T2931` `(bug): Unicode decode error causes vyos.configd service to restart` +- {vytask}`T2727` `(bug): Add a dotted decimal value validator` +- {vytask}`T2328` `(default): dhcpv6 server not starting (disable check reversed?)` +- {vytask}`T1758` `(default): Switch vyos.config to libvyosconfig` +- {vytask}`T954` `(bug): Using the 10.255.255.0/24 subnet on other interfaces breaks L2TP/IPSec` + +## 2021-07-23 + +- {vytask}`T3699` `(bug): login: verify selected "system login user" name is not already used by the base system.` + +## 2021-07-21 + +- {vytask}`T3689` `(bug): static ipv6 route doesn't deleted in some cases` +- {vytask}`T3685` `(feature): IPv6 PBR doesn't allow setting of an egress interface` + +## 2021-07-20 + +- {vytask}`T3691` `(bug): GRETAP: key is not applied when interface is created` + +## 2021-07-13 + +- {vytask}`T3679` `(default): Point the unexpected exception message link to the new rolling release location` + +## 2021-07-11 + +- {vytask}`T3665` `(bug): Missing VRF support for VxLAN but already documented` + +## 2021-07-06 + +- {vytask}`T3660` `(feature): Conntrack-Sync configuration command to specify destination udp port for peer` + +## 2021-07-01 + +- {vytask}`T3658` `(feature): Add support for dhcpdv6 fixed-prefix6` + +## 2021-06-29 + +- {vytask}`T3593` `(bug): PPPoE server called-sid format does not work` + +## 2021-06-25 + +- {vytask}`T3650` `(bug): OpenVPN: Upgrade package to 2.5.1 before releasing VyOS 1.3.0` +- {vytask}`T3649` `(feature): Add bonding additional hash-policy` + +## 2021-06-24 + +- {vytask}`T2722` `(bug): get_config_dict() and key_mangling=('-', '_') will alter CLI data for tagNodes` + +## 2021-06-22 + +- {vytask}`T3629` `(bug): IPoE server shifting address in the range` + +## 2021-06-20 + +- {vytask}`T3637` `(bug): vrf: bind-to-all didn't work properly` + +## 2021-06-19 + +- {vytask}`T3633` `(feature): Add LRO offload for interface ethernet` + +## 2021-06-17 + +- {vytask}`T3631` `(feature): route-map: migrate "set extcommunity-rt" and "set extcommunity-soo" to "set extcommunity rt|soo" to match FRR syntax` + +## 2021-06-16 + +- {vytask}`T2425` `(feature): Rewrite all policy zebra filters to XML/Python style` +- {vytask}`T3630` `(feature): op-mode: add "show version kernel" command` + +## 2021-06-13 + +- {vytask}`T3620` `(feature): Rename WWAN interface from wirelessmodem to wwan to use QMI interface` +- {vytask}`T3622` `(feature): WWAN: add support for APN authentication` +- {vytask}`T3621` `(bug): PPPoE interface does not validate if password is supplied when username is set` + +## 2021-06-10 + +- {vytask}`T3250` `(bug): PPPoE server: wrong local usernames` +- {vytask}`T3138` `(bug): ddclient improperly updated when apply rfc2136 config` +- {vytask}`T2645` `(default): Editing route-map action requires adding a new rule` + +## 2021-06-09 + +- {vytask}`T3602` `(bug): Renaming BGP Peer Groups Leaves Router Broken` +- {vytask}`T2916` `(bug): A state of VTI interface in a configuration does not being processing properly` + +## 2021-06-08 + +- {vytask}`T3605` `(default): Allow to set prefer-global for ipv6-next-hop` +- {vytask}`T3607` `(feature): [route-map] set ipv6 next-hop prefer-global` + +## 2021-06-07 + +- {vytask}`T3581` `` (bug): Incomplete command `show ipv6 ospfv3 linkstate` `` +- {vytask}`T3516` `(bug): FRR 7.5 adds a second route when you attempt to change a static route distance instead of overwriting the old route` +- {vytask}`T3461` `(bug): OpenConnect Server redundancy check` +- {vytask}`T3455` `(bug): system users can not be added in "edit"` + +## 2021-06-04 + +- {vytask}`T3592` `(feature): Set default TTL 64 for tunnels` + +## 2021-06-01 + +- {vytask}`T406` `(bug): VPN configuration error: IPv6 over IPv4 IPsec is not supported when using IPv6 ONLY tunnel.` + +## 2021-05-30 + +- {vytask}`T1866` `(bug): Commit archive over SFTP doesn't work with non-standard ports` +- {vytask}`T3589` `(feature): op-mode: support clearing out logfiles from CLI` +- {vytask}`T3508` `(bug): Check if there's enough drive space for an upgrade before downloading an image` +- {vytask}`T1506` `(enhancment): commit-archive scp/sftp public key authentication` + +## 2021-05-29 + +- {vytask}`T3135` `(bug): BFD configurations fail to be applied` +- {vytask}`T3103` `(default): Rewrite parts of vyos\frr.py for readability, logging and to fix mulitiline regex "bugs"` +- {vytask}`T2739` `(default): vyos-utils is not compiled with a Jenkins pipeline.` +- {vytask}`T2451` `(bug): Cannot use !tcp or !tcp_udp while adding firewall rule` +- {vytask}`T2436` `(default): equuleus: Testing: vyos-1x: syntax checking Python scripts in PR` +- {vytask}`T2184` `(bug): OpenVPN op_mode tools broken` +- {vytask}`T1944` `(bug): FRR: Invalid route in BGP causes update storm, memory leak, and failure of Zebra` + +## 2021-05-28 + +- {vytask}`T1579` `(feature): Rewrite all interface types in new XML/Python style` + +## 2021-05-27 + +- {vytask}`T2629` `(bug): VXLAN interfaces don't actually allow you to configure most settings` +- {vytask}`T2617` `(feature): Rewrite vyatta-op-quagga "show" to XML` +- {vytask}`T2512` `(feature): vyatta-op-quagga [show ip] to XML format` +- {vytask}`T1905` `(default): Update to Keepalived 2.0.19` +- {vytask}`T2669` `(bug): DHCP-server overlapping ranges.` + +## 2021-05-26 + +- {vytask}`T3558` `(default): autocomplete options for dhcp-interface is not showing for the static route command` +- {vytask}`T3540` `(bug): Keepalived memory utilisation issue when constantly getting its state in JSON format` +- {vytask}`T2807` `(feature): IPv6 Link-Local Address - Automatically generation/configuration on GRE Interfaces` + +## 2021-05-24 + +- {vytask}`T3575` `(bug): pseudo-ethernet: must check source-interface MTU` +- {vytask}`T3571` `(bug): Broken Show Tab Complete` +- {vytask}`T3576` `(bug): ISIS does not support IPV6` + +## 2021-05-23 + +- {vytask}`T3570` `(default): Prevent setting of a larger MTU on child interfaces` +- {vytask}`T3572` `(feature): Basic Drive Diagnostic Tools` + +## 2021-05-20 + +- {vytask}`T3554` `(feature): Add area-type stub for ospfv3` + +## 2021-05-19 + +- {vytask}`T3562` `(feature): Update Accel-PPP to a newer revision` +- {vytask}`T3559` `(feature): Add restart op-command for OpenConnect Server` + +## 2021-05-18 + +- {vytask}`T3525` `(default): VMWare resume script syntax errors` +- {vytask}`T2462` `(default): LLDP op-mode exception: IndexError: list index out of range` + +## 2021-05-15 + +- {vytask}`T3549` `(bug): DHCPv6 "service dhcpv6-server global-parameters name-server" is not correctly exported to dhcpdv6.conf when multiple name-server entries are present` +- {vytask}`T3532` `(bug): Not possible to change ethertype after interface creation` +- {vytask}`T3550` `(bug): Router-advert completion typo` +- {vytask}`T3547` `(feature): conntrackd: remove deprecated config options` +- {vytask}`T3535` `(feature): Rewrite vyatta-conntrack-sync in new XML and Python flavor` +- {vytask}`T2049` `(feature): Update strongSwan cipher suites list for IPSec settings` + +## 2021-05-14 + +- {vytask}`T3346` `(bug): nat 4-to-5 migration script fails when a 'source' or 'destination' node exists but there are no rules` +- {vytask}`T3248` `(default): Deal with VRRP mode-force command that exists in 1.2 but not in 1.3` +- {vytask}`T3426` `(default): add support for script arguments to vyos-configd` + +## 2021-05-13 + +- {vytask}`T3544` `(feature): DHCP server should validate configuration before applying it` +- {vytask}`T3543` `(feature): Support for setting lacp_rate on LACP bonded interfaces` + +## 2021-05-12 + +- {vytask}`T3302` `(default): Make vyos-configd relay stdout from scripts to the user's console` + +## 2021-05-11 + +- {vytask}`T3526` `(bug): Smoketest policy fail in CI` + +## 2021-05-10 + +- {vytask}`T3528` `(bug): Frr 7.5.1 uses 'seq' for community-lists` + +## 2021-05-08 + +- {vytask}`T3517` `(bug): FRR 7.5 bfd behavior for 1.3` + +## 2021-05-07 + +- {vytask}`T1171` `(bug): 1.2.0 epa2 - IPsec VPN initiation` + +## 2021-05-06 + +- {vytask}`T3519` `(bug): Cannot add / assign L2TPv3 to vrf` + +## 2021-05-01 + +- {vytask}`T3379` `(feature): Add global-parameters name-server for dhcpv6-server` +- {vytask}`T3491` `(default): Change Kernel HZ to 1000` + +## 2021-04-30 + +- {vytask}`T3170` `(default): Add a sanity check for empty node.def files` + +## 2021-04-29 + +- {vytask}`T3502` `(bug): "system ip multipath layer4-hashing" doesn't work` +- {vytask}`T3029` `(bug): Generated NGINX configuration is wrong for the redirection (http -> https)` +- {vytask}`T3156` `(feature): Add op and additional conf commands for ISIS` +- {vytask}`T2012` `(feature): Global PBR` +- {vytask}`T1314` `(feature): Allow BGP on unnumbered interfaces` + +## 2021-04-27 + +- {vytask}`T2946` `(bug): Calling 'stty_size' causes show interfaces API to fail` + +## 2021-04-25 + +- {vytask}`T3468` `(bug): Tunnel interfaces aren't suggested as being available for bridging (regression)` +- {vytask}`T1802` `(feature): Wireguard QR code in cli for mobile devices` + +## 2021-04-23 + +- {vytask}`T3290` `(bug): Disabling GRE conntrack module fails` + +## 2021-04-18 + +- {vytask}`T3481` `(default): Exclude tag node values from key mangling` +- {vytask}`T3475` `(bug): XML dictionary cache unable to process syntaxVersion elements` + +## 2021-04-15 + +- {vytask}`T3386` `(bug): PPPoE-server don't start with local authentication` + +## 2021-04-14 + +- {vytask}`T3055` `(bug): op-mode incorrect naming for ipsec policy-based tunnels` + +## 2021-04-12 + +- {vytask}`T3454` `(enhancment): dhclient reject option` + +## 2021-04-05 + +- {vytask}`T1612` `(default): dhcp-server time-offset fails to validate` +- {vytask}`T3438` `(bug): VRF: removing vif which belongs to a vrf, will delete the entire vrf from the operating system` +- {vytask}`T3418` `(bug): BGP: system wide known interface can not be used as neighbor` + +## 2021-04-04 + +- {vytask}`T3457` `(feature): Output the "monitor log" command in a colorful way` + +## 2021-03-31 + +- {vytask}`T3445` `(bug): vyos-1x build include not all nodes` + +## 2021-03-25 + +- {vytask}`T2639` `(feature): sort output of show vpn ipsec sa` + +## 2021-03-22 + +- {vytask}`T3284` `(bug): merge/load fail silently if unable to resolve host` + +## 2021-03-21 + +- {vytask}`T3416` `(bug): NTP: when running inside a VRF op-mode commands do not work` + +## 2021-03-20 + +- {vytask}`T3392` `(bug): vrrp over dhcp default route bug (unexpected vrf)` +- {vytask}`T3373` `(feature): Upgrade to SaltStack version 3002.5` +- {vytask}`T3329` `(default): "system conntrack ignore" rules can no longer be created due to an iptables syntax change` +- {vytask}`T3300` `(feature): Add DHCP default route distance` +- {vytask}`T3306` `(feature): Extend set route-map aggregator as to 4 Bytes` + +## 2021-03-18 + +- {vytask}`T3411` `(default): Extend the redirect_stdout context manager in vyos-configd to redirect stdout from subprocesses` +- {vytask}`T3271` `(bug): qemu-kvm grub issue` + +## 2021-03-17 + +- {vytask}`T3413` `(bug): Configuring invalid IPv6 EUI64 address results in "OSError: illegal IP address string passed to inet_pton"` + +## 2021-03-14 + +- {vytask}`T2271` `(feature): OSPF: add per VRF instance support` +- {vytask}`T175` `(feature): Add source route option to VTI interfaces` + +## 2021-03-13 + +- {vytask}`T3406` `(bug): tunnel: interface no longer supports specifying encaplimit none - or migrator is missing` +- {vytask}`T3407` `(bug): console-server: do not allow to spawn a console-server session on serial port used by "system console"` + +## 2021-03-11 + +- {vytask}`T3399` `(bug): RPKI: dashes in hostnames are replaced with underscores when rendering the FRR config` +- {vytask}`T3305` `(bug): Ingress qdisc does not work anymore in 1.3-rolling-202101 snapshot` +- {vytask}`T2927` `(bug): isc-dhcpd release and expiry events never execute` +- {vytask}`T899` `(bug): Tunnels cannot be moved from one bridge to another` +- {vytask}`T786` `(feature): new style xml and conf-mode scripts: posibillity to add tagNode value as parameter to conf-script` + +## 2021-03-09 + +- {vytask}`T3382` `(bug): Error creating Console Server` + +## 2021-03-08 + +- {vytask}`T3387` `(bug): Command "Monitor vpn ipsec" is not working` + +## 2021-03-07 + +- {vytask}`T3319` `(bug): VXLAN uses ttl 1 (auto) by default` +- {vytask}`T3391` `(feature): Add CLI support for specifying maximum-paths per address family ipv4 unicast and ipv6 unicast` +- {vytask}`T3211` `(feature): ability to redistribute ISIS into other routing protocols` + +## 2021-03-05 + +- {vytask}`T2659` `(feature): Add fastnetmon (DDoS detection) support` + +## 2021-03-04 + +- {vytask}`T2861` `(bug): route-map "set community additive" not working correctly` + +## 2021-03-03 + +- {vytask}`T2966` `(feature): tunnel: add new encapsulation types ip6tnl and ip6gretap` + +## 2021-03-01 + +- {vytask}`T3342` `(bug): On xen-netback interfaces must set "scattergather" offload before MTU>1500` + +## 2021-02-28 + +- {vytask}`T3370` `(bug): dhcp: Invalid domain name "private"` +- {vytask}`T3369` `(feature): VXLAN: add IPv6 underlay support` + +## 2021-02-27 + +- {vytask}`T2291` `(bug): Bad hostnames in /etc/hosts with static-mapping in dhcp server config` +- {vytask}`T3364` `(feature): tunnel: cleanup/rename CLI nodes` +- {vytask}`T3368` `(feature): macsec: add support for gcm-aes-256 cipher` +- {vytask}`T3366` `(bug): tunnel: can not change local / remote ip address for gre-bridge tunnel` +- {vytask}`T3173` `(feature): Need 'nopmtudisc' option for tunnel interface` + +## 2021-02-26 + +- {vytask}`T3357` `(default): HTTP-API redirect from http correct https port` + +## 2021-02-24 + +- {vytask}`T3303` `(feature): Change welcome message on boot` + +## 2021-02-21 + +- {vytask}`T3163` `(feature): ethernet ring-buffer can be set with an invalid value` + +## 2021-02-19 + +- {vytask}`T3326` `(bug): OSPFv3: Cannot add L2TPv3 interface` + +## 2021-02-18 + +- {vytask}`T3259` `(default): many dnat rules makes the vyos http api crash, even showConfig op timeouts` + +## 2021-02-17 + +- {vytask}`T3047` `(bug): OSPF : virtual-link and passive-interface default parameters does not work together` +- {vytask}`T3312` `(feature): SolarFlare NICs support` + +## 2021-02-16 + +- {vytask}`T3318` `(feature): Update Linux Kernel to v5.4.208 / 5.10.142` + +## 2021-02-14 + +- {vytask}`T2152` `(bug): ddclient has bug which prevents use_web from being used` +- {vytask}`T3308` `(feature): BGP: add gracefull shutdown support` + +## 2021-02-13 + +- {vytask}`T3028` `(feature): Create a default user when metadata is not available (for Cloud-init builds)` +- {vytask}`T2867` `(feature): Cleanup DataSourceOVF.py in the Cloud-init` +- {vytask}`T2726` `(feature): Allow to use all supported SSH key types in Cloud-init` +- {vytask}`T2403` `(feature): Full support for networking config in Cloud-init` +- {vytask}`T2387` `(feature): Create XML scheme for [conf_mode] BGP` +- {vytask}`T2174` `(feature): Rewrite protocol BGP to new XML/Python style` +- {vytask}`T1987` `(bug): A default route can be deleted by dhclient-script in some cases` +- {vytask}`T723` `(feature): Add support for first boot or installation time saved config modification` +- {vytask}`T1775` `(bug): Cloud-init not running userdata runcmd` +- {vytask}`T1389` `(feature): Add support for NoCloud cloud-init datasource` +- {vytask}`T1315` `(feature): Allow BGP to use address-family l2vpn evpn` + +## 2021-02-11 + +- {vytask}`T2638` `(default): FRR: New framework for configuring FRR` + +## 2021-02-08 + +- {vytask}`T3295` `(feature): Update Linux Kernel to v5.4.96 / 5.10.14` + +## 2021-02-07 + +- {vytask}`T3293` `(bug): RPKI migration script errors out after CLI rewrite` + +## 2021-02-06 + +- {vytask}`T3285` `(feature): Schedule reboots through systemd-shutdownd instead of atd` +- {vytask}`T661` `(feature): Show a warning if the router is going to reboot soon (due to "commit-confirm" command)` + +## 2021-02-05 + +- {vytask}`T2450` `(feature): Rewrite "protocols vrf" tree in XML and Python` +- {vytask}`T208` `(feature): Ability to ignore default-route from dhcpcd per interface` + +## 2021-02-03 + +- {vytask}`T3239` `(default): XML: override 'defaultValue' for mtu of certain interfaces; remove workarounds` +- {vytask}`T2910` `(feature): XML: generator should support override of variables` +- {vytask}`T2873` `(bug): "show nat destination translation address" doesn't filter at all` + +## 2021-02-02 + +- {vytask}`T3018` `(bug): Unclear behaviour when configuring vif and vif-s interfaces` +- {vytask}`T3255` `(default): Rewrite protocol RPKI to new XML/Python style` + +## 2021-02-01 + +- {vytask}`T3268` `(feature): Add VRF support to VIF-S interfaces` +- {vytask}`T3274` `(default): ask_yes_no() doesn't handle EOFError` + +## 2021-01-31 + +- {vytask}`T3276` `(feature): Update Linux Kernel to v5.4.94 / 5.10.12` + +## 2021-01-30 + +- {vytask}`T3269` `(bug): VIF-C interfaces don't verify configuration` +- {vytask}`T3240` `(feature): Support per-interface DHCPv6 DUIDs` +- {vytask}`T3273` `(default): PPPoE static default-routes deleted on interface down when not added by interface up` + +## 2021-01-29 + +- {vytask}`T3262` `(bug): DHCPv6 client runs when dhcpv6-options is configured without requesting an address or PD` +- {vytask}`T3261` `(bug): Does not possible to disable pppoe client interface.` + +## 2021-01-27 + +- {vytask}`T3257` `(feature): tcpdump supporting complete protocol` +- {vytask}`T3110` `(bug): Broken pipe in show interfaces` +- {vytask}`T651` `(enhancment): Split CI'ed, VyOS-specific packages and other packages into separate repos` +- {vytask}`T597` `(enhancment): Code testing on sonarcloud.com` +- {vytask}`T516` `(default): Make Python / XML code development more testable` +- {vytask}`T625` `(default): Lack of IKEv1 lifetime negotiation` +- {vytask}`T613` `(bug): Missing linux-kbuild` +- {vytask}`T505` `(bug): Hostapd cannot log` + +## 2021-01-26 + +- {vytask}`T3251` `(bug): PPPoE client trying to authorize with the wrong username` +- {vytask}`T2859` `(bug): show nat source translation - Errors out` + +## 2021-01-25 + +- {vytask}`T3249` `(feature): Support operation mode forwarding table output` + +## 2021-01-24 + +- {vytask}`T3230` `(bug): RPKI can't be deleted` +- {vytask}`T3243` `(feature): Update Linux Kernel to v5.4.92 / 5.10.10` + +## 2021-01-18 + +- {vytask}`T2761` `(feature): Extend "show vrrp" op-mode command with router priority` +- {vytask}`T2679` `(feature): VRRP with BFD Failure Detection` +- {vytask}`T3212` `(bug): SSH: configuration directory is not always created on boot` +- {vytask}`T3231` `(bug): "system option ctrl-alt-delete" has no effect` + +## 2021-01-17 + +- {vytask}`T3222` `(bug): Typo in BGP dampening description` +- {vytask}`T2944` `(bug): NTP by default listen on any address/interface` +- {vytask}`T3226` `(bug): Repair bridge smoke test damage` +- {vytask}`T2442` `(enhancment): Move application of STP settings for bridge members from interfaces-bridge.py to Interface.add_to_bridge()` +- {vytask}`T2381` `(bug): OpenVPN: openvpn-option parsed/rendered improperly` + +## 2021-01-16 + +- {vytask}`T3215` `(bug): Operational command "show ipv6 route" is broken` +- {vytask}`T3172` `(bug): Builds sometime after 2020-12-17 have broken routing after reboot` +- {vytask}`T3157` `(bug): salt-minion fails to start due to permission error accessing /root/.salt/minion.log` +- {vytask}`T3167` `(default): Recurring bugs in Intel NIC drivers` +- {vytask}`T3151` `(default): Decide on the final list of packages for 1.3` +- {vytask}`T3137` `(feature): Let VLAN aware bridge approach the behavior of professional equipment` +- {vytask}`T3223` `(feature): Update Linux Kernel to v5.4.89 / 5.10.7` + +## 2021-01-15 + +- {vytask}`T3210` `(feature): ISIS three-way-handshake` +- {vytask}`T3184` `(feature): Add correct desctiptions for BGP neighbors` +- {vytask}`T2850` `(feature): Add BGP template for FRR` + +## 2021-01-14 + +- {vytask}`T3218` `(feature): Replace Intel out-of-tree drivers with Linux Kernel stock drivers.` + +## 2021-01-13 + +- {vytask}`T3186` `(bug): NAT: Commit failed when applying negated(!) addresses` + +## 2021-01-12 + +- {vytask}`T3205` `(bug): Does not possible to configure tunnel mode gre-bridge` + +## 2021-01-11 + +- {vytask}`T3208` `(bug): Does not possible to change user password` +- {vytask}`T3198` `(bug): OSPF database filtering issue` +- {vytask}`T3206` `(bug): Unable to delete destination NAT rule` +- {vytask}`T3193` `(bug): DHCPv6 PD verification issues` +- {vytask}`T3201` `(bug): Operational command "show log all" is not working for RADIUS users` + +## 2021-01-10 + +- {vytask}`T3178` `(feature): Migrate vyatta-op-quagga to vyos-1x` + +## 2021-01-09 + +- {vytask}`T2467` `(bug): Restarting flow accounting fails with systemd error` +- {vytask}`T3199` `(feature): Update Linux Kernel to v5.4.88 / 5.10.6` + +## 2021-01-07 + +- {vytask}`T3192` `(feature): login: radius: add support for IPv6 RADIUS servers` + +## 2021-01-05 + +- {vytask}`T3169` `(enhancment): Reimplement smoke test of span (mirror)` +- {vytask}`T3161` `(default): Consider removing ConfigLoad.pm` +- {vytask}`T1398` `(default): Remove vyatta-config-migrate package` +- {vytask}`T805` `(enhancment): Drop config compatibility with Vyatta Core older than 6.5` + +## 2021-01-04 + +- {vytask}`T3185` `(bug): [conf-mode] Wrong CompletionHelp for Tunnel local-ip` +- {vytask}`T2601` `(bug): pppoe-server: Cannot disable CCP` + +## 2021-01-03 + +- {vytask}`T3180` `(bug): DHCP server raises NameError` + +## 2021-01-02 + +- {vytask}`T2321` `(feature): VRF support for SSH, NTP, SNMP service` +- {vytask}`T3177` `(bug): Rolling Release no longer reports VMware UUID` + +## 2021-01-01 + +- {vytask}`T3171` `(feature): Add CLI option to enable RPS (Receive Packet Steering)` + +## 2020-12-31 + +- {vytask}`T3162` `(bug): Wrong PPPoE server pado-delay parameter added to config` +- {vytask}`T3160` `(bug): PPPoE server called-sid option defined in wrong section` +- {vytask}`T3168` `(feature): Update Linux Kernel to v5.4.86` + +## 2020-12-29 + +- {vytask}`T3082` `(bug): multi_to_list must distinguish between values and defaults` +- {vytask}`T1466` `(feature): Add EAPOL login support` + +## 2020-12-28 + +- {vytask}`T1732` `(feature): Removing vyatta-webproxy module` +- {vytask}`T2666` `(feature): Packet Processing with eBPF and XDP` +- {vytask}`T2581` `(default): webproxy: implement proxy chaining` +- {vytask}`T563` `(feature): webproxy: migrate 'service webproxy' to get_config_dict()` + +## 2020-12-27 + +- {vytask}`T3150` `(bug): When configuring QoS, the setting procedure of port mirroring is wrong` + +## 2020-12-23 + +- {vytask}`T3143` `(bug): OpenVPN server: Push route config format is wrong` +- {vytask}`T3146` `(feature): Upgrade FRR from 7.4 -> 7.5 version incl. new libyang` +- {vytask}`T3145` `(feature): Update Linux Kernel to v5.4.85` +- {vytask}`T3147` `(feature): Upgrade to SaltStack version 3002.2` + +## 2020-12-22 + +- {vytask}`T3142` `(bug): OpenVPN op-command completion fails due to missing status file` +- {vytask}`T2940` `(feature): Update FRR to 7.4` +- {vytask}`T2573` `(bug): BFD op-mode commands are broken` +- {vytask}`T2495` `(feature): Add xml for ISIS [conf_mode]` +- {vytask}`T1316` `(feature): Support for IS-IS` + +## 2020-12-21 + +- {vytask}`T2619` `(bug): Bug: Changes in NAT or ZONES from 1.2 to 1.3` + +## 2020-12-20 + +- {vytask}`T3131` `(bug): Typo in ipsec preshared-secret help` +- {vytask}`T3134` `(bug): DHCPv6 DUID configuration node missing` +- {vytask}`T3140` `(feature): Relax "ethernet offload-options" CLI definition` +- {vytask}`T3132` `(feature): Enable egress flow accounting` + +## 2020-12-17 + +- {vytask}`T2810` `(default): Docs for vpn anyconnect-server` +- {vytask}`T2036` `(default): Open Connect VPN Server () support` + +## 2020-12-14 + +- {vytask}`T3128` `(bug): pppoe smoke test failed` +- {vytask}`T3129` `(feature): Update Linux Kernel to v5.4.83` +- {vytask}`T3089` `(feature): Migrate port mirroring to vyos-1x and support two-way traffic mirroring` +- {vytask}`T3130` `(feature): Replace vyos-netplug with upstream debian version` + +## 2020-12-13 + +- {vytask}`T3114` `(bug): When the bridge member is a non-ethernet interface, setting VLAN-aware bridge parameters fails` + +## 2020-12-11 + +- {vytask}`T3123` `(bug): Configuration of vti interface impossible` + +## 2020-12-10 + +- {vytask}`T3117` `(bug): OpenVPN config migration errors upgrading from 1.3-rolling-202010280217 to 1.3-rolling-202012060217` + +## 2020-12-09 + +- {vytask}`T3122` `(feature): Update Linux Kernel to v4.19.162` +- {vytask}`T3121` `(bug): get_config_dict() and key_mangling=('-', '_') Broke PowerDNS dns_forwarding config file` + +## 2020-12-08 + +- {vytask}`T2562` `(bug): VyOS can't be used as a DHCP server for a DHCP relay` + +## 2020-12-07 + +- {vytask}`T3120` `(bug): Python error when deleting nat rule` +- {vytask}`T3119` `(feature): migrate "system ip" to get_config_dict() and provide smoketest` + +## 2020-12-05 + +- {vytask}`T2744` `(bug): igmp-proxy issue: Address already in use` + +## 2020-12-04 + +- {vytask}`T3108` `(bug): Section config overlapped match with FRRConfig` +- {vytask}`T3112` `(feature): PPPoE IPv6: remove "enable" node` +- {vytask}`T3100` `(feature): Migrate DHCP/DHCPv6 server to get_config_dict()` + +## 2020-12-03 + +- {vytask}`T3105` `(bug): static-host-mapping writing in one line` +- {vytask}`T3107` `(feature): Update Linux Kernel to v4.19.161` +- {vytask}`T3104` `(bug): LLDP Traceback error` + +## 2020-12-01 + +- {vytask}`T3102` `(bug): Destination NAT fails to commit` +- {vytask}`T2713` `(bug): VyOS must not change permissions on files in /config/auth` + +## 2020-11-30 + +- {vytask}`T3091` `(feature): Add "tag" for static route` +- {vytask}`T1207` `(feature): DMVPN behind NAT` + +## 2020-11-29 + +- {vytask}`T3095` `(feature): Migrate dhcp-relay and dhcpv6-relay to get_config_dict()` + +## 2020-11-28 + +- {vytask}`T2890` `(bug): NAT error adding translation address range` +- {vytask}`T2868` `(bug): Tcp-mss option in policy calls kernel-panic` +- {vytask}`T3092` `(feature): nat: migrate to get_config_dict()` + +## 2020-11-27 + +- {vytask}`T2715` `(feature): Duplicate address detection option supporting ARP` +- {vytask}`T2714` `(feature): A collection of utilities supporting IPv6 or ipv4` +- {vytask}`T3088` `(feature): Migrate IGMP-Proxy over to get_config_dict() and add smoketests` + +## 2020-11-24 + +- {vytask}`T3087` `(feature): Update Linux Kernel to v4.19.160` + +## 2020-11-23 + +- {vytask}`T2177` `(default): Commit fails on adding disabled interface to bridge` +- {vytask}`T3066` `(bug): reboot in - Invalid time` +- {vytask}`T2802` `(bug): Tunnel interface does not apply EUI-64 IPv6 Address` +- {vytask}`T2359` `(bug): Adding IPIP6 tun interface to bridge [conf_mode] errors` +- {vytask}`T2357` `(bug): GRE-bridge conf_mode errors` +- {vytask}`T2259` `(feature): Support for bind vif-c interfaces into VRFs` +- {vytask}`T2205` `(bug): "set interface ethernet" fails on Hyper-V` +- {vytask}`T2182` `(bug): Failure to commit an IPv6 address on a tunnel interface` +- {vytask}`T2155` `(bug): Cannot set anything on Intel 82599ES 10-Gigabit SFI/SFP+` +- {vytask}`T2153` `(bug): traceroute circular reference` +- {vytask}`T3081` `(bug): get_config_dict() does not honor whitespaces in the CLI values field` +- {vytask}`T3080` `(bug): OpenVPN failing silently for a number of reasons in rolling post Nov/02` +- {vytask}`T3074` `(bug): OpenVPN site-to-site creates wrong peer address` +- {vytask}`T2542` `(bug): OpenVPN client tap interfaces not coming up` +- {vytask}`T3084` `(bug): wifi: TypeError on "show interfaces wireless info"` + +## 2020-11-21 + +- {vytask}`T3079` `(bug): Fix the problem that VLAN 1 will be deleted in VLAN-aware bridge` +- {vytask}`T3060` `(bug): OpenVPN virtual interface not coming up after upgrade` + +## 2020-11-20 + +- {vytask}`T3078` `(feature): CLI cleanup: rename "system options" -> "system option"` +- {vytask}`T2997` `(feature): DHCP: disallow/do-not-request certain options when requesting IP address from server` +- {vytask}`T3077` `(feature): WireGuard: automatically create link-local IPv6 adresses` +- {vytask}`T2550` `(default): OpenVPN: IPv4 not working in client mode` +- {vytask}`T3072` `(feature): Migrate tunnel interfaces to new get_config_dict() approach` +- {vytask}`T3065` `(feature): Add "interfaces wirelessmodem" IPv6 support` +- {vytask}`T3048` `(feature): Drop static smp-affinity for a more dynamic way using tuned` + +## 2020-11-19 + +- {vytask}`T3067` `(bug): Wireless interface can no longer be added to the bridge after bridge VLAN support` +- {vytask}`T3075` `(feature): Update Linux Kernel to v4.19.158` + +## 2020-11-16 + +- {vytask}`T3003` `(enhancment): Extend smoketest framework to allow loading an arbitrary config file` + +## 2020-11-15 + +- {vytask}`T3069` `(bug): OpenVPN routed networks not available` +- {vytask}`T3038` `(feature): Supporting AZERTY keyboards` +- {vytask}`T2993` `(bug): op-mode: lldp: show lldp neighbors - AttributeError: 'str' object has no attribute 'items'` + +## 2020-11-14 + +- {vytask}`T3041` `(bug): Intel QAT: vyos-1.3-rolling-202011020217-amd64 kernel panic during configure` + +## 2020-11-13 + +- {vytask}`T3063` `(feature): Add support for Huawei LTE Module ME909s-120` +- {vytask}`T3059` `(bug): L2TPv3 interface: Enforced to shutdown but no command to enable interface permanently` + +## 2020-11-12 + +- {vytask}`T3064` `(feature): Update Linux Kernel to v4.19.157` + +## 2020-11-10 + +- {vytask}`T2103` `(bug): Abnormal interface names if VIF present` + +## 2020-11-08 + +- {vytask}`T3050` `(bug): Broken address/subnet validation on NAT configuration` + +## 2020-11-07 + +- {vytask}`T2914` `(bug): OpenVPN: Fix for IPv4 remote-host hostname in client mode:` +- {vytask}`T2653` `(feature): "set interfaces" Python handler code improvements - next iteration` +- {vytask}`T311` `(feature): DHCP: set client-hostname via CLI` + +## 2020-11-06 + +- {vytask}`T3051` `(bug): OpenVPN: multiple client routes do not work in server mode` +- {vytask}`T3046` `(bug): openvpn directory is not auto-created` +- {vytask}`T3052` `(feature): Update Linux firmware files to 20201022 version` +- {vytask}`T2731` `(bug): "show interfaces" returns invalid state when link is down` + +## 2020-11-05 + +- {vytask}`T3049` `(feature): Update Linux Kernel to v4.19.155` +- {vytask}`T2994` `(feature): Migrate OpenVPN interfaces to get_config_dict() syntax` + +## 2020-11-03 + +- {vytask}`T3043` `(feature): Wireless: Refactor CLI` +- {vytask}`T3034` `(feature): Add WiFi WPA 3 support` +- {vytask}`T2967` `(bug): Duplicate IPv6 BFD peers created` +- {vytask}`T2483` `(bug): DHCP most likely not restarting pdns_recursor` + +## 2020-11-02 + +- {vytask}`T3024` `(bug): DHCPv6 PD configuration doesn't really render an expected behavior` + +## 2020-11-01 + +- {vytask}`T3036` `(feature): OpenVPN remote-address does not accept IPv6 address` +- {vytask}`T2193` `` (feature): Display disabled VRRP instances in a `show vrrp` output `` + +## 2020-10-30 + +- {vytask}`T2790` `(feature): Add ability to set ipv6 protocol route-map for OSPFv3` +- {vytask}`T3033` `(feature): Update Linux Kernel to v4.19.154` +- {vytask}`T2969` `(bug): OpenVPN: command_set on interface is not applied, if interface doesn't come up in commit` + +## 2020-10-28 + +- {vytask}`T2631` `(default): l2tp, sstp, pptp add option to disable radius accounting` +- {vytask}`T2630` `(feature): Allow Interface MTU over 9000` +- {vytask}`T3027` `(bug): Unable to update system Signature check FAILED` +- {vytask}`T2995` `(bug): Enhancements/bugfixes for vyos_dict_search()` +- {vytask}`T2968` `(feature): Add support for Intel Atom C2000 series QAT` + +## 2020-10-27 + +- {vytask}`T3026` `(default): qemu: update script for deprecated ssh_host_port_min/max` +- {vytask}`T2938` `(feature): Adding remote Syslog RFC5424 compatibility` +- {vytask}`T2924` `(bug): Using 'set src' in a route-map invalidates it as part of a subsequent boot-up` +- {vytask}`T2587` `(bug): Cannot enable the interface when the MTU is set to less than 1280` +- {vytask}`T2885` `(default): configd: print commit errors to config session terminal` +- {vytask}`T2808` `(default): Add smoketest to ensure script consistency with config daemon` +- {vytask}`T2582` `(default): Script daemon to offload processing during commit` +- {vytask}`T1721` `(bug): Recursive Next Hop not updated for static routes` + +## 2020-10-24 + +- {vytask}`T3007` `(default): HTTP-API should use config load script, not backend config load` +- {vytask}`T3009` `(bug): vpn l2tp remoteaccess require option broken` +- {vytask}`T3010` `(bug): ttl option of gre-bridge` +- {vytask}`T3005` `(bug): Intel: update out-of-tree drivers, i40e driver warning` +- {vytask}`T3004` `(feature): ConfigSession should (optionally) use config load script` +- {vytask}`T2723` `(feature): Support tcptraceroute` + +## 2020-10-22 + +- {vytask}`T2978` `(bug): IPoE service does not work on shared mode` +- {vytask}`T2906` `(bug): OpenVPN: tls-auth missing key direction` + +## 2020-10-21 + +- {vytask}`T2828` `(bug): BGP conf_mode error enforce-first-as` +- {vytask}`T2749` `(bug): Setting ethx configuration takes a long time` +- {vytask}`T2138` `(default): Can't load archived configs as they are gzipped` + +## 2020-10-20 + +- {vytask}`T2987` `(bug): VxLAN not working properly after upgrading to latest October build and with a new installation` +- {vytask}`T2989` `(default): MPLS documentation expansion` + +## 2020-10-19 + +- {vytask}`T1588` `(bug): VRRP failed to start if any of its interaces not exist` +- {vytask}`T1385` `(feature): Allow bonding interfaces to have pseudo-ethernet interfaces` +- {vytask}`T3000` `(bug): Mismatch between "prefix-length" and "preference" in dhcp6-server syntax` +- {vytask}`T2992` `(feature): Automatically verify sha256 checksum on ISO download` +- {vytask}`T752` `(feature): Add an option to disable IPv4 forwarding on specific interface only` + +## 2020-10-18 + +- {vytask}`T2965` `(feature): Brief BFD Peer Info` +- {vytask}`T2907` `(feature): OpenVPN: Option to disable encryption` +- {vytask}`T2985` `(feature): Add glue code to create bridge interface on demand` + +## 2020-10-17 + +- {vytask}`T2980` `(bug): FRR bfdd crash due to invalid length` +- {vytask}`T2991` `(feature): Update WireGuard to 1.0.20200908` +- {vytask}`T2990` `(feature): Update Linux Kernel to v4.19.152` +- {vytask}`T2981` `(feature): MPLS LDP neighbor session clear capability` +- {vytask}`T2792` `` (default): Failed to run `sudo make qemu` with vyos-build container due to the change of packer `` + +## 2020-10-13 + +- {vytask}`T2976` `(bug): Client IP pool does not work for PPPoE local users` + +## 2020-10-12 + +- {vytask}`T2951` `(bug): Cannot enable logging for monitor nat` +- {vytask}`T2782` `(bug): Changing timezone, does not restart rsyslog` + +## 2020-10-06 + +- {vytask}`T2957` `(bug): show openvpn not printing anything` + +## 2020-10-05 + +- {vytask}`T2963` `(bug): Wireless: WIFI is not password protected when security wpa mode is not defined but passphrase is` + +## 2020-10-04 + +- {vytask}`T2953` `(feature): Accel-PPP services CLI config cleanup (SSTP, L2TP, PPPoE, IPoE)` +- {vytask}`T2829` `(bug): PPPoE server: mppe setting is implemented as node instead of leafNode` +- {vytask}`T2960` `(feature): sstp: migrate to get_config_dict()` + +## 2020-10-03 + +- {vytask}`T2956` `(feature): Add support for list of defaultValues` +- {vytask}`T2955` `(feature): Update Linux Kernel to v4.19.149` + +## 2020-10-02 + +- {vytask}`T2952` `(bug): configd: timeout breaks synchronization of messages, causing freeze` + +## 2020-10-01 + +- {vytask}`T2945` `(bug): Interface removed from bridge on setting change` +- {vytask}`T2948` `(bug): NAT: OSError when configuring translation address range` +- {vytask}`T2936` `(feature): Migrate PPPoE server to get_config_dict() do reduce boilerplate code` + +## 2020-09-30 + +- {vytask}`T2939` `(bug): Wireguard Remove Peer Fails` + +## 2020-09-29 + +- {vytask}`T2919` `(feature): PPPoE server: Called-Station-Id attribute` +- {vytask}`T2918` `(feature): Accounting interim jitter for pppoe, l2tp, pptp, ipoe` +- {vytask}`T2917` `(feature): PPPoE server: Preallocate NAS-Port-Id` +- {vytask}`T2937` `(feature): Update Linux Kernel to v4.19.148` + +## 2020-09-27 + +- {vytask}`T2930` `(feature): Support configuration of MAC address for VXLAN and GENEVE tunnel` + +## 2020-09-26 + +- {vytask}`T2856` `` (bug): equuleus: `show version all` throws broken pipe exception on abort `` +- {vytask}`T2929` `(bug): Upgrading from 1.2 (crux) to 1.3 rolling causes vyos.configtree.ConfigTreeError for RADIUS settings` +- {vytask}`T2928` `(bug): MTU less then 1280 bytes and IPv6 will raise FileNotFoundError` +- {vytask}`T2926` `(bug): snmp.py missing an import` +- {vytask}`T2912` `(feature): When setting MTU check for hardware maximum supported MTU size` + +## 2020-09-25 + +- {vytask}`T2915` `(bug): Lost "proxy-arp-pvlan" option for vlan` +- {vytask}`T2925` `(feature): Update Linux Kernel to v4.19.147` +- {vytask}`T2921` `(feature): Migrate "service dns forwarding" to get_config_dict() for ease of source maintenance` + +## 2020-09-24 + +- {vytask}`T2896` `(bug): set ip route 0.0.0.0/0 dhcp-interface eth0` +- {vytask}`T2923` `(bug): Configuring DHCPv6-PD without a interface to delegate to raises TypeError` + +## 2020-09-23 + +- {vytask}`T2846` `(bug): ip route doesn't show longer-prefixes` + +## 2020-09-20 + +- {vytask}`T2904` `(feature): 802.1ad / Q-in-Q ethertype default not utilized` +- {vytask}`T2905` `(feature): Sync CLI nodes between PPPoE and WWAN interface` +- {vytask}`T2903` `(feature): Q-in-Q (802.1.ad) ethertype should be defined explicitly and not via its raw value` + +## 2020-09-19 + +- {vytask}`T2894` `(bug): bond: lacp: member interfaces get removed once bond interface has vlans configured` +- {vytask}`T2901` `(feature): Update Linux Kernel to v4.19.146` +- {vytask}`T2900` `(bug): DNS forwarding: invalid warning is shown for "system name-server" or "system name-servers-dhcp" even if present` + +## 2020-09-18 + +- {vytask}`T945` `(bug): Unable to change configuration after changing it from script (vbash + script-template)` + +## 2020-09-16 + +- {vytask}`T2886` `(bug): RADIUS authentication broken only returns operator level` +- {vytask}`T2887` `(bug): WiFi ht40+ channel width is not set in hostaptd.conf` + +## 2020-09-15 + +- {vytask}`T2515` `(bug): Ethernet interface is automatically disabled when removing it from bond` + +## 2020-09-14 + +- {vytask}`T2872` `(bug): "Show log" for nat and openvpn got intermixed` +- {vytask}`T2301` `(bug): Cannot delete PBR` +- {vytask}`T2880` `(feature): Update Linux Kernel to v4.19.145` +- {vytask}`T2879` `(feature): Cleanup 4.19.144 kernel configuration` + +## 2020-09-13 + +- {vytask}`T2858` `(feature): Rewrite dynamic dns client to get_config_dict()` +- {vytask}`T2857` `(feature): Cleanup Intel QAT configuration script` +- {vytask}`T2877` `(feature): LACP / bonding: support configuration of minimum number of links` + +## 2020-09-12 + +- {vytask}`T2863` `(default): Wireguard IPv6 Link-Local Addresses Are Not Unique` +- {vytask}`T2876` `(feature): Update Linux Kernel to v4.19.144` + +## 2020-09-10 + +- {vytask}`T2870` `(feature): Update Linux Kernel to v5.8.8` + +## 2020-09-09 + +- {vytask}`T2728` `(bug): Protocol option ignored for IPSec peers in transport mode` +- {vytask}`T1934` `(default): Change default hostname when deploy from OVA without params.` +- {vytask}`T1953` `(bug): DDNS service name validation rejects valid service names` + +## 2020-09-07 + +- {vytask}`T1729` `(default): PIM (Protocol Independent Multicast) implementation` + +## 2020-09-06 + +- {vytask}`T2860` `(bug): Update Accel-PPP to fix l2tp CVE` + +## 2020-09-02 + +- {vytask}`T2833` `(bug): RIP outgoing update filter list no longer operational` +- {vytask}`T2849` `(bug): vyos.xml.defaults should return a list on multi nodes, by default` + +## 2020-08-31 + +- {vytask}`T2636` `(bug): get_config_dict() shall always return a list on <multi/> nodes` + +## 2020-08-30 + +- {vytask}`T2843` `(feature): Upgrade Linux Kernel to 5.8 series` +- {vytask}`T2814` `` (default): kernel 5.1+ : NAT : module `nft_chain_nat_ipv4` renamed `` +- {vytask}`T2839` `(feature): Upgrade WireGuard user-space tools and Kernel module` +- {vytask}`T2842` `(feature): Replace custom "wireguard, wireguard-tools" package with debian-backports version` + +## 2020-08-29 + +- {vytask}`T2836` `(default): show system integrity broken in 1.3` + +## 2020-08-28 + +- {vytask}`T2126` `(bug): show vpn ipsec sa IPSec - Process NOT Running` +- {vytask}`T2813` `(bug): NAT: possible to commit illegal source nat without translation` +- {vytask}`T1463` `` (bug): Missing command `show ip bgp scan` appears in command completion `` + +## 2020-08-27 + +- {vytask}`T2832` `(feature): Migrate vyos-smoketest content into vyos-1x` + +## 2020-08-26 + +- {vytask}`T2830` `(default): Migrate "service https" to use get_config_dict()` +- {vytask}`T2831` `(feature): Update Linux Kernel to v4.19.142` + +## 2020-08-25 + +- {vytask}`T2826` `(bug): frr: frr python lib error in replace_section` + +## 2020-08-24 + +- {vytask}`T2423` `(bug): Loadkey scp ssh key errors` + +## 2020-08-23 + +- {vytask}`T2811` `(bug): Cannot delete vpn anyconnect` +- {vytask}`T2823` `(bug): VXLAN has state A/D after configuration` +- {vytask}`T2812` `(default): Add basic smoketest for anyconnect` + +## 2020-08-22 + +- {vytask}`T2822` `(feature): Update Linux Kernel to v4.19.141` +- {vytask}`T2821` `(feature): Support DHCPv6-PD without "address dhcpv6"` +- {vytask}`T2677` `(feature): Proposal for clearer DHCPv6-PD configuration options` + +## 2020-08-20 + +- {vytask}`T2209` `(bug): Documentation has reference to the old 'user x level admin' option` +- {vytask}`T1665` `(default): prefix-list and prefix-list6 rules incorrectly accept a host address where prefix is required` +- {vytask}`T2815` `(default): Move certbot config directory under /config/auth` + +## 2020-08-19 + +- {vytask}`T2794` `(bug): op-mode: lldp: "show lldp neighbors" IndexError: list index out of range` +- {vytask}`T2791` `(feature): "monitor traceroute" has no explicit IPv4/IPv6 support` +- {vytask}`T1515` `(bug): FRR ospf6d crashes when performing: "show ipv6 ospfv3 database"` + +## 2020-08-16 + +- {vytask}`T2277` `(bug): dhclient-script-vyos does not support VRFs` +- {vytask}`T2090` `(default): Deleting 'service salt-minion' causes python TypeError` + +## 2020-08-15 + +- {vytask}`T2797` `(feature): Update Linux Kernel to v4.19.139` +- {vytask}`T2796` `(bug): PPPoE-Server: listen interface is mandatory but validation check is missing` + +## 2020-08-14 + +- {vytask}`T2795` `(bug): console server fails to commit` + +## 2020-08-12 + +- {vytask}`T2786` `(bug): OSPF Interface Cost` +- {vytask}`T2325` `(bug): NHRP op-mode errors with missing daemon socket` +- {vytask}`T2227` `(feature): MPLS documentation` +- {vytask}`T2767` `(bug): The interface cannot be disabled for network enabled configuration` +- {vytask}`T2316` `(bug): DHCP-server op-mode errors` + +## 2020-08-11 + +- {vytask}`T2779` `(bug): LLDP: "show lldp neighbors interface" does not yield any result` +- {vytask}`T2379` `(bug): DHCPv6 address for interface deletion triggers a script error` +- {vytask}`T2784` `(default): Remove unused arg from host_name.py functions verify and get_config` + +## 2020-08-10 + +- {vytask}`T2780` `(feature): Update Linux Kernel to v4.19.138` + +## 2020-08-08 + +- {vytask}`T2716` `(bug): Shaper-HFSC shapes but does not control latency correctly` +- {vytask}`T2497` `(default): Cache config string during commit` +- {vytask}`T2501` `(bug): Cannot recover from failed boot config load` +- {vytask}`T1974` `(feature): Allow route-map to set administrative distance` +- {vytask}`T1949` `(bug): Multihop IPv6 BFD is unconfigurable` + +## 2020-08-04 + +- {vytask}`T2758` `(bug): router-advert: 'infinity' is not a valid integer number` +- {vytask}`T2637` `(bug): Vlan is not removed from the system` +- {vytask}`T1287` `(bug): No DHCPv6 leases reported for "show dhcpv6 client leases"` + +## 2020-08-03 + +- {vytask}`T2241` `(default): Changing settings on an interface causes it to fall out of bridge` +- {vytask}`T2757` `(bug): "show system image version" contains additional new-line character breaking output` +- {vytask}`T1826` `(bug): Misleading message on "reboot at" command` +- {vytask}`T1511` `(default): Rewrite ethernet setup scripts to python` +- {vytask}`T1600` `(default): Convert 'ping' operation from vyatta-op to new syntax` +- {vytask}`T1486` `(bug): Unknown LLDP version reported to peers` +- {vytask}`T1414` `(enhancment): equuleus: buster: 10-unmountfs.chroot fail under apply` +- {vytask}`T1076` `(bug): SSH: make configuration (sshd_config) volatile and store it to /run` +- {vytask}`T2724` `(feature): Support for IPv6 Toolset` +- {vytask}`T2323` `(bug): LLDP: "show lldp neighbors detail" returns warnings when service is not configured` +- {vytask}`T1754` `(bug): DHCPv6 client is impossible to restart` + +## 2020-08-02 + +- {vytask}`T2756` `(feature): Accel-PPP: make RADIUS accounting port configurable` + +## 2020-08-01 + +- {vytask}`T2752` `(bug): Exception when configuring unavailable ethernet interface` +- {vytask}`T2751` `(feature): Update Linux Kernel to v4.19.136` +- {vytask}`T2753` `(feature): Rewrite "add system image" op mode commands in XML` +- {vytask}`T2690` `(feature): Add VRF support to the add system image command` + +## 2020-07-30 + +- {vytask}`T2746` `(feature): IPv6 link-local addresses not configured` +- {vytask}`T2678` `(bug): High RAM usage on SSH logins with lots of IPv6 routes in the routing table.` +- {vytask}`T2701` `` (bug): `vpn ipsec pfs enable` doesn't work with IKE groups `` +- {vytask}`T2745` `(feature): router-advert: migrate to get_config_dict()` + +## 2020-07-29 + +- {vytask}`T2743` `(feature): WireGuard: move key migration from config script to migration script` +- {vytask}`T2742` `(feature): mDNS repeater: migrate to get_config_dict()` + +## 2020-07-28 + +- {vytask}`T1117` `(feature): 'show ipv6 bgp route-map' missing` +- {vytask}`T928` `(feature): Add support for PIM (Protocol-Independent Multicast)` + +## 2020-07-27 + +- {vytask}`T2729` `(feature): Pseudo-ethernet replace fail message` +- {vytask}`T1249` `(feature): multiple PBR rules can set to a single interface` +- {vytask}`T1956` `(feature): PPPoE server: support PADO-delay` +- {vytask}`T1295` `(feature): FRR: update documentation` +- {vytask}`T1222` `(bug): OSPF routing problem - route looping` +- {vytask}`T1158` `(bug): Route-Map configuration dropped updating rc11 to epa2` +- {vytask}`T1130` `(bug): Deleting BGP communities from prefix does not work` +- {vytask}`T2067` `(feature): pppoe-server: Add possibility set multiple service-name` + +## 2020-07-26 + +- {vytask}`T2734` `(feature): WireGuard: fwmark CLI definition is inconsistent` +- {vytask}`T2733` `(feature): Support MTU configuration on pseudo ethernet devices` +- {vytask}`T2644` `(default): Bonding interfaces cannot be disabled` +- {vytask}`T2476` `(bug): Bond member description change leads to network outage` +- {vytask}`T2443` `(feature): NHRP: Add debugging information to syslog` +- {vytask}`T2021` `(bug): OSPFv3 doesn't support decimal area syntax` +- {vytask}`T1901` `(bug): Semicolon in values is interpreted as a part of the shell command by validators` +- {vytask}`T2000` `(bug): strongSwan does not install routes to table 220 in certain cases` +- {vytask}`T2091` `(bug): swanctl.conf file is not generated properly if more than one IPsec profile is used` +- {vytask}`T1983` `(feature): Expose route-map when BGP routes are programmed in to FIB` +- {vytask}`T1973` `(feature): Allow route-map to match on BGP local preference value` +- {vytask}`T1853` `(bug): wireguard - disable peer doesn't work` +- {vytask}`T1985` `(feature): pppoe: Enable ipv6 modules without configured ipv6 pools` + +## 2020-07-25 + +- {vytask}`T2730` `(feature): Update Linux Kernel to v4.19.134` +- {vytask}`T2106` `(bug): Wrong interface states after reboot` +- {vytask}`T1507` `(default): cli: logical redundancy with boolean type` + +## 2020-07-24 + +- {vytask}`T2097` `(bug): Problems when using <path> as completion helper in op-mode` +- {vytask}`T2092` `(bug): dhcp-server rfc3442 static route should add default route` +- {vytask}`T1817` `(bug): BGP next-hop-self not working.` +- {vytask}`T1462` `(bug): Upgrade path errors 1.1.8 to 1.2.1-S2` +- {vytask}`T1372` `(bug): Diff functionality behaves incorrectly in some cases` +- {vytask}`T2073` `(feature): ipoe-server: reset op-mode command for sessions` +- {vytask}`T1715` `(bug): System DNS Server Order Incorrect` + +## 2020-07-23 + +- {vytask}`T2673` `(bug): After the bridge is configured with Mac, bridge is automatically disabled` +- {vytask}`T2626` `(bug): Changing pseudo-ethernet mode, throws CLI error` +- {vytask}`T2608` `(bug): delete pseudo-ethernet failed (another error type)` +- {vytask}`T2527` `(bug): bonding: the last slave interface is not deleted` +- {vytask}`T2358` `(bug): ip6ip6 bridge conf_mode errors` +- {vytask}`T2346` `(bug): Setting hostname yields temporary file error` +- {vytask}`T2330` `(bug): Vpn op-mode syntax` +- {vytask}`T2188` `(default): NTP op-mode commands don't work` + +## 2020-07-22 + +- {vytask}`T2718` `(bug): ntp.conf updated incorrectly` +- {vytask}`T2658` `(bug): Interface description comment display error` +- {vytask}`T2643` `(bug): show interfaces does not scale with terminal width` +- {vytask}`T2725` `(bug): Config fails to load if user has no password` +- {vytask}`T2707` `(default): Allow alternative initialization data for Config` + +## 2020-07-20 + +- {vytask}`T2709` `(bug): Destination NAT translation port without address fails to commit` +- {vytask}`T2519` `(bug): Broadcast address does not add automatically` + +## 2020-07-19 + +- {vytask}`T2708` `(bug): "show flow-accounting" should not display script's "usage" help` +- {vytask}`T2592` `(default): dhcp-relay discarding packets on valid interfaces` +- {vytask}`T2712` `(feature): udp-broadcast-relay: serivce no longer starts` +- {vytask}`T2706` `(feature): Support NDP protocol monitoring` + +## 2020-07-18 + +- {vytask}`T2704` `(bug): connect/disconnect Missing newline in op-mode tab completion helper` +- {vytask}`T2689` `(feature): Add helper functions to query changes between session and effective configs` +- {vytask}`T2585` `(bug): Unable to access the Internet after opening PPPoE on-demand dialing` + +## 2020-07-15 + +- {vytask}`T2675` `(bug): DNS service failed to start` +- {vytask}`T2596` `(feature): Allow specifying source IP for 'add system image'` + +## 2020-07-12 + +- {vytask}`T1575` `` (default): `show snmp mib ifmib` crashes with IndexError `` +- {vytask}`T2696` `(bug): Some bugfixes of vyatta-wanloadbalance` + +## 2020-07-11 + +- {vytask}`T2687` `(feature): SNMP: change logic on v3 password encryption` +- {vytask}`T2693` `(bug): Dhcp6c cannot be restarted after PPPoE link is reset` + +## 2020-07-08 + +- {vytask}`T2692` `(bug): Evaluate Setting Default Hash Policy to L3+L4` +- {vytask}`T2646` `(bug): Sysctl for IPv4 ECMP Hash Policy Not Set` + +## 2020-07-07 + +- {vytask}`T2691` `(bug): Upgrade from 1.2.5 to 1.3-rolling-202007040117 results in broken config due to case mismatch` +- {vytask}`T2389` `(bug): BGP community-list unknown command` +- {vytask}`T2686` `(bug): FRR: BGP: large-community configuration is not applied properly after upgrading FRR to 7.3.x series` + +## 2020-07-06 + +- {vytask}`T2680` `(bug): dhcp6c service cannot recover when it fails` + +## 2020-07-05 + +- {vytask}`T2684` `(feature): Update Linux Kernel to v4.19.131` +- {vytask}`T2685` `(feature): Update Accel-PPP to fix SSTP client issues` +- {vytask}`T2681` `(bug): PPPoE stops negotiating IPv6` + +## 2020-07-04 + +- {vytask}`T2682` `(bug): VRF aware services - connection no longer possible after system reboot` + +## 2020-07-03 + +- {vytask}`T2670` `(default): Remove dependency on show_config from get_config_dict` +- {vytask}`T2676` `(feature): NTP: migrate to get_config_dict() implementation` + +## 2020-07-02 + +- {vytask}`T2668` `(default): get_config_dict: add get_first_key arg to utility function get_sub_dict` + +## 2020-07-01 + +- {vytask}`T2662` `(default): get_config_dict includes node name as key only for tag and leaf nodes` +- {vytask}`T2667` `(feature): get_config_dict: Use utility function for non-empty path argument` + +## 2020-06-28 + +- {vytask}`T2660` `(bug): XML: Python default dictionary does not obey underscore (_) when flat is False` + +## 2020-06-27 + +- {vytask}`T2656` `(bug): XML: Python default dictionary returns wrong dictionary level(s)` + +## 2020-06-26 + +- {vytask}`T2642` `(bug): sshd fails to start due to configuration error` +- {vytask}`T2588` `(default): Add support for default values to the interface-definition format` +- {vytask}`T2622` `(bug): Pseudo-ethernet interface config disappears across versions` +- {vytask}`T2057` `(feature): Generalised Interface configuration` +- {vytask}`T2625` `(feature): Provide generic Library for package builds` + +## 2020-06-25 + +- {vytask}`T2487` `(bug): VRRP does not display info when group disabled` +- {vytask}`T2329` `(bug): Show remote config openvpn` +- {vytask}`T2165` `(bug): When trying to add route to ripng it complains that ip address should be IPv4 format` +- {vytask}`T2159` `(default): webproxy log read from wrong file` +- {vytask}`T2101` `(feature): Fix VXLAN config option parsing` +- {vytask}`T2062` `(bug): Wrong dhcp-server static route subnet bytes` +- {vytask}`T1986` `(bug): Python configuration manipulation library leaks open files` +- {vytask}`T1762` `(bug): VLAN interface configuration fails after internal representation of edit level was switched from a string to a list` +- {vytask}`T1538` `(bug): Update conntrack-sync packages to fix VRRP issues` +- {vytask}`T1808` `(feature): add package nftables` + +## 2020-06-24 + +- {vytask}`T2634` `(feature): remove autogeneration of interface "ip section" from vyatta-cfg-system` +- {vytask}`T2633` `(bug): Error with arp_accept on tun interface` +- {vytask}`T2595` `(feature): Update Linux Kernel to v4.19.128` +- {vytask}`T1938` `(bug): syslog doesn't start automatically` + +## 2020-06-23 + +- {vytask}`T2632` `(bug): WireGuard: Cannot use only one preshared-key for one peer` +- {vytask}`T1829` `(bug): Install Image script does not respect size of partition greater than 2G but less than disk size` +- {vytask}`T2635` `(feature): SSH: migrate to get_config_dict()` + +## 2020-06-22 + +- {vytask}`T2486` `(bug): DNS records set via 'system static-host-mapping' return NXDOMAIN from 'service dns forwarding' after a request to a forwarded zone` +- {vytask}`T2463` `(bug): DHCP-received nameserver not added to vyos-hostsd` +- {vytask}`T2534` `(bug): pdns-recursor override.conf error` +- {vytask}`T2054` `(bug): Changing "system name-server" doesn't update dns forwarding config, neither does "restart dns forwarding"` +- {vytask}`T2225` `(default): PIM/IGMP documentation` + +## 2020-06-21 + +- {vytask}`T2624` `(feature): Serial Console: fix migration script for configured powersave and no console` +- {vytask}`T2610` `(bug): default-lifetime is not reflected in the RA message` +- {vytask}`T2299` `(feature): login radius-server priority` +- {vytask}`T1739` `(bug): Serial interface seems not to be deleted properly` +- {vytask}`T480` `(bug): Error if no serial interface is present (/dev/ttyS0: not a tty)` + +## 2020-06-20 + +- {vytask}`T2621` `(bug): show interfaces repeats interface description if it is longer then an arbitrary number of characters` +- {vytask}`T2618` `(default): Conversion from 1.2 to 1.3 lost RADVD prefix autonomous-flag setting` + +## 2020-06-19 + +- {vytask}`T2589` `(bug): delete pseudo-ethernet failed` +- {vytask}`T2490` `(feature): Add serial (rs232) to ssh bridge service` + +## 2020-06-18 + +- {vytask}`T2614` `(default): Add an option to mangle dict keys to vyos.config.get_config_dict()` +- {vytask}`T2026` `(default): Make cli-shell-api correctly exit with non-zero code on failures` +- {vytask}`T1868` `(default): Add opportunity to get current values from API` + +## 2020-06-17 + +- {vytask}`T2478` `(feature): login radius: use NAS-IP-Address if defined source address` +- {vytask}`T2141` `(bug): Static ARP is not applied on boot` +- {vytask}`T2609` `(bug): router-advert: radvd does not start when lifetime is improperly configured` +- {vytask}`T1720` `(feature): support for more 'show ip route' commands` + +## 2020-06-16 + +- {vytask}`T2604` `(default): Remove use of is_tag in system-syslog.py` +- {vytask}`T2605` `(bug): SNMP service is not disabled by default` +- {vytask}`T2568` `(bug): Add some missing checks in config` +- {vytask}`T2156` `(default): PIM op-mode commands` + +## 2020-06-15 + +- {vytask}`T2600` `(bug): RADIUS system login configuration rendered wrongly` +- {vytask}`T2599` `(bug): "show interfaces" does not list VIF interfaces in ascending order` +- {vytask}`T2591` `(bug): show command has wrong interfaces ordering` +- {vytask}`T2576` `(bug): "show interfaces" does not return VTI` + +## 2020-06-14 + +- {vytask}`T2354` `(bug): Wireless conf_mode errors` +- {vytask}`T2593` `(bug): source NAT translation port can not be set when translation address is set to masquerade` +- {vytask}`T2594` `(default): Missing firmware for iwlwifi` + +## 2020-06-11 + +- {vytask}`T2578` `(bug): ipaddrcheck unaware of /31 host addresses - can no longer assign /31 mask to interface addresses` +- {vytask}`T2571` `(bug): NAT destination port with ! results in error` +- {vytask}`T2570` `(feature): Drop support for "system console device <device> modem"` +- {vytask}`T2586` `(bug): WWAN default route is not installed into VRF` +- {vytask}`T2561` `(feature): Drop support for "system console netconsole"` +- {vytask}`T2569` `(feature): Migrate "set system console" to XML and Python representation` + +## 2020-06-10 + +- {vytask}`T2575` `(bug): pppoe-server: does not possibly assign IP address` +- {vytask}`T2565` `(bug): Cannot connect to l2tp server with radius auth` +- {vytask}`T2553` `(bug): set interface ethN vif-s nnnn does not commit` + +## 2020-06-08 + +- {vytask}`T2559` `(feature): Add operational mode command to retrieve hardware sensor data` + +## 2020-06-07 + +- {vytask}`T2529` `(feature): WWAN: migrate from ttyUSB device to new device in /dev/serial/by-bus` +- {vytask}`T2560` `(feature): New op-mode command to display information about USB interfaces` + +## 2020-06-05 + +- {vytask}`T2548` `(bug): Interfaces allowing inappropriate network addresses to be assigned` +- {vytask}`T1958` `(default): Include only firmware we actually need` + +## 2020-06-04 + +- {vytask}`T2514` `(enhancment): "mac" setting for bond members` + +## 2020-06-02 + +- {vytask}`T2129` `(feature): XML schema: tagNode not allowed on first level in new XML op-mode definition` +- {vytask}`T2545` `(feature): Show physical device offloading capabilities for specified ethernet interface` +- {vytask}`T2544` `(feature): Enable Kernel KONFIG_KALLSYMS` +- {vytask}`T2543` `(feature): Kernel: always build perf binary but ship as additional deb package to not bloat the image` +- {vytask}`T1096` `(bug): BGP process memory leak` + +## 2020-06-01 + +- {vytask}`T2535` `(feature): Update Intel QAT drivers to 1.7.l.4.9.0-00008` +- {vytask}`T2537` `(feature): Migrate "show log dns" from vyatta-op to vyos-1x` +- {vytask}`T2536` `(bug): "show log dns forwarding" still refers to dnsmasq` +- {vytask}`T2538` `(feature): Update Intel NIC drivers to recent release (preparation for Kernel >=5.4)` +- {vytask}`T2526` `(feature): Wake-On-Lan CLI implementation` + +## 2020-05-31 + +- {vytask}`T2532` `(feature): VRF aware OpenVPN` + +## 2020-05-30 + +- {vytask}`T2388` `(feature): template rendering should create folder and set permission` +- {vytask}`T2531` `(feature): Update Linux Kernel to v4.19.125` +- {vytask}`T2530` `(bug): Error creating VRF with a name of exactly 16 characters` + +## 2020-05-29 + +- {vytask}`T2528` `(bug): "update dns dynamic" throws FileNotFoundError excepton` + +## 2020-05-28 + +- {vytask}`T1291` `(default): Under certain conditions the VTI will stay forever down` + +## 2020-05-27 + +- {vytask}`T2395` `(feature): HTTP API move to flask/flask-restx as microframework` +- {vytask}`T1121` `(bug): Can't search for prefixes by community: Community malformed: AA:NN` + +## 2020-05-26 + +- {vytask}`T2520` `(bug): show conntrack fails with Perl error` +- {vytask}`T2502` `(bug): PPPoE default route not installed for IPv6 when "default-route auto"` +- {vytask}`T2458` `(feature): Update FRR to 7.3.1` +- {vytask}`T2506` `(feature): DHCPv6-PD add prefix hint CLI option` + +## 2020-05-25 + +- {vytask}`T2391` `(bug): pppoe-server session-control does not work` +- {vytask}`T2269` `(feature): SSTP specify tunnels names` +- {vytask}`T1137` `(bug): 'sh ip bgp sum' being truncated` + +## 2020-05-22 + +- {vytask}`T2491` `(feature): MACsec: create CLI for replay protection` +- {vytask}`T2489` `(feature): Add MACsec interfaces to "show interfaces" output` +- {vytask}`T2201` `(feature): Rewrite protocol BGP [op-mode] to new XML/Python style` +- {vytask}`T2492` `(feature): Do not set encrypted user password when it is not changed` +- {vytask}`T2496` `(feature): Set default to new syntax for config file component versions` +- {vytask}`T2493` `(feature): Update Linux Kernel to v4.19.124` +- {vytask}`T2380` `(bug): After PPPoE 0 is restarted, the default static route is lost` + +## 2020-05-21 + +- {vytask}`T1876` `(bug): IPSec VTI tunnels are deleted after rekey and dangling around as A/D` +- {vytask}`T2488` `(feature): Remove logfile for dialup interfaces like pppoe and wwan` +- {vytask}`T2475` `(bug): linting` +- {vytask}`T1820` `(bug): VRRP transition scripts for sync-groups are not supported in VyOS (anymore)` +- {vytask}`T2364` `(default): Add CLI command for mroute` +- {vytask}`T2023` `(feature): Add support for 802.1ae MACsec` + +## 2020-05-20 + +- {vytask}`T2480` `(bug): NAT: after rewrite commit tells that dnat IP address is not locally connected` + +## 2020-05-19 + +- {vytask}`T2481` `(feature): WireGuard: support tunnel via IPv6 underlay` +- {vytask}`T421` `(bug): Add Pv6 prefix delegation support` +- {vytask}`T815` `(feature): Add DHCPv6 server prefix-delegation support` + +## 2020-05-17 + +- {vytask}`T2471` `(feature): PPPoE server: always add AdvAutonomousFlag when IPv6 is configured` +- {vytask}`T2409` `(default): At boot, effective config should not be equal to current config` + +## 2020-05-16 + +- {vytask}`T2466` `(bug): live-build encounters apt dependency problem when building with local packages` +- {vytask}`T2470` `(feature): Update to PowerDNS recursor 4.3` +- {vytask}`T2469` `(feature): Update Linux Kernel to v4.19.123` +- {vytask}`T2198` `(default): Rewrite NAT in new XML/Python style` + +## 2020-05-15 + +- {vytask}`T2449` `(bug): 'ipv6 address autoconf' and 'address dhcpv6' don't work because interfaces have accept_ra=1 (they should have accept_ra=2 when forwarding=1)` + +## 2020-05-14 + +- {vytask}`T2456` `(bug): netflow source-ip cannot be configured` + +## 2020-05-13 + +- {vytask}`T2435` `(bug): Pseudo-ethernet Interfaces Broken` +- {vytask}`T2294` `(bug): ipoe-server broken (jinja2 template issue)` + +## 2020-05-12 + +- {vytask}`T2454` `(feature): Update Linux Kernel to v4.19.122` +- {vytask}`T2392` `(bug): SSTP with ipv6` + +## 2020-05-10 + +- {vytask}`T2445` `(bug): VRF route leaking for ipv4 not working` +- {vytask}`T2372` `(bug): VLAN: error on commit if main interface is disabled` +- {vytask}`T2439` `(bug): Configuration dependency problem, unable to load complex configuration after reboot` + +## 2020-05-09 + +- {vytask}`T2427` `(default): Interface addressing broken since fix for T2372 was merged` +- {vytask}`T2438` `(default): isc-dhcp-server(6).service reports startup success immediately even if dhcpd fails to start up` +- {vytask}`T2367` `(default): Flush addresses from bridge members` + +## 2020-05-08 + +- {vytask}`T2441` `(bug): TZ validator has a parse error` +- {vytask}`T2429` `(bug): Vyos cannot apply VLAN sub interface to bridge` + +## 2020-05-06 + +- {vytask}`T2402` `(bug): Live ISO should warn when configuring that changes won't persist` + +## 2020-05-05 + +- {vytask}`T1899` `(bug): Unionfs metadata folder is copied to the active configuration directory` + +## 2020-05-04 + +- {vytask}`T2412` `(bug): ping flood does not work as unprivileged user` +- {vytask}`T701` `(bug): LTE interface dosen't come up` +- {vytask}`T951` `(bug): command 'isolate-stations true/false' does not make any changes in the hostapd.conf` + +## 2020-05-03 + +- {vytask}`T2420` `(feature): Update Linux Kernel to v4.19.120` +- {vytask}`T2406` `(feature): DHCPv6 CLI improvements` +- {vytask}`T2421` `(feature): Update WireGuard to Debian release 1.0.20200429-2_bpo10+1` + +## 2020-05-02 + +- {vytask}`T2414` `(feature): Improve runtime from Python numeric validator` +- {vytask}`T2413` `(feature): Update Linux Kernel to v4.19.119` + +## 2020-05-01 + +- {vytask}`T2411` `(feature): op-mode: make "monitor traceroute" VRF aware` +- {vytask}`T2347` `(bug): During commit, any script output directed to stdout will contain path` +- {vytask}`T2239` `(default): build-vmware-image script ignores the predefined file path, uses the environment variable unconditionally.` + +## 2020-04-29 + +- {vytask}`T2399` `(bug): op-mode "dhcp client leases" does not return leases` +- {vytask}`T2398` `(bug): op-mode "dhcp client leases interface" completion helper misses interfaces` +- {vytask}`T2394` `(feature): dhcpv6 client does not start` +- {vytask}`T2393` `(feature): dhclient: migrate from SysVinit to systemd` +- {vytask}`T2268` `(bug): DHCPv6 is broken` + +## 2020-04-28 + +- {vytask}`T1227` `(bug): rip PW can't be set at interface config` + +## 2020-04-27 + +- {vytask}`T2373` `(feature): Required auth options for pppoe-server` +- {vytask}`T1381` `(feature): Enable DHCP option 121 processing` +- {vytask}`T2010` `(bug): Reboot at reports wrong time or missing timezone` + +## 2020-04-26 + +- {vytask}`T2386` `(bug): salt: upgrade to 2019.2 packages` +- {vytask}`T2385` `(bug): salt-minion: improve completion helpers` +- {vytask}`T2384` `(bug): salt-minion: log to syslog and remove custom logging option` +- {vytask}`T2383` `(feature): Update Linux Kernel to v4.19.118` +- {vytask}`T2382` `(bug): salt-minion: Throws KeyError on commit` +- {vytask}`T2350` `(bug): Interface geneve conf-mode error` + +## 2020-04-25 + +- {vytask}`T2304` `(feature): "system login" add RADIUS VRF support` +- {vytask}`T1842` `(bug): Equuleus: "reboot at 04:00" command not working` + +## 2020-04-24 + +- {vytask}`T2375` `(feature): WireGuard: throw exception if address and port are not given as both are mandatory` +- {vytask}`T2348` `(bug): On IPv6 address distribution and DHCPv6 bugs` + +## 2020-04-23 + +- {vytask}`T2369` `(feature): VRF: can not leak interface route from default VRf to any other VRF` +- {vytask}`T2368` `(bug): VRF: missing completion helper when leaking to default table` +- {vytask}`T2374` `(bug): Tunnel interface can not be disabled` +- {vytask}`T2362` `(default): IPv6 link-local addresses missing due to EUI64 address code, causing router-advert not to work` +- {vytask}`T2345` `(default): IPv6 router-advert not working` + +## 2020-04-22 + +- {vytask}`T2361` `(bug): Unable to delete VLAN vif interface` +- {vytask}`T2339` `(bug): OpenVPN: IPv4 no longer working after adding IPv6 support` +- {vytask}`T2331` `(bug): VRRP op-mode errors` +- {vytask}`T2320` `(bug): Wireguard creates non-existing interfaces in [op-mode].` +- {vytask}`T2096` `(feature): Provide "generate" and "show" commands via the http API` +- {vytask}`T2351` `(feature): Cleanup PPTP server implementation and CLI commands` + +## 2020-04-21 + +- {vytask}`T2341` `(bug): Pseudo-ethernet Interfaces Not Loaded on Boot` +- {vytask}`T2270` `(bug): using load with scp/sftp and a username and password does not work` +- {vytask}`T2255` `(bug): DNS forwarding op-mode error` +- {vytask}`T1907` `(bug): Traceback on a non-existent interface.` +- {vytask}`T2204` `(feature): Support tunnel source-interface` + +## 2020-04-20 + +- {vytask}`T2335` `(bug): Unable to assign IPv6 from ISP` +- {vytask}`T2317` `(bug): l2tp overwriting ipsec config files` +- {vytask}`T2292` `(bug): Ensure graceful shutdown of vyos-http-api` +- {vytask}`T2344` `(bug): PPPoE server client static IP assignment silently fails` + +## 2020-04-19 + +- {vytask}`T2337` `(default): hw-id gone missing from interfaces after upgrade to 1.3-rolling-202004191028` +- {vytask}`T2340` `(feature): Remove informational "sg" messages from syslog` +- {vytask}`T2338` `(bug): Can't delete static IPv6 route on vrf` +- {vytask}`T2336` `(bug): OpenVPN service fails to start` +- {vytask}`T2308` `(default): openvpn op-mode scripts broken after migrating to systemd service` +- {vytask}`T2185` `(default): Start daemons with systemd units instead of with start-stop-daemon` + +## 2020-04-18 + +- {vytask}`T2318` `(bug): dns-forwarding migration script breaks with invalid interface name` +- {vytask}`T2319` `(feature): Update Linux Kernel to v4.19.116` +- {vytask}`T2314` `(feature): Cleanup PPPoE server implementation and CLI commands` +- {vytask}`T2313` `(bug): Accel-PPP / PPPoEserver raises "Floating point exception" when not all limits are defined` +- {vytask}`T2312` `(feature): Use LED modules to enable more visible feedback on VyOS hardware chassis` +- {vytask}`T2306` `(feature): Add new cipher suites to the WiFi configuration` +- {vytask}`T2286` `(default): IPoE server vulnerability` +- {vytask}`T2224` `(feature): Update Linux Kernel to v4.19.114` +- {vytask}`T2110` `(feature): RADIUS: supply include file for radius config to have a uniform CLI` +- {vytask}`T2324` `(feature): Cleanup IPoE server implementation and CLI commands` + +## 2020-04-17 + +- {vytask}`T2275` `(bug): flow-accounting broken in rolling` +- {vytask}`T2256` `(feature): Accel-ppp op-mode syntax` + +## 2020-04-16 + +- {vytask}`T2295` `(bug): Passwords with Special Characters Broken` +- {vytask}`T2305` `(feature): Add release name to "show version" command` +- {vytask}`T2235` `(default): OpenVPN server client IP doesn't reserve that IP in the pool` +- {vytask}`T149` `(feature): IPv6 support in OpenVPN tunnel` + +## 2020-04-15 + +- {vytask}`T2293` `(bug): OpenVPN: UnboundLocalError after merging server_network PullRequest` +- {vytask}`T2298` `(bug): Errors PDNS with name-server set` + +## 2020-04-14 + +- {vytask}`T2213` `(bug): vyos-1x: WiFi mode ieee80211ac should also activate ieee80211n` + +## 2020-04-13 + +- {vytask}`T2283` `(default): openvpn not starting: ccd path in template not moved to /run/openvpn/ccd` +- {vytask}`T2236` `(bug): DMVPN broken after tunnel rewrite to XML/Python` +- {vytask}`T2284` `(default): Upgrade ddclient to 3.9.1 which also brings systemd files` +- {vytask}`T2282` `(feature): Clarify hw-id in ethernet and wireless interface nodes` +- {vytask}`T611` `` (feature): Static route syntax should reflect `ip` command routing capabilities, if possible. `` + +## 2020-04-12 + +- {vytask}`T2273` `(default): OpenVPN no longer starts in latest rolling, migrate to systemd` +- {vytask}`T2263` `(feature): Reset feature for SSTP sessions` +- {vytask}`T2262` `(bug): Broken reset commands for pptp and l2tp` +- {vytask}`T2031` `(bug): pseudo-ethernet link interface cannot be changed` + +## 2020-04-11 + +- {vytask}`T2264` `(feature): l2tp: cleanup CLI definition` +- {vytask}`T2233` `(bug): Typos in wlanX.cfg` +- {vytask}`T2238` `(bug): After re-writing list_interfaces.py to use Interfaces() pseudo-ethernet is missing` + +## 2020-04-10 + +- {vytask}`T2265` `(feature): DHCP to be an attribute of the class instead of a inheritance` +- {vytask}`T2261` `(bug): "client-config-dir" not being set for openvpn` +- {vytask}`T2248` `(bug): PPPoE Broken in Latest 1.3 Rolling (1.3-rolling-202004070629)` +- {vytask}`T1629` `(bug): IP addresses configured on vif-s interfaces are not added to the system` +- {vytask}`T2266` `(default): openvpn bridged client-server doesn't work (validation error)` +- {vytask}`T2253` `(default): Fix use of cmd in merge config and remote function helpers` + +## 2020-04-09 + +- {vytask}`T2260` `(feature): vxlan, pseudo-ethernet: convert link nodes to source-interface` +- {vytask}`T2172` `(feature): Enable conf VXLAN without remote address` +- {vytask}`T2237` `(bug): l2tp, pptp, pppoe wrong chap-secrets file` + +## 2020-04-08 + +- {vytask}`T2244` `(feature): WireGuard: cleanup Python implementation and reduce amount of boilerplate code` +- {vytask}`T2186` `(feature): Provide more information to the user when a traceback is reported to the user` +- {vytask}`T2246` `(bug): LLDP op-mode error` +- {vytask}`T2240` `(feature): Support for bind vif-c interfaces into VRFs` +- {vytask}`T2160` `(feature): Allow restricting HTTP API to specific virtual hosts` +- {vytask}`T2247` `(feature): WireGuard: add VRF support` + +## 2020-04-05 + +- {vytask}`T2212` `(bug): vyos-1x: WiFi card antenna count not set accordingly` +- {vytask}`T2230` `(feature): Split out inlined Jina2 template to data/templates folder` +- {vytask}`T2206` `(feature): Split WireGuard endpoint into proper host and port nodes` + +## 2020-04-04 + +- {vytask}`T2158` `(bug): Commit fails if ethernet interface doesn't support flow control (pause)` +- {vytask}`T2221` `(bug): Ability to remove a VRF that has a next-hop-vrf as target` +- {vytask}`T2211` `(bug): vyos-1x: VHT channel width not set accordingly` +- {vytask}`T2208` `(bug): vyos-1x: commit on interfaces wireless wlanX capabilities vht link-adaptation (both|unsolicited) fails` +- {vytask}`T2183` `(bug): A number of bugs with wireguard script due to interface rearrangement` +- {vytask}`T2104` `(default): ifconfig.py size` +- {vytask}`T2028` `(feature): Convert "interfaces tunnel" to new XML/Python representation` +- {vytask}`T2219` `(bug): VRF default route of PPPoE and WWAN interfaces do not get added into proper routing table` +- {vytask}`T2222` `(default): openvpn: requires "multihome" option to listen on all addresses with udp protocol` + +## 2020-04-02 + +- {vytask}`T2072` `(bug): Shell autocomplete of option (config node) with quoted value doesn't work` +- {vytask}`T1823` `(feature): l2tpv3 interface migration fails` +- {vytask}`T2202` `(feature): Update PowerDNS recursor to 4.2 series` +- {vytask}`T2200` `(feature): Add VRF support on wirelessmodem interfaces` + +## 2020-03-31 + +- {vytask}`T2166` `(bug): Broken proxy-arp on vif` +- {vytask}`T2180` `(bug): get_config_dict should be independent of CLI edit level` +- {vytask}`T2053` `(default): Update vyos-load-config.py for version string syntax change` +- {vytask}`T2052` `(default): Update vyos-merge-config.py for version string syntax change` +- {vytask}`T2144` `(default): vyos-build: docker: selection of text in the terminal still selects it in vim (mouse isn't completely disabled)` + +## 2020-03-30 + +- {vytask}`T2176` `(default): 'WiFiIf' object has no attribute 'set_state'` +- {vytask}`T2029` `(feature): Switch to new syntax for config file component versions` + +## 2020-03-29 + +- {vytask}`T2178` `(bug): VRF interface don't get removed when VRF is deleted` +- {vytask}`T2170` `(feature): Add ability to create static route from default to VRF` +- {vytask}`T1831` `(feature): Denest IPv6 router-advert from Interfaces to general service` + +## 2020-03-28 + +- {vytask}`T2167` `(bug): vyos.ifconfig.get_mac() broken` +- {vytask}`T2151` `(default): wireless: can't delete interface present in config but not present in system` +- {vytask}`T1988` `(feature): Migrate wirelessmodem to new XML/Python style interface` + +## 2020-03-27 + +- {vytask}`T2164` `(bug): Package libstrongswan-standard-plugins missing from image` +- {vytask}`T2105` `(bug): wireless: not possible to disabled wlan0` +- {vytask}`T2169` `(default): Remove redundant use of show_config in vyos-merge-config` + +## 2020-03-26 + +- {vytask}`T2162` `(default): migration script for router-advert sets link-mtu 0 on bridge interfaces` +- {vytask}`T1735` `(bug): Issue in "show vpn ipsec/ike sa" output with ipsec encryption algorithm aes128gcm128/aes256gcm128/chacha etc` + +## 2020-03-25 + +- {vytask}`T2148` `(default): openvpn: setting "server client" config without "server client ip" results in ValueError: '' does not appear to be an IPv4 or IPv6 address` +- {vytask}`T2146` `(default): openvpn: "delete server client" doesn't delete the corresponding ccd configs` + +## 2020-03-24 + +- {vytask}`T2157` `(default): Organize service https listen-address/listen-port/server-name under 'virtual-host' node` +- {vytask}`T1845` `(bug): syslog host no longer accepts a port` + +## 2020-03-22 + +- {vytask}`T2150` `(feature): SSTP ssl certificates can only be stored in /config/user-data/sstp` +- {vytask}`T2149` `(feature): Update Linux Kernel to v4.19.112` +- {vytask}`T476` `(enhancment): Update the base system to Debian 10 (Buster)` + +## 2020-03-21 + +- {vytask}`T2142` `(bug): vyos-build: Add required packages and step to build-GCE-image script` +- {vytask}`T1870` `(feature): Extend Pipeline scripts to support PullRequests` + +## 2020-03-20 + +- {vytask}`T2006` `(bug): SSTP RADIUS CLI accepts invalid values` +- {vytask}`T2140` `(default): openvpn: tls file check function checkCertHeader returns True even when no match is found` +- {vytask}`T2007` `(feature): SSTP accepts client MTU up to 16384 bytes` +- {vytask}`T2008` `(feature): Adjustment of SSTP CLI to be more consistent to the rest of VyOS` + +## 2020-03-19 + +- {vytask}`T2135` `(bug): Login banner missing spacing now` +- {vytask}`T2132` `(feature): Document kernel boot parameter 'vyos-config-debug'` +- {vytask}`T1744` `(default): Config load fails in ConfigTree with ValueError: Failed to parse config: lexing: empty token` + +## 2020-03-17 + +- {vytask}`T2134` `` (bug): VXLAN: `NameError: name 'config' is not defined` `` + +## 2020-03-16 + +- {vytask}`T2131` `(feature): Improve syslog remote host CLI definition` + +## 2020-03-15 + +- {vytask}`T2122` `(feature): Update Intel out-of-tree drivers to latest version(s)` +- {vytask}`T2121` `(feature): Update Linux Kernel to v4.19.109` +- {vytask}`T2119` `(bug): Error on boot when removing ethernet interface from VM` + +## 2020-03-14 + +- {vytask}`T834` `(feature): New L2TP server implementation based on accel-ppp` + +## 2020-03-13 + +- {vytask}`T1622` `(default): Add failsafe and back trace to boot config loader` + +## 2020-03-11 + +- {vytask}`T1961` `(bug): VXLAN - fails to commit due to non-existent variable, broken MTU` +- {vytask}`T2084` `(default): conntrack-tools package build error for current/equuleus` + +## 2020-03-10 + +- {vytask}`T1331` `(bug): DNS stops working` + +## 2020-03-09 + +- {vytask}`T2111` `(feature): VRF add route leaking support` +- {vytask}`T2109` `(bug): Ping by name broken in VyOS 1.3-rolling-202003080217` +- {vytask}`T2065` `(bug): VyOS 1.3 Don't set daemon in openvpn-{intf}.conf file` +- {vytask}`T31` `(feature): Add VRF support` + +## 2020-03-08 + +- {vytask}`T1954` `` (bug): Having `system login radius` configured causes exponentially long boot times `` +- {vytask}`T1760` `(bug): RADIUS shared secret is not redacted from "show configuration" op mode command` + +## 2020-03-07 + +- {vytask}`T2107` `(bug): Wireless interfaces do not work in station mode without security` + +## 2020-03-05 + +- {vytask}`T2074` `(bug): VyOS docker container: Cannot configure ethernet interface` + +## 2020-03-04 + +- {vytask}`T2098` `(bug): Wrong call to cli-shell-api in generated op-mode templates for path completion helper` + +## 2020-03-03 + +- {vytask}`T2095` `(bug): Copy command errors out` + +## 2020-03-01 + +- {vytask}`T2082` `(bug): WireGuard broken after merging T2057` +- {vytask}`T2089` `(feature): RADIUS: do not query servers when commit is running started from a non RADIUS user` +- {vytask}`T2086` `(feature): Move sudo session open/close log entries to auth.log` + +## 2020-02-29 + +- {vytask}`T2046` `(feature): allowing sub-classes of Interface to redefine how the interface is created` + +## 2020-02-28 + +- {vytask}`T2083` `(default): vyos-build: build-packages fails at mdns-repeater due to wrong branch` +- {vytask}`T2080` `(default): traffic-policy shaper error when setting bandwidth` + +## 2020-02-27 + +- {vytask}`T2075` `(feature): Add support for OpenVPN tls-crypt file option` +- {vytask}`T2068` `(feature): Update Linux Kernel to v4.19.105` +- {vytask}`T1703` `(default): Macvlan PPPoE support` +- {vytask}`T2078` `(feature): Kernel: remove unused RAID functions 5,6,10,jbod,dm` + +## 2020-02-25 + +- {vytask}`T2070` `(feature): Rewrite (dis-)connect op-mode commands in XML and Python` +- {vytask}`T2071` `(feature): Add possibility to temporary disable a RADIUS server used for system login` + +## 2020-02-23 + +- {vytask}`T2055` `(feature): Remove IPv6 router-advert options for PPPoE` +- {vytask}`T1318` `(feature): PPPoE client CLI redesign` + +## 2020-02-22 + +- {vytask}`T2063` `(feature): vyos-salt-minion package is missing from vyos-world` + +## 2020-02-20 + +- {vytask}`T1969` `(default): OSPF with WireGuard cause Route Inactive` + +## 2020-02-18 + +- {vytask}`T2034` `(default): Removal of interfaces loopback lo removed 127.0.0.1 and ::1` + +## 2020-02-17 + +- {vytask}`T2047` `(feature): Update Linux Kernel to v4.19.104` +- {vytask}`T2048` `(bug): ISO boot fails when wireless adapter is present` + +## 2020-02-16 + +- {vytask}`T2043` `(bug): Bond VLANs can't be extended on the fly` +- {vytask}`T2030` `(bug): Bond doesn't survive reboot` +- {vytask}`T1992` `(bug): Adding vlan on a bond resets all BGP connections on same bond` +- {vytask}`T1908` `(feature): Add zone option for Cloudflare DDNS` +- {vytask}`T1246` `(bug): VyOS 1.2.0 "openvpn-options" configuration does not allow quotes in values` + +## 2020-02-15 + +- {vytask}`T2042` `(bug): Error on reboot after deleting "service snmp" and not "service lldp snmp enable"` +- {vytask}`T2041` `(bug): Adding non existent bond interface raises exception` + +## 2020-02-14 + +- {vytask}`T2039` `(bug): Wrong system type displayed in show version` +- {vytask}`T2040` `(bug): vyos-http-api-server should reload Config in all routes` + +## 2020-02-13 + +- {vytask}`T2033` `(feature): Drop vyos-replace package` +- {vytask}`T1635` `(feature): Rewrite interface pseudo-ethernet in new XML/Python style` + +## 2020-02-10 + +- {vytask}`T2024` `(feature): Migrate "system login banner" to XML/Python` + +## 2020-02-09 + +- {vytask}`T2022` `(bug): When RADIUS config is active, local logins won't work` +- {vytask}`T2020` `(default): Unable to log in after upgrade to 1.3-rolling-202002080217` +- {vytask}`T1931` `(bug): Enabling SNMP commit error` + +## 2020-02-05 + +- {vytask}`T1948` `(bug): RADIUS login broken in 1.3` +- {vytask}`T1990` `(feature): Migrate "system login" to XML/Python representation` +- {vytask}`T1585` `(default): Add letsencrypt/certbot support for 'service https'` + +## 2020-02-04 + +- {vytask}`T1965` `(bug): VyOS-1.3: ping no longer supports specifying interface or source` + +## 2020-02-02 + +- {vytask}`T2011` `(feature): Update Linux Kernel to v4.19.101` +- {vytask}`T640` `(bug): Images no longer work when built without "recommended" packages` + +## 2020-02-01 + +- {vytask}`T2009` `(bug): Ethernet Interface always stays down` +- {vytask}`T1989` `(bug): conf.get_config_dict() throws exception` + +## 2020-01-31 + +- {vytask}`T1768` `(bug): PPtP - vyos.config rewrite` +- {vytask}`T2002` `(bug): VLAN interfaces try to be enabled even if parent interface is A/D` + +## 2020-01-30 + +- {vytask}`T1994` `(default): lldpd not bound to specified interfaces - Fix jinja template` +- {vytask}`T1896` `(enhancment): Remove LLDP-MED civic_based location information` +- {vytask}`T1724` `(feature): wireguard - add endpoint check in verify()` + +## 2020-01-29 + +- {vytask}`T1996` `(feature): Update Linux Kernel to 4.19.99` +- {vytask}`T1862` `(default): Use regex pattern \s+ to split strings on whitespace in Python 3.7` +- {vytask}`T1755` `(bug): Python KeyError exceptions raised with 'show vpn ipsec sa' command under use of certain IPSEC cipher suites` +- {vytask}`T1747` `(bug): L2TP breaks after upgrading to VyOS 1.2-rolling-201910180117 [issue report and proposed solution]` +- {vytask}`T1664` `(bug): Ipoe with bond per vlan don't work` +- {vytask}`T1895` `(feature): There is not restriction on selection of syslog facility` +- {vytask}`T1670` `(feature): OpenVPN option for tls-auth` + +## 2020-01-26 + +- {vytask}`T1937` `(bug): snmpd throwing a tremendous amount of errors` +- {vytask}`T1767` `(bug): IPoE - vyos.config rewrite` +- {vytask}`T1765` `(bug): wireguard - vyos.config rewrite` + +## 2020-01-24 + +- {vytask}`T1975` `(bug): OpenVPN tap devices won't come up automatically` + +## 2020-01-23 + +- {vytask}`T1766` `(bug): service-pppoe - vyos.config rewrite` + +## 2020-01-21 + +- {vytask}`T1784` `(bug): DMVPN with IPSec does not work in HUB mode` +- {vytask}`T1977` `(bug): webproxy error on fresh install` + +## 2020-01-18 + +- {vytask}`T1830` `(feature): 1.3-rolling boots to GRUB prompt post-install on UEFI systems` +- {vytask}`T1940` `(bug): EFI Fresh Install fails to boot, 4K Sector Drives Fail to boot EFI` + +## 2020-01-16 + +- {vytask}`T1880` `(default): "A stop job is running for live-tools - System Support Scripts" hangs, times out when shutting down equuleus live iso` + +## 2020-01-15 + +- {vytask}`T1959` `(bug): Error message when adding IPSec VPN` + +## 2020-01-09 + +- {vytask}`T1955` `(feature): snmp - cli config val_help missing` +- {vytask}`T1813` `(bug): error in generated /etc/hosts file` + +## 2020-01-08 + +- {vytask}`T1946` `(bug): Recovery ifname for PPtP remote-access` + +## 2020-01-03 + +- {vytask}`T1939` `(feature): Provide abstraction for interface "ip" options` + +## 2020-01-01 + +- {vytask}`T1779` `(bug): Tunnel interfaces aren't suggested as being available for bridging` + +## 2019-12-31 + +- {vytask}`T1654` `(bug): sFlow: multiple "sflow server" not work, and "disable-imt" could break configuration` +- {vytask}`T1923` `(feature): Migrate L2TPv3 interface to XML/Python` + +## 2019-12-30 + +- {vytask}`T1920` `(bug): beep: Error: Running under sudo, which is not supported for security reasons.` +- {vytask}`T1918` `(bug): l2tp / ipsec config broken in latest daily` +- {vytask}`T1897` `(bug): IPSec - 1.2 to 1.3 migration failed` +- {vytask}`T1921` `(bug): snmp: VyOS options no longer recognized` +- {vytask}`T1922` `(feature): Add VXLAN IPv6 support` +- {vytask}`T1919` `(feature): Migrate "system options" to XML/Python representation` + +## 2019-12-28 + +- {vytask}`T1916` `(feature): Update Linux Kernel to v4.19.91` +- {vytask}`T1915` `(bug): Remove "system ipv6 blacklist" option` +- {vytask}`T1912` `(feature): Migrate "system (ip|ipv6)" to XML/Python representation` + +## 2019-12-27 + +- {vytask}`T1910` `(bug): Invalid parmissions on latest 1.3 rolling ISO images` + +## 2019-12-26 + +- {vytask}`T1794` `(bug): Interface description can't contain a colon` +- {vytask}`T1906` `(feature): Migrate "system time-zone" configuration to XML/Python` + +## 2019-12-23 + +- {vytask}`T1898` `(enhancment): Support multiple IPv4/IPv6 LLDP management addresses` +- {vytask}`T1878` `(bug): accel-ppp: pppoe single-session option implementation` + +## 2019-12-22 + +- {vytask}`T393` `(enhancment): Migrate vyatta-lldpd to vyos-1x` + +## 2019-12-20 + +- {vytask}`T1892` `(default): vyos-build: Do not install recommends in docker image [enhancement]` +- {vytask}`T1411` `(enhancment): equuleus: buster: vyatta-ravpn: libfreeradius-client2 is missing in buster` + +## 2019-12-19 + +- {vytask}`T1873` `(default): DHCP server fails to start due to a change in isc-dhcp-server init scripts` + +## 2019-12-18 + +- {vytask}`T1889` `(bug): Error building docker build image` +- {vytask}`T1132` `(default): Build on Debian Buster` + +## 2019-12-17 + +- {vytask}`T1886` `(feature): Update Linux Kernel to v4.19.89` +- {vytask}`T1887` `(feature): Update WireGuard to Debian release 0.0.20191212-1` + +## 2019-12-13 + +- {vytask}`T1861` `(default): hosts lost after modified static-host-mapping` + +## 2019-12-10 + +- {vytask}`T1843` `(feature): Add GCC preprocessor support for XML files` + +## 2019-12-08 + +- {vytask}`T1566` `(feature): Extend L2TP/IPSec server with IPv6` + +## 2019-12-07 + +- {vytask}`T1714` `(bug): Disable DHCP Nameservers Not Working` + +## 2019-12-06 + +- {vytask}`T1860` `(feature): Update WireGuard to Debian release 0.0.20191127-2` +- {vytask}`T1859` `(feature): Update Linux Kernel to v4.19.88` +- {vytask}`T1854` `(bug): Dynamic DNS configuration cannot be deleted` +- {vytask}`T1849` `(bug): DHCPv6 client does not start` +- {vytask}`T1169` `(bug): LLDP potentially broken` +- {vytask}`T586` `(bug): Cannot add ethernet vif-s vif-c interface to bridge-group` + +## 2019-12-05 + +- {vytask}`T1847` `(bug): set_level incorrectly handles path given as empty string` + +## 2019-12-04 + +- {vytask}`T1787` `(default): Failed config migration from V1.2.3 to 1.2-rolling-201911030217` +- {vytask}`T1212` `(bug): IPSec Tunnel to Cisco ASA drops reliably after 4.2GB transferred` +- {vytask}`T1704` `(feature): OpenVPN - Add support for ncp-ciphers` + +## 2019-12-03 + +- {vytask}`T1782` `(bug): pppoe0: showing as "Coming up"` +- {vytask}`T1801` `(bug): Unescaped backslashes in config values cause configuration failure` + +## 2019-12-02 + +- {vytask}`T1840` `(bug): PPPoE doesn't not rename pppX to pppoeX` + +## 2019-11-25 + +- {vytask}`T1824` `(bug): Permission denied: '/opt/vyatta/etc/config/vyos-migrate.log'` + +## 2019-11-24 + +- {vytask}`T1673` `(bug): vif bridge-group not migrated to bridge member interface` +- {vytask}`T1799` `(feature): Add support for GENEVE (Generic Network Virtualization Encapsulation)` + +## 2019-11-23 + +- {vytask}`T1627` `(feature): Rewrite wireless interface in new style XML syntax` + +## 2019-11-21 + +- {vytask}`T1818` `(default): Print name of migration script on failure` +- {vytask}`T1814` `(default): Add log of migration scripts run during config migration` + +## 2019-11-14 + +- {vytask}`T1710` `(default): [equuleus] buster: add patch to fix live-build missing key error` +- {vytask}`T1804` `(default): Add python3-psutil to docker image` +- {vytask}`T1736` `(default): Decide on best practice for patching live-team packages for VyOS build system` +- {vytask}`T1424` `(default): Rewrite the config load script` + +## 2019-11-11 + +- {vytask}`T1793` `(feature): Editing description on an interface causes BGP sessions to reset on commit` + +## 2019-11-10 + +- {vytask}`T1791` `(feature): Update Linux Kernel to 4.19.82` + +## 2019-11-08 + +- {vytask}`T1789` `(bug): ddclient not working with generated RFC2136 / nsupdate config` + +## 2019-11-03 + +- {vytask}`T1777` `(bug): Bonding interface MAC address mismatch after reboot` +- {vytask}`T1752` `(bug): PPPoE does not automatically start on boot` + +## 2019-11-02 + +- {vytask}`T1783` `(bug): Interface can't unpin from bridge` + +## 2019-10-22 + +- {vytask}`T1756` `(feature): Modify output to be more useful - Wireguard` + +## 2019-10-21 + +- {vytask}`T1741` `(feature): Add system wide proxy setting` + +## 2019-10-19 + +- {vytask}`T1746` `(bug): 201910180117 fails startup with 'Permission Denied' errors` +- {vytask}`T1743` `(default): equuleus: remove references to SSH key type "rsa1" deprecated in Debian Buster` + +## 2019-10-18 + +- {vytask}`T1712` `(default): DHCP client sometimes doesn't start` +- {vytask}`T1604` `(enhancment): equuleus: buster: vbash: tab completion breaks` + +## 2019-10-11 + +- {vytask}`T1723` `(bug): wireguard - Interface wg01 could not be brought up in time` + +## 2019-10-09 + +- {vytask}`T1719` `(feature): ssh deprecated options` +- {vytask}`T1718` `(bug): ISO check in /opt/vyatta/sbin/install-image faulty` +- {vytask}`T1682` `(feature): Migrate to new Jenkins Pipeline script` + +## 2019-10-08 + +- {vytask}`T1717` `(bug): disable multiple daemons to autostart at boot` + +## 2019-10-06 + +- {vytask}`T1713` `(feature): Remove deprecated packages no longer required after migration to Accel-PPP` + +## 2019-10-03 + +- {vytask}`T1689` `(feature): "reset openvpn" op-mode command should terminate and restart OpenVPN process` + +## 2019-10-01 + +- {vytask}`T1706` `(bug): wireguard broken in latest rolling` + +## 2019-09-30 + +- {vytask}`T1688` `(feature): OpenVPN - Add new cipher aes-(128|192|256)-gcm` + +## 2019-09-28 + +- {vytask}`T1696` `(bug): NTP - Tests fail when building vyos-1x` +- {vytask}`T1512` `(bug): vyos 1.2 openvpn client names with spaces created incorrectly` + +## 2019-09-27 + +- {vytask}`T1681` `(feature): cleanup wireguard code since tagnodes are now visible` +- {vytask}`T1695` `(bug): Syntax error in interface-dummy.py` + +## 2019-09-26 + +- {vytask}`T1692` `(bug): ipoe-server verify function error` +- {vytask}`T1691` `(bug): OpenVPN - Commiting config when OpenVPN peer/server not available makes commit hang` +- {vytask}`T1690` `(feature): restart op-mode commands for 'service (pppoe|ipoe)-server'` + +## 2019-09-25 + +- {vytask}`T1672` `(bug): Wireguard keys not automatically moved` + +## 2019-09-23 + +- {vytask}`T1679` `(bug): during bootup: invalid literal for int() with base 10` +- {vytask}`T1680` `(feature): DHCP client does not release IP address on exit/deletion` + +## 2019-09-21 + +- {vytask}`T1676` `(default): [equuleus] buster: update GRUB boot parameters during upgrade` +- {vytask}`T1637` `(feature): Rewrite ethernet interface in new style XML syntax` +- {vytask}`T1675` `(feature): OpenVPN - Specify minimum TLS version` + +## 2019-09-20 + +- {vytask}`T1602` `(default): equuleus: buster: add live build apt options for choosing vyos packages` + +## 2019-09-19 + +- {vytask}`T1666` `(feature): Deleting a bond will place member interfaces into A/D state` + +## 2019-09-17 + +- {vytask}`T239` `(bug): Improve documentation for the firewall all-ping setting` + +## 2019-09-16 + +- {vytask}`T1040` `(default): rc.local is executed too early` + +## 2019-09-15 + +- {vytask}`T1662` `(default): openvpn: 'show openvpn client' error` +- {vytask}`T1661` `(default): openvpn: wrong checking for existence cert files` +- {vytask}`T1630` `(bug): OpenVPN after changing it from root to nobody (unprivileged user) cant add routes` + +## 2019-09-13 + +- {vytask}`T1660` `(bug): Bonding dont’t work on VyOS 1.2-rolling-201909120338` +- {vytask}`T1655` `(enhancment): equuleus: buster: arm: vyos-accel-ppp build failes because of filename hardcoded as x86_64 in debian/rules` + +## 2019-09-12 + +- {vytask}`T1572` `(feature): Wireguard keyPair per interface` +- {vytask}`T1545` `(bug): IPSEC vti issue` + +## 2019-09-10 + +- {vytask}`T1650` `(feature): implement wireguard default key removal` +- {vytask}`T1649` `(feature): feature documentation different keypairs per interface` +- {vytask}`T1648` `(feature): add cli command 'delete wireguard named-key <key>'` + +## 2019-09-09 + +- {vytask}`T1639` `(bug): wireguard pubkey change error` + +## 2019-09-07 + +- {vytask}`T1640` `(feature): Update Linux Kernel to v4.19.70` + +## 2019-09-06 + +- {vytask}`T1624` `(bug): Failed to set up config session` +- {vytask}`T1636` `(feature): Rewrite VXLAN in new style XML/Python` +- {vytask}`T1479` `(bug): libvyosconfig error reporting doesn't include line numbers` +- {vytask}`T808` `(feature): replace lighthttpd with nginx` +- {vytask}`T1478` `(bug): libvyosconfig parser does not support escaped quotes inside single-quoted strings` + +## 2019-09-04 + +- {vytask}`T1632` `(bug): OpenVPN 'push' options with quotes` +- {vytask}`T1631` `(bug): Multiple push-route options cause error generating openvpn configuration` +- {vytask}`T1557` `(feature): Create generic abstraction for configuring interfaces e.g. IP address` +- {vytask}`T1628` `(feature): Adopt WireGuard configuration script to new vyos.ifconfig class` +- {vytask}`T1614` `(feature): Rewrite bonding interface in new style XML syntax` + +## 2019-09-02 + +- {vytask}`T1621` `(default): Rewrite the rest of trivial vyatta-op commands to new syntax` + +## 2019-08-31 + +- {vytask}`T1456` `(bug): Port group cannot be configured if the same port is configured as standalone and inside a range` + +## 2019-08-28 + +- {vytask}`T1615` `(feature): After migration to pyroute2 the address DHCP statement is no longer covered` + +## 2019-08-27 + +- {vytask}`T1617` `(default): OpenVPN push route failure` +- {vytask}`T1250` `(bug): FRR not setting default gateway from DHCP` + +## 2019-08-26 + +- {vytask}`T1591` `(bug): OpenVPN "run show openvpn client status" does not work` +- {vytask}`T1608` `(feature): bridge: Bridge adding non existing interfaces is allowed but does not work` +- {vytask}`T1548` `(feature): Rewrite OpenVPN interface/op-commands in new style XML/Python` +- {vytask}`T1607` `(default): Convert 'reset conntrack' and 'reset ip[v6] cache' operations from vyatta-op to new syntax` + +## 2019-08-25 + +- {vytask}`T1611` `(default): Migration to latest rolling fails with vyos.configtree.ConfigTreeError: Path [b'interfaces bridge br0 igmp-snooping querier'] doesn't exist` + +## 2019-08-23 + +- {vytask}`T1606` `(bug): Rolling release no longer boots after adding hostname daemon` + +## 2019-08-21 + +- {vytask}`T1601` `(feature): Rewrite loopback interface type with new style XML/Python interface` +- {vytask}`T1596` `(default): Convert 'telnet' and 'traceroute' vyatta-op commands to new syntax` + +## 2019-08-20 + +- {vytask}`T1595` `(feature): Migrate deprecated "service dns forwarding listen-on" to listen-address` + +## 2019-08-19 + +- {vytask}`T1580` `(feature): Rewrite dummy interface type with new style XML/Python interface` +- {vytask}`T1590` `(default): Convert 'show system' operations from vyatta-op to python/xml syntax` + +## 2019-08-17 + +- {vytask}`T1592` `(feature): Update Linux Kernel to v4.19.67` + +## 2019-08-15 + +- {vytask}`T1584` `(default): equuleus: buster: add consistent grub options for predictable interface names` + +## 2019-08-13 + +- {vytask}`T1556` `(feature): Rewrite Bridge in new style XML syntax` + +## 2019-08-09 + +- {vytask}`T1569` `(feature): interfaceconfig class documetation` + +## 2019-08-05 + +- {vytask}`T1562` `(feature): Change version scheme on current branch used for rolling releases` + +## 2019-08-04 + +- {vytask}`T1561` `(bug): VyOS rolling ISO cluttered with vyatta-ravpn Git Repo` + +## 2019-08-02 + +- {vytask}`T853` `(feature): Add SSTP server support` +- {vytask}`T742` `(feature): Replace poptop and xl2tpd with accel-ppp` + +## 2019-08-01 + +- {vytask}`T1544` `(feature): L2TP documentation` + +## 2019-07-31 + +- {vytask}`T1552` `(feature): accel-ppp: SSTP documentation` +- {vytask}`T1553` `(default): equuleus: buster: add 'noautologin' to boot parameters` + +## 2019-07-29 + +- {vytask}`T1532` `(default): [equuleus] buster: GPG error on vyos package repository` + +## 2019-07-28 + +- {vytask}`T1547` `(feature): accel-ppp/L2TP restructure CLI` +- {vytask}`T1546` `(bug): accel-ppp/L2TP radius-source address is not honored` + +## 2019-07-23 + +- {vytask}`T1533` `(bug): Rolling builds broken!` +- {vytask}`T1489` `(feature): Add vlan_mon usage at Accel` + +## 2019-07-22 + +- {vytask}`T1435` `(enhancment): Make ip-address [OPTIONAL] (in dhcp-server -> static-mapping) to cope with "unfriendly" client-hostnames of IoT-Devices` + +## 2019-07-21 + +- {vytask}`T823` `(feature): Rewrite DHCP op mode in the new style` + +## 2019-07-18 + +- {vytask}`T1497` `(bug): "set system name-server" generates invalid/incorrect resolv.conf` +- {vytask}`T533` `(feature): Support for PPPoE MTU greater than 1492` + +## 2019-07-08 + +- {vytask}`T1510` `(feature): [IPoE] vlan-mon option implementation` +- {vytask}`T1508` `(feature): [pppoe] migration script for service pppoe-server interface` +- {vytask}`T1494` `(feature): accel-ppp: IPoE update documentation` +- {vytask}`T989` `(feature): Add support for IPoE server` + +## 2019-07-03 + +- {vytask}`T1502` `(feature): Add build sanity checking tools to the dev builds` + +## 2019-07-02 + +- {vytask}`T1099` `(default): Openvpn: use config files instead of one long command.` +- {vytask}`T1495` `(feature): accel-ppp: IPoE implement IPv6 PD` + +## 2019-07-01 + +- {vytask}`T1498` `(bug): Nameservers are not propagated into resolv.conf` + +## 2019-06-24 + +- {vytask}`T1482` `(feature): Add OpenVPN SHA384 hashing algorithm` + +## 2019-06-23 + +- {vytask}`T1476` `(bug): Update PowerDNS recursor to 4.2 series` + +## 2019-06-22 + +- {vytask}`T1313` `(feature): Add support for reusable build flavours` +- {vytask}`T1202` `` (bug): Add `hvinfo` to the packages directory `` + +## 2019-06-20 + +- {vytask}`T1413` `(enhancment): equuleus: buster: vyos-xe-guest-utilities is not installable and breaks live-build` +- {vytask}`T1412` `(enhancment): equuleus: buster: vyos-netplug is not installable and breaks live-build` + +## 2019-06-19 + +- {vytask}`T1334` `(feature): Migration script runner rewrite` +- {vytask}`T1327` `(bug): Set the serial console speed to 115200 by default` + +## 2019-06-18 + +- {vytask}`T1451` `(bug): Intel e1000e driver missing in lates rolling release` + +## 2019-06-17 + +- {vytask}`T1408` `(feature): pppoe-server - implement local-ipv6 for pure IPv6 based deployments` + +## 2019-06-12 + +- {vytask}`T1397` `(default): Rewrite the config merge script` + +## 2019-06-05 + +- {vytask}`T1426` `(default): Update the script that checks conntrack hash-size on reboot` + +## 2019-06-03 + +- {vytask}`T1423` `(default): When merging remote config files, create known_hosts file if not present.` + +## 2019-05-28 + +- {vytask}`T1410` `(feature): Upgrade Linux Kernel to 4.19.46` + +## 2019-05-26 + +- {vytask}`T1404` `(feature): Update iproute2 package to 4.19` + +## 2019-05-24 + +- {vytask}`T1407` `(bug): pppoe IPv6 PD documention by practical example` + +## 2019-05-23 + +- {vytask}`T1402` `(feature): Update Linux Kernel to 4.19.45` + +## 2019-05-22 + +- {vytask}`T1399` `(bug): accel-ppp kernel modules missing in rolling build 20190522` +- {vytask}`T1393` `(bug): pppoe IPv6 pool doesn't work` + +## 2019-05-21 + +- {vytask}`T592` `` (bug): lldpcli: unknown command from argument 1: `#` `` + +## 2019-05-16 + +- {vytask}`T1267` `(feature): FRR: Add interface name for static routes` +- {vytask}`T1148` `(bug): epa2 BGP peers initiate before config is fully loaded, routes leak.` + +## 2019-05-06 + +- {vytask}`T1368` `(feature): Enable MPLS support in Linux Kernel` + +## 2019-05-04 + +- {vytask}`T1365` `(bug): Cannot configure syslog on 1.2.0-rolling+201904260337` + +## 2019-04-29 + +- {vytask}`T1352` `(feature): vyos-documentaion: accel-pppoe adding CIDR based IP pool option` + +## 2019-04-21 + +- {vytask}`T1348` `(feature): Upgrade WireGuard to 0.0.20190406-1` +- {vytask}`T1347` `(feature): Upgrade Linux Kernel to 4.19.36` + +## 2019-04-20 + +- {vytask}`T1344` `(feature): Unclutter "system login radius" configuration nodes` + +## 2019-04-19 + +- {vytask}`T1325` `(default): GRE tunnel to Cisco router fails in 1.2.0 - works in 1.1.8` + +## 2019-04-16 + +- {vytask}`T1184` `(feature): wireguard - extend documentation with the show interface wireguard commands` + +## 2019-04-15 + +- {vytask}`T1260` `(feature): VICI-based implementation of "run show vpn ipsec sa"` +- {vytask}`T1248` `(default): Add a function for copying nodes to the vyos.configtree library` + +## 2019-04-05 + +- {vytask}`T1324` `(feature): update documtation for 'set system login user level'` + +## 2019-04-04 + +- {vytask}`T1323` `(feature): migrate operator accounts to admin accounts and remove the option to setup an operator account` + +## 2019-03-20 + +- {vytask}`T405` `(feature): Add binaries for lcdproc` + +## 2019-03-12 + +- {vytask}`T1284` `(feature): accel-ppp: pptp implementation documention` +- {vytask}`T833` `(feature): New PPTP server implementation based on accel-ppp` + +## 2019-02-22 + +- {vytask}`T1257` `(bug): implement 'set system static-host-mapping' in host_name.py and remove old function calls` + +## 2019-02-21 + +- {vytask}`T1214` `` (bug): Add `ipaddrcheck` to the packages directory `` + +## 2019-02-10 + +- {vytask}`T1154` `(default): use of local cache to build iso` + +## 2019-02-09 + +- {vytask}`T1236` `(feature): Update Linux Kernel` diff --git a/docs/changelog/md-1.4.md b/docs/changelog/md-1.4.md new file mode 100644 index 00000000..cd50127e --- /dev/null +++ b/docs/changelog/md-1.4.md @@ -0,0 +1,4457 @@ +# 1.4 Sagitta + +% Please don't add anything by hand. +% This file is managed by the script: +% _ext/releasenotes.py + +## 2024-04-25 + +- {vytask}`T6263` `(bug): Multicast: Could not commit multicast config with multicast join group using source-address` +- {vytask}`T5833` `(bug): Not all AFIs compatible with VRF` + +## 2024-04-24 + +- {vytask}`T6255` `(bug): Static table description should not contain white-space` +- {vytask}`T6226` `` (feature): add HAPROXY `tcp-request content accept` related block to load-balancing reverse proxy config `` +- {vytask}`T6109` `(bug): remote syslog do not get all the logs` +- {vytask}`T6217` `(feature): VRRP contrack-sync script change name of the logger` +- {vytask}`T6244` `(feature): Spacing of "Show System Uptime" hard to parse` + +## 2024-04-23 + +- {vytask}`T6260` `(bug): image-tools: remove failed image directory if 'No space left on device' error` +- {vytask}`T6261` `(default): Typo in op_mode connect_disconnect print statement for check_ppp_running` +- {vytask}`T6237` `(feature): IPSec remote access VPN: ability to set EAP ID of clients` + +## 2024-04-22 + +- {vytask}`T5996` `(bug): unescape backslashes for config save, compare commands` +- {vytask}`T6103` `(bug): DHCP-server bootfile-name double slash syntax weird behaviour` +- {vytask}`T6080` `(default): Default NTP server settings` +- {vytask}`T5986` `(bug): Container: Error on commit when environment variable value contains \n line break` + +## 2024-04-21 + +- {vytask}`T6191` `(bug): Policy Route TCP-MSS Behavior Different from 1.3.x` +- {vytask}`T5535` `(feature): disable-directed-broadcast should be moved to firewall global-options` + +## 2024-04-20 + +- {vytask}`T6252` `(bug): gre tunnel - doesn't allow configure jumbo frame more than 8024` + +## 2024-04-19 + +- {vytask}`T6221` `(bug): Enabling VRF breaks connectivity` +- {vytask}`T6035` `(bug): QoS policy shaper queue-type random-detect requires limit avpkt` +- {vytask}`T6246` `(feature): Enable basic haproxy http-check configuration options` +- {vytask}`T6242` `(feature): Loadbalancer reverse-proxy: SSL backend skip CA certificate verification` + +## 2024-04-17 + +- {vytask}`T6168` `(bug): add system image does not set default boot to current console type in compatibility mode` +- {vytask}`T6243` `(bug): Update vyos-http-api-tools for package idna security advisory` +- {vytask}`T6154` `(enhancment): Installer should ask for password twice` +- {vytask}`T5966` `(default): Adjust dynamic dns configuration address subpath to be more intuitive and other op-mode adjustments` +- {vytask}`T5723` `(default): mdns repeater: Always reload systemd daemon before applying changes` +- {vytask}`T5722` `(bug): Failing to add route in failover if gateway not in the same interface network` +- {vytask}`T5612` `(default): Miscellaneous improvements and fixes for dynamic DNS configuration` +- {vytask}`T5574` `(default): Support per-service cache management for dynamic dns providers` +- {vytask}`T5360` `(bug): ddclient generating abuse` + +## 2024-04-15 + +- {vytask}`T6100` `(bug): NAT config migration error in 1.4.0-epa1 if invalid address/network defined in 1.3.6 version` +- {vytask}`T5734` `(bug): OpenVPN server dh-params that are not in PKI error` + +## 2024-04-14 + +- {vytask}`T6210` `(feature): Add container ability to configure capability sys-nice` + +## 2024-04-13 + +- {vytask}`T6173` `(bug): Build Causes Errors When "--version" Contains Slashes ("/")` +- {vytask}`T2518` `(feature): Support NAT for ipv6(NPT)` +- {vytask}`T6238` `(default): vyos-build Check pull request title requires the python script` +- {vytask}`T6235` `(default): Git check PR status: conflicts and resolution` + +## 2024-04-12 + +- {vytask}`T5872` `(default): ipsec remote access VPN: support dhcp-interface` +- {vytask}`T6216` `(bug): Upgrade error from 1.3 to 1.4 - Firewall using character '+'` +- {vytask}`T6214` `(bug): Error when using some constraints` +- {vytask}`T6213` `(bug): Firewall group constraints` +- {vytask}`T6148` `(bug): Reset vpn ipsec command breaks tunnel and does not reset SAs that are down` +- {vytask}`T1487` `(default): DNS (pdns_recursor) stats logs not saved to disk` +- {vytask}`T6222` `(bug): VRRP rfc3768-compatibility not working correctly when resulting interface name is over 15 characters` +- {vytask}`T6218` `(bug): Container network interface in VRF fails to generate IPv6 link-local address` +- {vytask}`T5959` `(default): Streamline dns forwarding service` +- {vytask}`T5846` `(default): Refactor and simplify DUID definition in conf-mode` +- {vytask}`T5631` `(feature): Ability to export the current configuration in JSON format` +- {vytask}`T5615` `(default): Narrow down spurious name conflict with mdns` +- {vytask}`T5530` `(default): Add LFA to IS-IS` +- {vytask}`T5195` `(default): Break up the vyos.util module` +- {vytask}`T5124` `(bug): Python3 deprecation distutils.version import LooseVersion` +- {vytask}`T1871` `(feature): add MTU option when configure limiter traffic-policy` +- {vytask}`T874` `(feature): Support for Two Factor Authentication for CLI access via Google Authenticator/OTP` +- {vytask}`T6204` `(default): Remove shebang lines from Python modules` +- {vytask}`T6166` `(bug): Tech support generation error for custom output location` +- {vytask}`T6062` `(feature): container: add support for image manipulation based on tag name` +- {vytask}`T5877` `(default): Reduce unnecessary nesting in system domain-search path and improve smoketest` +- {vytask}`T5871` `(default): ipsec remote access VPN: specify "cacerts" to disambiguate mulitple remote access configurations` +- {vytask}`T5870` `(default): ipsec remote access VPN: add x509 ("pubkey") authentication` +- {vytask}`T5772` `(default): Require HTTPS API server configurations to include at least one key if key-based auth is used` +- {vytask}`T5447` `(feature): Allow static MACsec keys with peers` +- {vytask}`T4221` `(default): Add a template filter for converting scalars to single-item lists` +- {vytask}`T3766` `(feature): containers: Expanding options for networking and building containers` + +## 2024-04-11 + +- {vytask}`T4516` `(feature): Rewrite system image manipulation tools in Python` +- {vytask}`T4548` `(feature): GRUB loader configuration rework` +- {vytask}`T3774` `(bug): atop logs are not limited in size` +- {vytask}`T3574` `(default): Add constraintGroup for combining validators with logical AND` +- {vytask}`T3474` `(default): Revisit storing syntax version of interface definitions in XML file` +- {vytask}`T160` `(feature): Support NAT64` +- {vytask}`T6228` `(bug): Cleanup of not existing units` + +## 2024-04-10 + +- {vytask}`T6207` `(bug): image-tools: restore ability to copy config.boot.default on image install` +- {vytask}`T5750` `(bug): Upgrade from 1.3.4 to 1.4 Rolling fails QoS` +- {vytask}`T5858` `(bug): Show conntrack statistics formatting is all over the place` +- {vytask}`T4734` `(feature): Feature Request: openvpn: add OTP 2FA support` + +## 2024-04-09 + +- {vytask}`T3409` `(feature): Add back TCP-MSS Clamp to PMTU` +- {vytask}`T6121` `(feature): Extend service config-sync for sections vpn, policy, vrf` + +## 2024-04-08 + +- {vytask}`T6197` `(bug): IPoE-server interface client-subnet looks broken or works with the wrong logic` +- {vytask}`T6196` `(bug): Route-map and summary-only do not work in BGP aggregation at the same time` +- {vytask}`T6068` `(feature): dhcp server: allow switching between load-balanced and hotspare mode` + +## 2024-04-07 + +- {vytask}`T6205` `(bug): ipoe: error in migration script logic while renaming mac-address to mac node` +- {vytask}`T6039` `(bug): cloud-init DNS search-domain causes configuration migration/validation error` +- {vytask}`T5862` `(bug): Default MTU is not acceptable in some environments` +- {vytask}`T6208` `(feature): container: rename "cap-add" CLI node to "capability"` +- {vytask}`T6188` `(feature): Add Firewall Rule Description to "show firewall" commands` +- {vytask}`T1244` `(default): Support for StartupResync in conntrackd` + +## 2024-04-06 + +- {vytask}`T6203` `(enhancment): Remove obsoleted xml lib` +- {vytask}`T6202` `(bug): Multi-Protocol BGP is broken by 6PE patch in upstream FRR 9.1` + +## 2024-04-05 + +- {vytask}`T6089` `(bug): [1.3.6->1.4.0-epa1 Migration] "ospf passive-interface default" incorrectly added` +- {vytask}`T2590` `(bug): DHCPv6 not updating nameservers and search domains since replacing isc-dhcp-client with WIDE dhcp6c` +- {vytask}`T6199` `(feature): spring cleaning - drop unused Python imports` + +## 2024-04-04 + +- {vytask}`T6119` `(default): Use a compliant TOML parser` +- {vytask}`T6171` `(feature): dhcp server fail-over - Rename fail-over node` +- {vytask}`T6115` `(bug): Build from Git tags fail` +- {vytask}`T5122` `(feature): Move "archive-areas" to defaults.toml to support "non-free-firmware" repository` +- {vytask}`T5121` `(bug): Incorrect "architecture" config loaded` +- {vytask}`T4951` `(default): Add an op mode exception for cases when operations fail due to insufficient system resources` +- {vytask}`T4883` `(default): Add a description field for routing tables` +- {vytask}`T4796` `(bug): build-vyos-image ignores multiple options` +- {vytask}`T4795` `(feature): Cleanup custom python validators` +- {vytask}`T4761` `(default): Add a generic URL validator` +- {vytask}`T3843` `(bug): l2tp configuration not cleared after delete` +- {vytask}`T3681` `(default): The VMware Tools resume script did not run successfully in this virtual machine.` +- {vytask}`T1991` `(feature): Rework time services` +- {vytask}`T5711` `(default): Put the version data file inside the ISO image` +- {vytask}`T5672` `(default): Remove the old-style command definition importer` +- {vytask}`T5639` `(default): Group vyos-1x dependencies by their VyOS components and specify their purpose` +- {vytask}`T5638` `(default): Add support for requiring numeric values to be ranges rather than single numbers` +- {vytask}`T5634` `(default): Remove support for Blowfish and DES from OpenVPN` +- {vytask}`T5605` `(default): Do not generate keysize option in OpenVPN configs` +- {vytask}`T5582` `(default): Add a command to force NTP sync` +- {vytask}`T5449` `(default): Add options for TCP MSS probing` +- {vytask}`T4440` `(default): Add OCI compliant image labels to vyos-build and vyos containers` +- {vytask}`T671` `(enhancment): Identify and remove dead code` +- {vytask}`T5109` `(feature): Improve OCaml XML validator` +- {vytask}`T1449` `(feature): Add opportunity to include custom default configs (few) at building` + +## 2024-04-03 + +- {vytask}`T6198` `(feature): configverify: add common helper for PKI certificate validation` +- {vytask}`T6192` `(feature): Multi VRF support for SSH` + +## 2024-04-02 + +- {vytask}`T6167` `(bug): VNI not set on VRF after reboot` +- {vytask}`T6151` `(default): BGP VRF - Route-leaking not work when the next-hop is a recursive route.` +- {vytask}`T6033` `(bug): hsflowd fails to start when using a tunnel interface` + +## 2024-04-01 + +- {vytask}`T6195` `(feature): dropbear: package upgrade 2022.83-1 -> 2022.83-1+deb12u1` +- {vytask}`T6193` `(bug): dhcp-client: invalid warning "is not a DHCP interface but uses DHCP name-server option" for VLAN interfaces` +- {vytask}`T6178` `(bug): Reverse-proxy should check that certificate exists during commit` + +## 2024-03-31 + +- {vytask}`T6186` `(bug): Fix regression in 'set system image default-boot'` +- {vytask}`T5832` `(feature): Keepalived: Allow using the 'dev' statement on excluded-addresses` + +## 2024-03-28 + +- {vytask}`T6147` `(bug): Conntrack not working as expected with global state-policy` +- {vytask}`T6175` `(bug): op-mode: "renew dhcp interface <name>" does not check if it's an actual DHCP interface` + +## 2024-03-26 + +- {vytask}`T6066` `(bug): Setting same network in different ospf area will raise exception` + +## 2024-03-25 + +- {vytask}`T6145` `(bug): Service config-sync does not rely on priorities but must` + +## 2024-03-24 + +- {vytask}`T6161` `(feature): Output container images as JSON` +- {vytask}`T6165` `(bug): grub: vyos-grub-update failed to start on "slow" systems` +- {vytask}`T6085` `(bug): VTI interfaces are in UP state by default` +- {vytask}`T6152` `(bug): Kernel panic for ZimaBoard 232` + +## 2024-03-23 + +- {vytask}`T6160` `(bug): isis: NameError: name 'process' is not defined` +- {vytask}`T6131` `(bug): Disabling openvpn interface(s) causes OSPF to fail to load on reboot` +- {vytask}`T4022` `(feature): Add package nat-rtsp-dkms` + +## 2024-03-22 + +- {vytask}`T6136` `(bug): Configuring a dynamic address group, config script did not check whether the group was created` +- {vytask}`T6130` `(bug): [1.3.6->1.4.0-epa2 Migration] BGP "set community" missing` +- {vytask}`T6090` `(bug): [1.3.6->1.4.0-epa1 Migration] policy route fails due tcp flag case sensitivity` +- {vytask}`T6155` `(default): ixgbe: failed to initialize because an unsupported SFP+ module type was detected.` +- {vytask}`T6125` `(feature): Support 802.1ad (0x88a8) vlan filtering for bridge` +- {vytask}`T5624` `(default): Remove /etc/debian_version from the image` + +## 2024-03-21 + +- {vytask}`T6143` `(feature): Increase configuration timeout range for service config-sync` + +## 2024-03-20 + +- {vytask}`T6133` `(feature): Add domain-name to commit-archive` +- {vytask}`T6129` `(feature): bgp: add route-map option "as-path exclude all"` + +## 2024-03-19 + +- {vytask}`T6127` `(bug): Ability to view logs for rules with Offload not functional` +- {vytask}`T6138` `(bug): Conntrack table op-mode fails with flowtable offload entries` + +## 2024-03-15 + +- {vytask}`T6118` `(feature): radvd: RFC8781: add nat64prefix support` + +## 2024-03-12 + +- {vytask}`T6020` `(bug): VRRP health-check script is not applied correctly in keepalived.conf` +- {vytask}`T5646` `(bug): QoS policy limiter broken if class without match` +- {vytask}`T2433` `(feature): Improve CLI value validator performance` +- {vytask}`T1436` `(bug): Config entries with default values do not correctly show as changed` + +## 2024-03-11 + +- {vytask}`T6098` `(bug): Description doesnt seem to allow for non international characters` +- {vytask}`T6070` `(bug): bnx2x NIC causes a commit error due to incorrect implementation of EEE status reading` +- {vytask}`T2998` `(bug): SNMP v3 oid "exclude" option doesn't work` +- {vytask}`T6107` `(bug): Nginx does not allow big config queries for configure endpoint API` +- {vytask}`T6096` `(bug): Config commits are not synced properly because 00vyos-sync is deleted by vyos-router` +- {vytask}`T6093` `(bug): Incorrect dhcp-options vendor-class-id regex` +- {vytask}`T6083` `(feature): ethtool: move string parsing to JSON parsing` +- {vytask}`T6069` `(bug): HTTP API segfault during concurrent configuration requests` +- {vytask}`T6057` `(feature): Add ability to disable syslog for conntrackd` +- {vytask}`T5504` `(feature): Keepalived VRRP ability to set more than one peer-address` +- {vytask}`T5717` `(feature): ospfv3 - add allow to set metric-type to ospf redistribution while frr docs says its possible.` +- {vytask}`T6071` `(bug): firewall: CLI description limit of 256 characters cause config upgrade issues` + +## 2024-03-08 + +- {vytask}`T6086` `(bug): NAT does not work with network-groups` +- {vytask}`T6094` `(bug): Destination Nat not Making Firewall Rules` +- {vytask}`T6061` `(bug): connection-status nat destination firewall filter not working in 1.4.0-epa1` +- {vytask}`T6075` `(bug): Applying firewall rules with a non-existent interface group` + +## 2024-03-07 + +- {vytask}`T6104` `(bug): Regression in commit-archive for non-interactive configuration` +- {vytask}`T6084` `(bug): OpenNHRP DMVPN configuration file clean after reboot if we have any IPSec configuration` +- {vytask}`T5348` `(bug): Service config-sync can freeze the secondary router if it has commit-archive location` +- {vytask}`T6073` `(bug): Conntrack/NAT not being disabled when VRFs are defined` +- {vytask}`T6095` `(default): Tab completion for "set interfaces wireless wlan0 country-code" incorrect country "uk"` + +## 2024-03-06 + +- {vytask}`T6079` `(bug): dhcp: migration fails for duplicate static-mapping` + +## 2024-03-05 + +- {vytask}`T5903` `(bug): NHRP don´t start on reboot from version 1.5-rolling-202401010026` +- {vytask}`T2447` `(feature): Additional Boot Argument Configuration to limit CPU C-States` + +## 2024-03-04 + +- {vytask}`T6054` `(bug): load-balancing wan - doesn't configure a list of ports` +- {vytask}`T6087` `(feature): ospfv3: add support to redistribute IS-IS routes` + +## 2024-03-02 + +- {vytask}`T6081` `(bug): QoS policy shaper target and interval wrong calcuations` + +## 2024-02-29 + +- {vytask}`T6078` `(feature): Update ethtool to 6.6` +- {vytask}`T6077` `(feature): banner: implement ASCII contest winner default logo` +- {vytask}`T6074` `(feature): container: do not allow deleting images which have a container running` + +## 2024-02-28 + +- {vytask}`T6055` `(bug): PKI error: "failed to install x value" when executed the command from conf mode` +- {vytask}`T4270` `(bug): dns forwarding - When "ignore-hosts-file" is unset, local hostname of router resolves to 127.0.1.1` + +## 2024-02-27 + +- {vytask}`T6065` `(bug): Duplicate lines in build-vyos-image script cause sagitta build to fail` +- {vytask}`T5080` `(bug): Conntrack enabled by default` + +## 2024-02-26 + +- {vytask}`T6064` `(bug): Can not build VyOS if repository it not cloned to a branch` +- {vytask}`T5754` `(default): Update to StrongSwan 5.9.11` + +## 2024-02-25 + +- {vytask}`T6060` `(feature): op-mode: container: support removing all container images at once` + +## 2024-02-24 + +- {vytask}`T5909` `(bug): Container registry with authentication prevents config load (section container) after reboot` + +## 2024-02-23 + +- {vytask}`T5376` `(bug): Conntrack FTP helper does not work properly` +- {vytask}`T970` `(feature): Hostname Support in NAT and Firewall Rules` +- {vytask}`T4940` `(feature): Interface debugging` + +## 2024-02-22 + +- {vytask}`T6048` `(bug): Exception in event handler script` +- {vytask}`T3902` `(bug): Firewall does not load on boot, address-group not found, even though it exists` + +## 2024-02-21 + +- {vytask}`T6050` `(bug): Wrong scripting commands descriptions in accel-ppp services` + +## 2024-02-19 + +- {vytask}`T5971` `(default): Create the same view of ppp section for all accel-ppp services` +- {vytask}`T6029` `(default): Rewrite Accel-PPP services to an identical feature set` +- {vytask}`T3722` `(bug): op-mode IPSec show vpn ike sa always shows L-TIME 0` + +## 2024-02-18 + +- {vytask}`T6043` `(bug): VxLAN and bridge error bug` +- {vytask}`T6041` `(bug): image-tools: install fails from PXE boot into live iso due to restrictive logic` + +## 2024-02-17 + +- {vytask}`T5972` `(feature): login: add possibility to disable individual local user accounts` + +## 2024-02-16 + +- {vytask}`T6009` `(bug): Firewall - Time not working properly when not using UTC` +- {vytask}`T6005` `(bug): Error on adding a wireguard interface to OSPFv3` +- {vytask}`T2113` `(bug): OpenVPN Options error: you cannot use --verify-x509-name with --compat-names or --no-name-remapping` +- {vytask}`T6019` `(feature): Bump nftables and libnftnl version` +- {vytask}`T3471` `(bug): DHCP hook is not able to detect all running DHCP instances` +- {vytask}`T6015` `(default): "journalctl_charon" file does not contain data in the generated "ipsec debug-archive" file` +- {vytask}`T6001` `(default): Add option to enable resolve-via-default` +- {vytask}`T5965` `(bug): WWAN modems using raw-ip do not work with dhclient/dhcp6c` +- {vytask}`T5418` `(bug): PPPoE-Server Client IP pool Subnet` +- {vytask}`T5245` `(bug): Wireless interfaces do not get IPv6 link-local address assigned` + +## 2024-02-15 + +- {vytask}`T5977` `(bug): nftables: Operation not supported when using match-ipsec in outbound firewall` +- {vytask}`T2612` `(bug): HTTPS API, changing API key fails but goes through` +- {vytask}`T5989` `(bug): IP subnets not usable in UPnP ACLs` +- {vytask}`T5890` `(default): OTP key generation is broken` +- {vytask}`T5719` `(default): mdns repeater: Add op-mode commands` +- {vytask}`T4839` `(feature): Dynamic Firewall groups` +- {vytask}`T4801` `(feature): Support for building AWS-ready ISO` +- {vytask}`T3993` `(enhancment): Extend HTTP API GraphQL support` +- {vytask}`T3991` `(bug): PKI operational command return traceback` +- {vytask}`T3780` `(bug): VTI not being brought down when tunnel is down` +- {vytask}`T3001` `(feature): Disable spectre mitigation patches from CLI` +- {vytask}`T562` `(feature): PDNS: Add support for authoritative dns server` +- {vytask}`T71` `(feature): Add virtual IP and route installation policy options for IPsec` +- {vytask}`T5496` `` (default): `show firewall` error `` +- {vytask}`T4038` `` (default): Rewrite `vyatta-image-tools.pl` in Python `` +- {vytask}`T4997` `(default): Add DHCP client user hooks dir` +- {vytask}`T775` `(feature): Config Sync between two VyOS routers` +- {vytask}`T381` `(feature): config nodes for EasyRSA CAs` +- {vytask}`T118` `(feature): Native Zabbix Support` + +## 2024-02-14 + +- {vytask}`T6034` `(feature): rpki: move file based SSH keys for authentication to PKI subsystem` +- {vytask}`T5981` `(bug): IPsec site-to-site migrated PKI ca certificates are created with an '@'` +- {vytask}`T5930` `(bug): vrf - route-leak not work using route-target both command.` +- {vytask}`T5709` `(bug): IPoE-server fails if next pool mentioned but not defined` +- {vytask}`T4119` `(bug): Issue with l2tp remote-access ipv6 configuration` +- {vytask}`T2044` `(bug): RPKI doesn't boot properly` +- {vytask}`T6032` `(feature): bgp: add EVPN MAC-VRF Site-of-Origin support` +- {vytask}`T5960` `(default): Rewriting authentication section in accel-ppp services` + +## 2024-02-13 + +- {vytask}`T5928` `(bug): Configuration fails to load on boot if offloading has VLAN interfaces defined` +- {vytask}`T5482` `(bug): Chrony NTP Server Fails To Sync Time` +- {vytask}`T5064` `(bug): Value validation for domain-groups seems to be broken` + +## 2024-02-12 + +- {vytask}`T6010` `(bug): Support setting multiple values in BGP path-attribute` +- {vytask}`T6004` `(bug): RPKI is not configured` +- {vytask}`T5952` `(default): DHCP allow same MAC Address on same subnet` +- {vytask}`T5849` `(feature): Add SRv6 route commands` + +## 2024-02-10 + +- {vytask}`T6023` `(bug): rpki: add support for CLI knobs expire-interval and retry-interval` +- {vytask}`T1090` `(default): Webproxy overhaul` + +## 2024-02-09 + +- {vytask}`T6028` `(bug): QoS policy shaper wrong class_id_max and default_minor_id` +- {vytask}`T6026` `(bug): QoS hide attempts to delete qdisc from devices` +- {vytask}`T5788` `(feature): frr: update to 9.1 release` +- {vytask}`T5703` `(bug): QoS config on pppoe interface resets back to fq_codel after tunnel reboots` +- {vytask}`T5685` `(feature): Keepalived VRRP prefix is not necessary for the virtual address` + +## 2024-02-08 + +- {vytask}`T6014` `(feature): Bump keepalived version` +- {vytask}`T5910` `(bug): Grub problem(?) Serial Console no longer working` +- {vytask}`T6021` `(bug): QoS r2q wrong calculation` + +## 2024-02-07 + +- {vytask}`T6017` `(bug): Update vyos-http-api-tools for security advisory` +- {vytask}`T6016` `(bug): Resolve intermittent failures in cleanup function after failed image install` +- {vytask}`T6024` `(feature): bgp: add additional missing FRR features` +- {vytask}`T6011` `(feature): rpki: known-hosts-file is no longer supported by FRR CLI - remove VyOS CLI node` +- {vytask}`T5998` `(feature): replay_window setting under vpn in config` + +## 2024-02-06 + +- {vytask}`T6018` `(default): smoketest: updating http-api framework requires a pause before test` +- {vytask}`T5921` `(bug): Trying to commit an OpenConnect configuration without any local users results in an exception` +- {vytask}`T5687` `(feature): Implement ECS settings for PowerDNS recursor` + +## 2024-02-05 + +- {vytask}`T5974` `(bug): QoS policy shaper is currently miscalculating bandwidth and ceil values for the default class` +- {vytask}`T5865` `(feature): Rewrite ipv6 pool section to ipv6 named pools in Accel-ppp services` + +## 2024-02-02 + +- {vytask}`T5739` `(bug): Password recovery does not work if public keys are configured` +- {vytask}`T5955` `(feature): Rootless containers/set uid/gid for container` +- {vytask}`T5941` `(bug): [1.3.5 -> 1.4.0-RC1 Migration] Orphaned Configuration Nodes Cause Issues` +- {vytask}`T6003` `(feature): Add 'show rpki as-number' and 'show rpki prefix'` +- {vytask}`T5848` `(feature): Add triple-isolate flow isolation option to CAKE QoS policy` + +## 2024-02-01 + +- {vytask}`T5995` `(bug): Kernel NIC-drivers for Huawei NICs are not properly enabled` +- {vytask}`T5978` `(bug): ethernet: hw-tc-offload does not actually get enabled on the NIC` +- {vytask}`T5979` `(enhancment): Add configurable kernel boot parameters` +- {vytask}`T5973` `(bug): vrf: RTNETLINK answers: File exists` +- {vytask}`T5967` `(bug): Multi-hop BFD connections can't be established; please add minimum-ttl option.` +- {vytask}`T5619` `(default): Update the Intel ixgbe driver due to issues with Intel X533` + +## 2024-01-31 + +- {vytask}`T6000` `(bug): [1.3.x -> 1.5.x] migrating threw exception in /opt/vyatta/etc/config-migrate/migrate/https/5-to-6, performed workaround` +- {vytask}`T5999` `(bug): load-balancing reverse-proxy can't configure root as a redirect` + +## 2024-01-30 + +- {vytask}`T5980` `(feature): Add image-tools support for configurable kernel boot options` + +## 2024-01-29 + +- {vytask}`T5988` `(bug): image-tools: a check of valid image name is missing from 'add image'` +- {vytask}`T5994` `(bug): Fix typo in 'remote' module preventing 'add system image' via ftp` + +## 2024-01-26 + +- {vytask}`T5957` `(bug): Firewall fails to delete inbound-interface name` +- {vytask}`T5779` `(bug): custom conntrack timeout rule not applicable` +- {vytask}`T5984` `(feature): Add user util numactl` + +## 2024-01-25 + +- {vytask}`T5983` `(bug): image-tools: minor regression in pruning version files in compatibility mode` +- {vytask}`T5927` `` (bug): QoS policy shaper-hfsc class does not have a `bandwidth` node but requires one in the check `` +- {vytask}`T5834` `(bug): Rename 'enable-default-log' to 'default-log'` + +## 2024-01-22 + +- {vytask}`T5968` `(feature): hsflowd: add VRF support` +- {vytask}`T5975` `(bug): GraphQL expects script otp.py that does not exists in 1.4` +- {vytask}`T5961` `(bug): QoS policy shaper vif with ceiling fails on commit` +- {vytask}`T5958` `(bug): QoS policy shaper-hfsc is not implemented` +- {vytask}`T5160` `(feature): Firewall refactor` +- {vytask}`T5969` `(feature): op-mode: list multicast group membership` + +## 2024-01-21 + +- {vytask}`T5799` `(bug): vyos unbootable after 1.4-rolling-202308240020 to 1.5-rolling-202312010026 upgrade` +- {vytask}`T5787` `(bug): dhcp-server allows duplicate static-mapping for the same IP address` +- {vytask}`T5692` `(enhancment): NTP leap smear` +- {vytask}`T5954` `(feature): Enable nvme_hwmon and drivetemp in KERNEL` + +## 2024-01-20 + +- {vytask}`T5915` `(bug): Firewall zone - Re add op-mode commands` +- {vytask}`T5805` `(bug): Missed per-interface statistic in telegraf` +- {vytask}`T5724` `(feature): About dhcp client hooks` +- {vytask}`T5577` `(bug): Optimize PAM configs for RADIUS/TACACS+` +- {vytask}`T5550` `(bug): Source validation on interface does not work properly` +- {vytask}`T5267` `(bug): Another corruption on upgrade` +- {vytask}`T5239` `(bug): frr 'hostname' missing or incorrect, and domain-name missing totally` +- {vytask}`T5219` `(bug): ddclient: Cloudflare doesn't require login` +- {vytask}`T5217` `(feature): Add firewall SYNPROXY` +- {vytask}`T5203` `(feature): load-balancing wan add systemd unit instead of old vyatta-wanloadbalance.init` +- {vytask}`T5199` `(bug): Salt-minion cannot connect to server in python 3.10 and up` +- {vytask}`T5138` `(feature): Add patch to accel-ppp build L2TP LNS use Calling-Number as RADIUS Calling-Station-ID` +- {vytask}`T5054` `(bug): ipsec: "show vpn ipsec remote-access" does not list active connections` +- {vytask}`T5053` `(bug): Vyatta-cfg Post-Removal Hook Tries to Disable Deleted Service` +- {vytask}`T5035` `(feature): Add more actions to policy route rule` +- {vytask}`T4990` `(bug): Commit results may not be properly saved if power is cut immediately after a successful commit` +- {vytask}`T4988` `(default): Expose time and size conversion functions as Jinja2 filters` +- {vytask}`T4986` `(feature): Ability to filter traffic originating from the router itself via firewall` +- {vytask}`T4963` `(default): vyos.ethtool: improve/fix driver name detection` +- {vytask}`T4935` `(bug): ospfv3: "not-advertise" and "advertise" conflict` +- {vytask}`T4897` `` (bug): Setting 'source-address' or `source-interface` on existing vxlan interface doesn't work `` +- {vytask}`T4888` `(default): Rewrite the conntrack sync script using vyos.opmode` +- {vytask}`T4863` `(feature): need an option for route policy to apply to dynamic interfaces l2tp*/ipoe*/pppoe* (for TCP MSS setting)` +- {vytask}`T4817` `(feature): Please add support for RFC 9234` +- {vytask}`T4765` `(default): Normalize field names in op mode JSON outputs` +- {vytask}`T4751` `(enhancment): Feature Request: system login: 2FA OTP key generator in VyOS CLI` +- {vytask}`T4726` `(default): Add completion and validation for the accel-ppp RADIUS vendor option` +- {vytask}`T4722` `(default): Improve abbreviation/acronym consistency` +- {vytask}`T4172` `(feature): Patch ndppd to not read route table if there are no auto prefixes` +- {vytask}`T4085` `(feature): Rewrite L2TP/PPTP/SSTP/PPPoE services to get_config_dict` +- {vytask}`T4031` `(feature): Ability to configure DMVPN in vrf` +- {vytask}`T4030` `(bug): SR-IOV and interface renaming bug` +- {vytask}`T4014` `(feature): Add “command” and “arg” configuration options for containers` +- {vytask}`T3965` `(default): arm: Extend configure scripts to allow for arm builds` +- {vytask}`T3813` `(bug): Some custom sysctl parameters can't be applied bug` +- {vytask}`T3778` `(bug): Abnormal network communication and settings` +- {vytask}`T3591` `(bug): OpenVPN with/without VRF not working (NordVPN)` +- {vytask}`T3372` `(feature): Support public HTTPS repos in live-build` +- {vytask}`T5963` `(bug): QoS policy shaper rate calculations could be wrong for some ethernet devices` +- {vytask}`T5962` `(feature): QoS policy set default speed to 100mbit or 1gbit instead of 10mbit` +- {vytask}`T5697` `(bug): event-handler keep failing` +- {vytask}`T4779` `(default): Make raw op mode command outputs use bytes for data amount values` + +## 2024-01-19 + +- {vytask}`T5897` `(bug): VyOS with Cloud-init and VRF stucks at reboot/shutdown process` +- {vytask}`T5554` `(bug): Disable sudo for PAM RADIUS` +- {vytask}`T4754` `(default): Improvement: system login: show configured 2FA OTP key` +- {vytask}`T5857` `(bug): show interfaces wireless info` +- {vytask}`T5841` `(default): Remove old ssh-session-cleanup.service` +- {vytask}`T5543` `(bug): Fix source address handling in static joins` +- {vytask}`T5884` `(default): Minor description fix (op-mode: generate wireguard)` +- {vytask}`T5781` `(default): Add ability to add additional minisign keys` + +## 2024-01-18 + +- {vytask}`T5863` `(bug): Failure to Load Config on Recent 1.5 Versions` +- {vytask}`T4638` `(bug): Deleting a parent interface does not delete its underlying VLAN interfaces` +- {vytask}`T5953` `` (default): Rename 'close_action' value from `hold` to `trap` in IPSEC IKE `` +- {vytask}`T905` `(bug): The command show remote-config does not work for remote-platform openvpn` + +## 2024-01-17 + +- {vytask}`T5923` `(bug): Config mode system_console.py is not aware of revised GRUB file structure` +- {vytask}`T4658` `` (feature): Rename DPD action `hold` to `trap` `` +- {vytask}`T5932` `(bug): 1.4-rolling-202304120317 to 1.4.0-rc1: dynamic dns migration fail` + +## 2024-01-16 + +- {vytask}`T5951` `(bug): [1.4.0-RC2] show hardware dmi Operational Mode Command Broken` +- {vytask}`T5937` `(bug): [1.3.5 -> 1.4.0-RC1 Migration] IPv6 BGP Neighbor Peer Groups Missing / Not Migrated` +- {vytask}`T5889` `(bug): Migration NAT 5-to-6 bug` +- {vytask}`T5859` `(bug): Invalid format of pool range in accel-ppp services` +- {vytask}`T5842` `(feature): Rewrite PPTP service to get_config_dict` +- {vytask}`T5801` `(feature): Rewrite L2TP service to get_config_dict` +- {vytask}`T5688` `(default): Create the same view of pool configuration for all accel-ppp services` + +## 2024-01-15 + +- {vytask}`T5944` `(bug): "reboot in 1" not working` +- {vytask}`T5936` `(bug): [1.3.5 -> 1.4.0-RC1 Migration] OSPF Passive Interface Configuration Not Working Correctly` +- {vytask}`T5247` `(bug): the bug of the command "show interfaces system"` +- {vytask}`T5901` `(bug): Cloud-init and DHCP exit hook errors` +- {vytask}`T4856` `(bug): DHCP-client exit hook for IPsec is incorrect` +- {vytask}`T2556` `(bug): "show interfaces vrrp" does not return any interface` + +## 2024-01-14 + +- {vytask}`T4428` `(feature): Update ddclient to newer version` + +## 2024-01-12 + +- {vytask}`T5925` `(feature): Containers change systemd KillMode` +- {vytask}`T5920` `(bug): Quick Start documentation contains error` +- {vytask}`T5919` `(bug): Firewall - opmode for ipv6` +- {vytask}`T5306` `(default): bgp config migration failed with v6only option configured with peer-group` +- {vytask}`T3429` `(bug): Hyper-V integration services not working on VyOS 1.4 (sagitta/current)` + +## 2024-01-11 + +- {vytask}`T5896` `(bug): Config Error on Boot with Podman and Firewall` +- {vytask}`T5532` `(bug): After add system image the boot stuck and works again after the second reboot` +- {vytask}`T5512` `(bug): build linux-firmware script cannot expand asterisks if firmware name is a glob string` +- {vytask}`T5379` `(bug): show system updates doesnt seem to be working` +- {vytask}`T5275` `(default): Add op mode commands for exporting certificates to PEM files with correct headers` +- {vytask}`T5274` `(default): Add a deprecation warning for OpenVPN site-to-site with pre-shared secret` +- {vytask}`T5262` `(default): Warn the user about unsaved config on reboot/shutdown attempts` +- {vytask}`T5257` `(feature): Cannont assign netflow source ip to ip in non default VRF` +- {vytask}`T5026` `(feature): Python3 modules crypt and spwd are deprecated` +- {vytask}`T5814` `(bug): VyOS 1.3 to 1.4 LTS Firewall ruleset migration script breaks configuration` +- {vytask}`T4610` `(bug): Firewall with 20K entries cannot load after reboot` +- {vytask}`T3191` `(bug): PAM RADIUS freezing when accounting does not configured on RADIUS server` +- {vytask}`T5917` `(feature): Restore annotations of (running)/(default boot) in select image list` +- {vytask}`T5916` `(default): Added segment routing check for index size and SRGB size` +- {vytask}`T5913` `(feature): Allow for Peer-Groups in ipv4-labeled-unicast SAFI` + +## 2024-01-10 + +- {vytask}`T5918` `` (bug): Verification problem for `set vpn ipsec interface` `` +- {vytask}`T5911` `(bug): pki: service update ignored if certificate name contains a hyphen (-)` +- {vytask}`T5886` `(feature): Add support for ACME protocol (LetsEncrypt)` +- {vytask}`T5766` `(bug): http: rewrite conf-mode script to get_config_dict()` +- {vytask}`T5144` `(default): Modernize dynamic dns operation` +- {vytask}`T4689` `(feature): Support RFS(Receive Flow Steering)` +- {vytask}`T4659` `(feature): Use vtysh to display bridge and some interface parameter information` +- {vytask}`T4646` `(bug): USB serial output console does not work` +- {vytask}`T4577` `(bug): WWAN commit failed which simple config` +- {vytask}`T4502` `(feature): Consider implementing (NAT/other) flow table offload` +- {vytask}`T4446` `(default): Unified CLI for displaying neithbors (ARP, IP, and NDP)` +- {vytask}`T4427` `(default): Remove the vyos-utils package list from vyos-build` +- {vytask}`T4300` `(feature): Extend list of supported interfaces for Cloud-init Network Configuration` +- {vytask}`T4250` `(bug): Organize logrotate settings to avoid duplicates` +- {vytask}`T4236` `(feature): Generate ovpn openvpn client configuration files` +- {vytask}`T4222` `(feature): Support for TWAMP as round-trip metric` +- {vytask}`T3833` `(bug): Cloud-init not finding data source in OpenStack` +- {vytask}`T5902` `(bug): http: remove virtual-host configuration in webserver` +- {vytask}`T3499` `(bug): Podman is not compatible with nat rules` +- {vytask}`T3430` `(bug): Cloud-init failing with “Unable to render networking” on VyOS 1.3` +- {vytask}`T3011` `(bug): router becomes unreachable for few minutes when vti interfaces goes down` +- {vytask}`T5791` `(default): Update dynamic dns configuration path to be consistent with other areas of VyOS` +- {vytask}`T5708` `(default): Additional dynamic dns improvements to align with ddclient 3.11.1 release` +- {vytask}`T5573` `(bug): Fix ddclient cache entries` +- {vytask}`T5012` `(feature): Control network configuration from Cloud-Init config` +- {vytask}`T3116` `(feature): Support back-end L4 level load balancing` +- {vytask}`T5614` `(default): Add conntrack helper matching on firewall` +- {vytask}`T4782` `(enhancment): Allow multiple CA certificates (on e.g. EAPoL)` +- {vytask}`T2199` `(default): Rewrite firewall in new XML/Python style` + +## 2024-01-09 + +- {vytask}`T5898` `(bug): Replace partprobe with partx due to unable to install VyOS` +- {vytask}`T5838` `(feature): Add Infiniband kernel modules` +- {vytask}`T5785` `(bug): API output of show container image broken` +- {vytask}`T5410` `` (feature): Improve `utils.convert.convert_data()` to process all stdtypes `` +- {vytask}`T5269` `(default): OpenVPN non-TLS site-to-site mode deprecation` +- {vytask}`T5249` `(feature): Add rollback-soft feature to rollback without a reboot` +- {vytask}`T4944` `(default): Prevent op mode functions from returning bare literals in raw output` +- {vytask}`T4910` `(default): Rewrite the remote access VPN op mode in the new style` +- {vytask}`T4470` `(feature): Rewrite load-balancing wan to XML/Python` +- {vytask}`T3763` `(bug): wireguard checks if port already binding` +- {vytask}`T3489` `(bug): NUMA has been disabled for the past few years and no-one has noticed` +- {vytask}`T3476` `(feature): Update availability check` +- {vytask}`T2845` `(bug): BGP conf_mode unable to delete configuration with peer-group` +- {vytask}`T2844` `(bug): BGP conf_mode errors disable-send-community` +- {vytask}`T2755` `(default): Requirements for partial interface setup` +- {vytask}`T2721` `(enhancment): Set FQ-CoDel as the default queueing mechanism for every class in Shaper` +- {vytask}`T2511` `(feature): Migrate vyatta-op-quagga to new XML format` +- {vytask}`T2302` `(default): Convert configuration scripts from executables to modules and use a script runner` +- {vytask}`T2281` `(feature): DHCP and Static IPs on Same Interface` +- {vytask}`T2216` `(default): Containerized third-party applications for VyOS` +- {vytask}`T2171` `(feature): Unify creation and manipulation of interfaces` +- {vytask}`T1759` `(feature): Replacing Vyatta::Interface perl` +- {vytask}`T2408` `(enhancment): DHCP Relay upstream and downstream interfaces` +- {vytask}`T1297` `(feature): Add GARP settings to VRRP/keepalived` + +## 2024-01-08 + +- {vytask}`T5888` `(bug): Firewall upgrade fails because of icmpv6` +- {vytask}`T5844` `(bug): HTTPS API doesn't start without configured keys even when GraphQL authentication type is set to token` +- {vytask}`T5664` `(bug): 1.4 user has no permissions?` +- {vytask}`T5215` `(default): Add a built-in ICMP health check for VRRP groups` +- {vytask}`T5045` `(bug): BFD is not starting after upgrade to 1.4-rolling-202302150317` +- {vytask}`T4193` `(default): Add support for transparent firewall` +- {vytask}`T3754` `(default): Make config scripts more testable` +- {vytask}`T3663` `(default): Use inotify file watching where applicable` +- {vytask}`T3480` `(bug): Does not possible to change console baud-rate` +- {vytask}`T2897` `(default): Remove cluster command` +- {vytask}`T5904` `(feature): op-mode: add "show ipv6 route vrf <name> <prefix>" command` + +## 2024-01-07 + +- {vytask}`T5891` `(bug): OpenVPN IPv6 config issue with 1.4-rc1` +- {vytask}`T5887` `(feature): Upgrade Linux Kernel to 6.6.y (2023 LTS edition)` + +## 2024-01-06 + +- {vytask}`T3670` `(feature): Option to disable HTTP port 80 redirect` + +## 2024-01-05 + +- {vytask}`T3642` `(feature): PKI configuration` +- {vytask}`T5894` `(feature): Extend get_config_dict() with additional parameter with_pki that defaults to False` + +## 2024-01-04 + +- {vytask}`T4072` `(feature): Feature Request: Firewall on bridge interfaces` +- {vytask}`T3459` `(default): Inform the user when unable to install outdated image` + +## 2024-01-03 + +- {vytask}`T5880` `(bug): verify_source_interface should not allow dynamic interfaces like ppp, l2tp, ipoe or sstpc client interfaces` +- {vytask}`T5879` `(bug): tunnel: sourceing from dynamic pppoe0 interface will fail on reboots` +- {vytask}`T4500` `(bug): Missing firewall logs` + +## 2024-01-02 + +- {vytask}`T5885` `(default): image-tools: relax restriction on image-name length from 32 to 64` + +## 2024-01-01 + +- {vytask}`T5883` `(bug): Preserve file ownership in /config subdirs on add system image` +- {vytask}`T5474` `(feature): Establish common file name pattern for XML conf mode commands` + +## 2023-12-30 + +- {vytask}`T5875` `(bug): login: removing and re-adding a user keeps the home directory but UID will change, thus SSH keys no longer work` +- {vytask}`T5653` `(feature): Command to display fingerprint` + +## 2023-12-29 + +- {vytask}`T5829` `(bug): Can't Add IPv6 Address to Containers` +- {vytask}`T5852` `(bug): Reboots fail with eapol WAN interface` +- {vytask}`T5869` `(bug): vyos.template.first_host_address() does not honor RFC4291 section 2.6.1` + +## 2023-12-28 + +- {vytask}`T4163` `(feature): [BMP-BGP] Routing monitoring feature` +- {vytask}`T5867` `(feature): Upgrade podman to Debian Trixie version 4.7.x` +- {vytask}`T5866` `(feature): Add op-mode command to restart IPv6 RA daemon` +- {vytask}`T5861` `(bug): Flavor build system fails with third-party packages` +- {vytask}`T5854` `(feature): Extend override-default script to allow embedded defaultValue settings` +- {vytask}`T5792` `(default): Upgrade ddclient 3.11.2 release` + +## 2023-12-25 + +- {vytask}`T5855` `` (feature): Migrate "set service lldp snmp enable" -> `set service lldp snmp" `` +- {vytask}`T5837` `(bug): vyos.configdict.node_changed does not return keys per adding` +- {vytask}`T5856` `(bug): SNMP service removal fails` + +## 2023-12-24 + +- {vytask}`T5853` `(default): Typo interfaces-virtual-ethernet.xml.in` + +## 2023-12-22 + +- {vytask}`T5804` `(bug): SNAT "any" interface error` +- {vytask}`T4760` `(bug): VyOS does not support running multiple instances of DHCPv6 clients` + +## 2023-12-21 + +- {vytask}`T5778` `(bug): The show dhcp server leases operation mode command does not work as expected` +- {vytask}`T5775` `(default): Migrated Firewall Global State Policy ineffective on latest firewall zone config` +- {vytask}`T5637` `(bug): Firewall default-action log` +- {vytask}`T5796` `(bug): Openconnect - HTTPS security headers are missing` +- {vytask}`T3580` `(feature): Refactoring firewall ipv6 rule icmpv6` +- {vytask}`T2898` `(feature): Support NDP proxy` +- {vytask}`T2229` `(feature): PPPOE Default Queue type selection` + +## 2023-12-20 + +- {vytask}`T5823` `(feature): Protocol BGP add default values for config dictionary` +- {vytask}`T5798` `(enhancment): reverse-proxy load-balancing service should support multiple certificates for frontend` + +## 2023-12-19 + +- {vytask}`T5828` `(default): Fix GRUB installation on arm64` + +## 2023-12-18 + +- {vytask}`T5751` `(feature): Adjust new image tools for non-interactive use` +- {vytask}`T5831` `(feature): show system image should reverse order by addition date` +- {vytask}`T5825` `(bug): image-tools: restore authentication on 'add system image'` +- {vytask}`T5821` `(bug): image-tools: restore vrf-aware 'add system image'` +- {vytask}`T5819` `(bug): Don't echo password on install image` +- {vytask}`T5806` `(bug): Clear old raid data on new install image` +- {vytask}`T5789` `(bug): image-tools should copy ssh host keys on image update` +- {vytask}`T5758` `(default): Restore scanning configs when live installing` + +## 2023-12-15 + +- {vytask}`T5824` `(bug): busybox cannot connect some websites from initramfs` +- {vytask}`T5803` `(default): git/github: Adjust configuration for safe and baseline defaults` + +## 2023-12-14 + +- {vytask}`T5773` `(bug): Unable to load config via HTTP` +- {vytask}`T5816` `(bug): BGP Large Community List Validation Broken` +- {vytask}`T5812` `(bug): rollback check max revision number does not work` +- {vytask}`T5749` `(feature): Show MAC address VRF and MTU by default for "show interfaces"` +- {vytask}`T5774` `(bug): commit-archive to FTP server broken after update (VyOS 1.5-rolling)` +- {vytask}`T5826` `(default): Add dmicode as an explicit dependency` +- {vytask}`T5793` `(default): mdns-repeater: Cleanup avahi-daemon configuration in /etc` + +## 2023-12-13 + +- {vytask}`T591` `(feature): Support SRv6` + +## 2023-12-12 + +- {vytask}`T4704` `(feature): Allow to set metric (MED) to rtt with rtt,+rtt or -rtt` +- {vytask}`T5815` `(enhancment): Add load_config module` +- {vytask}`T5413` `(default): Deny the opportunity to use one public/private key pair on both wireguard peers.` + +## 2023-12-11 + +- {vytask}`T5741` `(bug): WAN Load Balancing failover route tables aren't created` + +## 2023-12-10 + +- {vytask}`T5658` `(default): Add VRF support for mtr` + +## 2023-12-09 + +- {vytask}`T5808` `(bug): op-mode: ipv6 ospfv3 graceful-restart description contains incorrect info` +- {vytask}`T5802` `(bug): ping (ip or hostname) interface <tab> produces error` +- {vytask}`T5747` `(feature): op-mode add MAC VRF and MTU for show interfaces summary` +- {vytask}`T3983` `(bug): show pki certificate Doesnt show x509 certificates` + +## 2023-12-08 + +- {vytask}`T5782` `(enhancment): Use a single config mode script for https and http-api` +- {vytask}`T5768` `(enhancment): Remove auxiliary http-api.conf for simplification of http-api config mode script` +- {vytask}`T5809` `(default): Enable GRUB support for gzip compressed kernels` + +## 2023-12-04 + +- {vytask}`T5769` `(bug): VTI tunnels lose their v6 Link Local addresses when set down/up` + +## 2023-12-03 + +- {vytask}`T5753` `(feature): Add VXLAN vnifilter support` +- {vytask}`T5759` `(feature): Change VXLAN default MTU to 1500 bytes` + +## 2023-11-30 + +- {vytask}`T4601` `(bug): dhcp : relay agent IP address issue.` + +## 2023-11-28 + +- {vytask}`T4276` `(bug): IPsec peers dh-group negotiation issue with pfs enabled and multiple proposals configured with IKEv1` + +## 2023-11-27 + +- {vytask}`T5763` `(bug): Fix imprecise check for remote file name in vyos-load-config.py` +- {vytask}`T5783` `(feature): frr: smoketests must notice any daemon crash` + +## 2023-11-26 + +- {vytask}`T5760` `(feature): DHCP client custom dhcp-options` +- {vytask}`T2405` `(feature): archive to GIT or other platform` + +## 2023-11-25 + +- {vytask}`T5655` `(bug): commit-archive: Ctrl+C should not eror out with stack trace, signal should be cought` +- {vytask}`T4946` `(default): Rewrite "add system image" in the new op-mode` +- {vytask}`T4454` `` (default): `install-image` should check free storage `` + +## 2023-11-24 + +- {vytask}`T5776` `(feature): Enable VFIO support` +- {vytask}`T5402` `(bug): VRRP router with rfc3768-compatibility sends multiple ARP replies` +- {vytask}`T3895` `(default): VYOS firewall rules do not adhere to time schedule unless placed in UTC mode.` + +## 2023-11-23 + +- {vytask}`T4891` `(bug): BFD flapping loop` +- {vytask}`T4867` `(bug): "show bgp neighbors ... advertised-routes" and some other commands fail for IPv4 neighbors` + +## 2023-11-22 + +- {vytask}`T5767` `(feature): Add reboot and poweroff the system via API` +- {vytask}`T5729` `(bug): Firewall, nat and policy route - Switch to valueless` +- {vytask}`T5681` `(feature): Interface match - Simplified and unified cli` +- {vytask}`T4877` `(bug): Need verification in using import vrf and import vpn, export vpn commands` +- {vytask}`T4021` `(bug): Long commit time on bridge interface with 1-4094 allowed VLAN tags` +- {vytask}`T5338` `(feature): Add 'mpls bgp forwarding' feature` +- {vytask}`T3818` `(bug): BGP export route-map only works after bgpd restart` +- {vytask}`T5590` `(default): Firewall "log enable" logs every packet` +- {vytask}`T5426` `(default): Add exceptions in vici functions calls` + +## 2023-11-21 + +- {vytask}`T5762` `(bug): http: api: smoketests fail as they can not establish IPv6 connection to uvicorn backend server` + +## 2023-11-20 + +- {vytask}`T2816` `(default): Rewrite IPsec scripts with the new XML/Python approach` + +## 2023-11-18 + +- {vytask}`T1354` `(feature): Add support for VLAN-Aware bridges` + +## 2023-11-16 + +- {vytask}`T5726` `(bug): HTTPS API image cannot be updated` +- {vytask}`T5738` `(feature): Extend XML building blocks` +- {vytask}`T5736` `(feature): igmp: migrate "protocols igmp" to "protocols pim"` +- {vytask}`T5733` `(feature): pim(6): rewrite FRR PIM daemon configuration to get_config_dict() and add missing IGMP features` +- {vytask}`T5689` `(default): FRR 9.0.1 in VyOS current segfaults on show rpki prefix $prefix` +- {vytask}`T5595` `(feature): Multicast - PIM bfd feature enable` +- {vytask}`T3638` `(bug): Passwords With Dollar Sign Set Incorrectly` + +## 2023-11-15 + +- {vytask}`T5695` `(feature): Build FRR with LUA scripts --enable-scripting option` +- {vytask}`T5665` `(bug): radius user not working` +- {vytask}`T5728` `(bug): Improve compatibility between OpenVPN on VyOS 1.5 and OpenVPN Connect Client` +- {vytask}`T5732` `(bug): generate firewall rule-resequence drops geoip country-code from output` +- {vytask}`T5661` `(enhancment): Add show show ssh dynamic-protection attacker and show log ssh dynamic-protection` +- {vytask}`T1276` `(bug): dhcp relay + VLAN fails` + +## 2023-11-13 + +- {vytask}`T5698` `(feature): EVPN ESI Multihoming` +- {vytask}`T5563` `(bug): container: Container environment variable cannot be set` +- {vytask}`T5706` `(bug): Systemd-udevd high CPU utilization for multiple dynamic ppp/l2tp/ipoe interfaces` + +## 2023-11-10 + +- {vytask}`T5727` `(bug): validator: Use native URL validator instead of regex-based validator` + +## 2023-11-08 + +- {vytask}`T5720` `(bug): PPPoE-server adding new interface does not work` +- {vytask}`T5716` `(bug): PPPoE-server shaper template bug down-limiter option does not rely on fwmark` +- {vytask}`T5702` `(feature): Add ability to set include_ifmib_iface_prefix and ifmib_max_num_ifaces for SNMP` +- {vytask}`T5648` `(bug): ldpd neighbour template errors` +- {vytask}`T5564` `(bug): Both show firewall group and show firewall summary fails` +- {vytask}`T5559` `(feature): Selective proxy-arp/proxy-ndp when doing SNAT/DNAT` +- {vytask}`T5541` `(bug): Zone-Based Firewalling in VyOS Sagitta 1.4` +- {vytask}`T5513` `(bug): Anomalies in show firewall command after refactoring` +- {vytask}`T4864` `` (bug): `show firewall` command errors `` + +## 2023-11-07 + +- {vytask}`T5586` `(feature): Disable by default SNMP for Keepalived VRRP` + +## 2023-11-06 + +- {vytask}`T5705` `(bug): rsyslog - Not working when using facility=all` +- {vytask}`T5704` `(feature): PPPoE-server add max-starting option` +- {vytask}`T5707` `(bug): Wireguard peer public key update leaves redundant peers and breaks connectivity` +- {vytask}`T4269` `(feature): node.def generator should automatically add default values` + +## 2023-11-05 + +- {vytask}`T4020` `(feature): Add ability to control FRR daemons options` + +## 2023-11-03 + +- {vytask}`T5700` `(bug): Monitoring telegraf deprecated plugins inputs outputs` +- {vytask}`T5018` `(bug): Redirect to IFB removed after change in qos policy` + +## 2023-11-02 + +- {vytask}`T5701` `(feature): Update telegraf package` + +## 2023-11-01 + +- {vytask}`T5690` `(bug): Change to definition of environment variable 'vyos_rootfs_dir' is incorrect` + +## 2023-10-31 + +- {vytask}`T5699` `(feature): vxlan: migrate "external" CLI know to "parameters external"` +- {vytask}`T5668` `(feature): Disable VXLAN bridge learning and enable neigh_suppress when using EVPN` + +## 2023-10-27 + +- {vytask}`T5652` `(bug): Config migrate to image upgrade does not properly generate home directory` +- {vytask}`T4057` `(bug): Commit time for deleting sflow configuration ~1.5 min` + +## 2023-10-26 + +- {vytask}`T5683` `(bug): reverse-proxy pki filenames mismatch` +- {vytask}`T4903` `(bug): conntrack ignore does not suppotr IPv6 addresses` +- {vytask}`T4309` `(feature): Support network/address-groups and ipv6-network/ipv6-address-groups in conntrack ignore` +- {vytask}`T5606` `(feature): IPSec VPN: Allow multiple CAs certificates` +- {vytask}`T5650` `(default): Progressbars suffer from staircasing effect` +- {vytask}`T5568` `(default): Install image from live ISO always defaults boot to KVM entry` +- {vytask}`T3509` `(default): No BCP38 for IPv6 on VyOS` + +## 2023-10-23 + +- {vytask}`T5299` `(bug): QoS shaper ceiling does not work` +- {vytask}`T5667` `(feature): BGP label-unicast - enable ecmp` +- {vytask}`T5337` `(bug): MPLS/BGP: Route leak does not happen from the VPNv4 table to specific vrf` + +## 2023-10-22 + +- {vytask}`T5254` `(bug): Modification of any interface setting sets MTU back to default when MTU has been inherited from a bond` +- {vytask}`T5671` `(feature): vxlan: change port to IANA assigned default port` + +## 2023-10-21 + +- {vytask}`T5670` `(bug): bridge: missing member interface validator` +- {vytask}`T5617` `(feature): Add an option to exclude single values to the numeric validator` +- {vytask}`T5414` `(bug): dhcp-server does not allow valid bootfile-names` +- {vytask}`T5261` `(feature): Add AWS gateway load-balanceing tunnel handler (gwlbtun)` +- {vytask}`T5260` `(bug): Python3 module crypt is deprecated` +- {vytask}`T5191` `(default): Replace underscores with hyphens in command-line options generated by vyos.opmode` +- {vytask}`T5172` `(default): Set Python3 version dependency for vyos-1x to 3.10` +- {vytask}`T4956` `(default): 'show hardware cpu' issue on arm64` +- {vytask}`T4837` `(default): Expose "show ip route summary" in the op mode API` +- {vytask}`T4770` `(feature): Rewrite OpenVPN op-mode to vyos.opmode format` +- {vytask}`T4657` `` (bug): op-mode scripts with type hints in `return` do not work `` +- {vytask}`T4604` `(bug): bgpd eats huge amount of memory (about 500Megs a day)` +- {vytask}`T4432` `(default): Display load average normalized according to the number of CPU cores` +- {vytask}`T4416` `(default): Convert 'traceroute' operation to the new syntax and expand available options using python` +- {vytask}`T4402` `(bug): OpenVPN client-ip-pool option is broken` +- {vytask}`T3433` `(default): A review of the use of racist language in VyOS` +- {vytask}`T2719` `(feature): Standardized op mode script structure` + +## 2023-10-20 + +- {vytask}`T5233` `(bug): Op-mode flow-accounting netflow with disable-imt errors` +- {vytask}`T5232` `(bug): Flow-accounting uacctd.service cannot restart correctly` + +## 2023-10-19 + +- {vytask}`T4913` `(default): Rewrite the wireless op mode in the new style` + +## 2023-10-18 + +- {vytask}`T5642` `(bug): op cmd: generate tech-support archive: does not work` +- {vytask}`T5521` `(bug): Home owner directory changed to vyos for the user after reboot` + +## 2023-10-17 + +- {vytask}`T5662` `(bug): Fix indexing error in configdep script organization` +- {vytask}`T5235` `(bug): SSH keys with special characters cannot be applied via Cloud-init` + +## 2023-10-16 + +- {vytask}`T5165` `(feature): Policy local-route ability set protocol and port` + +## 2023-10-14 + +- {vytask}`T5629` `(bug): Policy local-route bug after migration to destination node address` + +## 2023-10-13 + +- {vytask}`T5227` `(feature): mDNS reflector should allow additional domains to browse and allow filtering services` +- {vytask}`T5166` `(feature): Remove local minisign package from build repo for 1.4` +- {vytask}`T5118` `(bug): Cleanup vestigial ntp completion script` +- {vytask}`T5115` `(default): Support custom port for name servers for forwarding zones` +- {vytask}`T5113` `(default): PDNS: Support custom port for DNS forwarders` +- {vytask}`T5112` `(feature): Enable support for Network Time Security (NTS) for chrony` +- {vytask}`T5143` `(enhancment): Apply constraint on powerdns forward-zones configuration` + +## 2023-10-12 + +- {vytask}`T5649` `(bug): vyos-1x should generate XML cache after building command templates for less cryptic error on typo` + +## 2023-10-10 + +- {vytask}`T5489` `(feature): Change to BBR as TCP congestion control, or at least make it an config option` +- {vytask}`T5479` `(bug): Helper leftovers found in nftables (firewall) even with all helpers disabled` +- {vytask}`T5436` `(bug): vyos-preconfig-bootup.script is missing` +- {vytask}`T5014` `(feature): Destination NAT - Add Load Balancing capabilities` + +## 2023-10-08 + +- {vytask}`T5630` `(feature): pppoe: allow to specify MRU in addition to already configurable MTU` + +## 2023-10-06 + +- {vytask}`T5096` `(feature): Change 'accept' firewall rule action from 'return' to 'accept'` +- {vytask}`T5576` `(feature): Add bgp remove-private-as all option` +- {vytask}`T3506` `(default): Migrate loadkey command to op-mode` + +## 2023-10-05 + +- {vytask}`T4320` `(default): Remove legacy version files in vyatta-cfg-system/cfg-version` + +## 2023-10-04 + +- {vytask}`T5632` `(feature): Add jq package to parse JSON files` +- {vytask}`T3655` `(bug): NAT Problem with VRF` +- {vytask}`T5585` `(bug): Fix file access mode for dynamic dns configuration` + +## 2023-10-03 + +- {vytask}`T5618` `(bug): Flow-accounting crushes when IMT is enabled` +- {vytask}`T5561` `(feature): NAT - Inbound or outbound interface should not be mandatory` +- {vytask}`T5553` `(feature): Firewall - Add action continue` +- {vytask}`T5250` `(bug): Firewall - show firewall group` +- {vytask}`T4383` `(bug): Flow Accounting returns permission error and fails to start` +- {vytask}`T5626` `(feature): Only select required Kernel CGROUP controllers` +- {vytask}`T5628` `(feature): op-mode: login: DeprecationWarning: 'spwd'` + +## 2023-10-01 + +- {vytask}`T936` `(feature): Reimplementation of tech-support diagnostic file generation` + +## 2023-09-30 + +- {vytask}`T5048` `(bug): QoS doesn't work correctly root task` +- {vytask}`T4989` `(bug): QoS Policy Limiter - classes for marked traffic do not work` + +## 2023-09-28 + +- {vytask}`T5596` `(feature): bgp: add new features from FRR 9` +- {vytask}`T5412` `(feature): Add support for extending config-mode dependencies in supplemental package` + +## 2023-09-26 + +- {vytask}`T5480` `(bug): Ability to disable SNMP for VRRP keepalived service` + +## 2023-09-25 + +- {vytask}`T5533` `(bug): Keepalived VRRP IPv6 group enters in FAULT state` + +## 2023-09-24 + +- {vytask}`T5511` `(feature): Cleanup of unused directories (and files) in order to shrink image-size` + +## 2023-09-23 + +- {vytask}`T5518` `(default): Add MLD protocol support` + +## 2023-09-22 + +- {vytask}`T5602` `(feature): For reverse-proxy type of load-balancing feature, support "backup" option in backends configuration` +- {vytask}`T5609` `(enhancment): Add util to get drive device name from id` +- {vytask}`T5608` `(enhancment): Rewrite add/delete raid member to Python and remove from vyatta-op` +- {vytask}`T5607` `(bug): Adjust RAID smoketest for non-deterministic SCSI device probing` + +## 2023-09-20 + +- {vytask}`T5588` `(bug): Add kernel conntrack_bridge module` +- {vytask}`T5271` `(default): Add support for peer-fingerprint to OpenVPN` +- {vytask}`T5241` `(feature): Support veth interfaces to working with netns` +- {vytask}`T5238` `(default): interface virtual-etherne - error when it doesn't use a peer` +- {vytask}`T5592` `(feature): salt: upgrade minion to 3005.2` + +## 2023-09-19 + +- {vytask}`T5597` `(feature): isis: add new features from FRR 9.` +- {vytask}`T4284` `(feature): QoS: rewrite to XML and Python` + +## 2023-09-18 + +- {vytask}`T5419` `(feature): Software/Hardware fastpath with nftables flowtable` + +## 2023-09-15 + +- {vytask}`T5581` `(feature): Add "show ip nht" op-mode command (IPv4 nexthop tracking table)` + +## 2023-09-11 + +- {vytask}`T5567` `(bug): vyos-1x: webproxy: maximum-object-size allowed ranges not in sync with Equuleus` +- {vytask}`T5551` `(bug): Missing check for boot_configuration_complete raises error in vyos-save-config.py` +- {vytask}`T5353` `(bug): config-mgmt: normalize archive updates and commit log entries` +- {vytask}`T3424` `(default): PPPoE IA-PD doesn't work in VRF` +- {vytask}`T2773` `(feature): EIGRP support for VRF` + +## 2023-09-10 + +- {vytask}`T5565` `(bug): Builds as vyos-999-timestamp instead of vyos-1.4-rolling-timestamp` +- {vytask}`T5555` `(bug): Fix timezone migrator (system 13-to-14)` +- {vytask}`T5529` `(bug): Missing symbolic link in linux-firmware package.` + +## 2023-09-09 + +- {vytask}`T5540` `(bug): vyos-1x: Wrong VHT configuration for WiFi 802.11ac` +- {vytask}`T5423` `(bug): ipsec: no output for op-cmd "show vpn ike secrets"` +- {vytask}`T3700` `(feature): Support VLAN tunnel mapping of VLAN aware bridges` + +## 2023-09-08 + +- {vytask}`T5502` `(bug): Firewall - wrong parser for inbound and/or outbound interface` +- {vytask}`T5460` `(feature): Firewall - remove config-trap` +- {vytask}`T5450` `(feature): Firewall interface group - Allow inverted matcher` +- {vytask}`T4426` `(default): Add arpwatch to the image` +- {vytask}`T4356` `(bug): DHCP v6 client only supports single interface configuration` + +## 2023-09-07 + +- {vytask}`T5510` `(feature): Shrink imagesize and improve read performance by changing mksquashfs syntax` + +## 2023-09-06 + +- {vytask}`T5542` `(bug): ipoe-server: external-dhcp(dhcp-relay) not woking / not implemented` +- {vytask}`T5548` `(bug): HAProxy renders timeouts incorrectly` +- {vytask}`T5544` `(feature): Allow CAP_SYS_MODULE to be set on containers` + +## 2023-09-05 + +- {vytask}`T5524` `(feature): Add config directory to liveCD` +- {vytask}`T5519` `` (bug): Function `call` sometimes hangs `` +- {vytask}`T5508` `(bug): Configuration Migration Fails to New Netfilter Firewall Syntax` +- {vytask}`T5495` `(feature): Enable snmp module also for frr/ldpd` +- {vytask}`T2958` `(bug): DHCP server doesn't work from a live CD` +- {vytask}`T5428` `(bug): dhcp: client renewal fails when running inside VRF` + +## 2023-09-04 + +- {vytask}`T5536` `(bug): show dhcp client leases caues No module named 'vyos.validate'` +- {vytask}`T5506` `(bug): Container bridge interfaces do not have a link-local address` + +## 2023-09-03 + +- {vytask}`T5538` `(bug): Change order within variable lb_config_tmpl to fit order of manpage and fix some typos` +- {vytask}`T4612` `(feature): Support arbitrary netmasks in firewall rules` + +## 2023-08-31 + +- {vytask}`T5190` `(feature): Cloud-Init cannot fetch Meta-data on machines where the main Ethernet interface is not eth0` +- {vytask}`T4895` `(bug): Tag nodes are overwritten when configured by Cloud-Init from User-Data` +- {vytask}`T4776` `(bug): NVME storage is not detected properly during installation` +- {vytask}`T5531` `(feature): Containers add label option` +- {vytask}`T5525` `(default): Change dev.packages.vyos.net repo to rolling-packages.vyos.net vyos-build:current uses` + +## 2023-08-30 + +- {vytask}`T4933` `(default): Malformed lines cause vyos.util.colon_separated_to_dict fail with a nondescript error` +- {vytask}`T4790` `(bug): RADIUS login does not work if sum of timeouts more than 50s` +- {vytask}`T4113` `(bug): Incorrect GRUB configuration parsing` +- {vytask}`T5520` `(bug): Likely source of corruption on system update exposed by change in coreutils for Bookworm` +- {vytask}`T4151` `(feature): IPV6 local PBR Support` +- {vytask}`T4485` `(default): OpenVPN: Allow multiple CAs certificates` + +## 2023-08-29 + +- {vytask}`T3940` `(bug): DHCP client does not remove IP address when stopped by the 02-vyos-stopdhclient hook` +- {vytask}`T3713` `(default): Create a meta-package for user utilities` +- {vytask}`T3339` `(bug): Cloud-Init domain search setting not applied` +- {vytask}`T3577` `(bug): Generating vpn x509 key pair fails with command not found` + +## 2023-08-28 + +- {vytask}`T4745` `(bug): CLI TAB issue with values with '-' at the beginning in conf mode` +- {vytask}`T5472` `(bug): NAT redirect should not require port` + +## 2023-08-27 + +- {vytask}`T4759` `(bug): domain-group on policy route not working` +- {vytask}`T1097` `(feature): Make firewall groups work everywhere that's appropropriate` + +## 2023-08-26 + +- {vytask}`T5039` `(bug): Can't add new local user` +- {vytask}`T5023` `(bug): PKI commit fails to update dependents` +- {vytask}`T4512` `(feature): enable-default-log on zone-policy` +- {vytask}`T5003` `(default): Upgrade base system to Debian 12 "Bookworm"` + +## 2023-08-25 + +- {vytask}`T5468` `(feature): Remove unused manpages to free up space` +- {vytask}`T5463` `(feature): Containers allow publish IPv6 address port` +- {vytask}`T4412` `(bug): commit archive: reboot not working with sftp` +- {vytask}`T3702` `(feature): Policy: Allow routing by fwmark` +- {vytask}`T3536` `(default): Unable to list all available routes` + +## 2023-08-24 + +- {vytask}`T5448` `(feature): Add service zabbix-agent` +- {vytask}`T5006` `(bug): Http api segfault with concurrent requests` +- {vytask}`T5505` `(feature): system: zebra route-map is not removed from FRR` +- {vytask}`T5305` `(bug): REST API configure operation should not be defined as async` +- {vytask}`T4292` `(feature): Rewrite vyatta-save-config.pl to Python` + +## 2023-08-23 + +- {vytask}`T5478` `(bug): Cannot configure resolver-cache options for firewall` +- {vytask}`T5466` `(feature): L3VPN - label allocation mode` +- {vytask}`T5453` `(bug): Fix nat66 - broken after load-balance was introduced in nat` +- {vytask}`T5446` `(bug): bgp: validity check for bestpath med option` +- {vytask}`T5500` `(feature): Minor fixes to configtree render` +- {vytask}`T5469` `(default): Incorrect dependency set in the openvpn-dco package when building VyOS for arm64` +- {vytask}`T5387` `(feature): dhcp6c: add a no release option` +- {vytask}`T5491` `(feature): Hostapd - AP-Mode - allow white-/blacklisting of Clients` +- {vytask}`T4889` `(default): Add nftables NAT REDIRECT [to localhost] to CLI` + +## 2023-08-22 + +- {vytask}`T5407` `(bug): Static routes pointed to container networks fail to persist after reboot` + +## 2023-08-20 + +- {vytask}`T5470` `(bug): wlan: can not disable interface if SSID is not configured` + +## 2023-08-18 + +- {vytask}`T5488` `(bug): System conntrack ignore does not take any effect` + +## 2023-08-17 + +- {vytask}`T4202` `(bug): NFT: Zone policies fail to apply when "l2tp+" is in the interface list` +- {vytask}`T5409` `(feature): Add 'set interfaces wireguard wgX threaded'` +- {vytask}`T5476` `(feature): netplug: replace Perl helper scripts with a Python equivalent` +- {vytask}`T5223` `(bug): tunnel key doesn't clear` +- {vytask}`T5490` `(feature): login: add missing regex for home direcotry and radius server key` + +## 2023-08-16 + +- {vytask}`T5483` `(bug): Residual dhcp-server test file causing zabbix-agent smoketest to fail` + +## 2023-08-15 + +- {vytask}`T5293` `(feature): Support for Floating Rules (Global Firewall-Rules that are automatically applied before all other Zone Rules)` +- {vytask}`T5273` `(default): Add op mode commands for displaying certificate details and fingerprints` +- {vytask}`T5270` `` (default): Make OpenVPN `tls dh-params` optional `` + +## 2023-08-14 + +- {vytask}`T5477` `(bug): op-mode pki.py should use Config for defaults` +- {vytask}`T5461` `(feature): Improve rootfs directory variable` +- {vytask}`T5457` `(feature): Add environmental variable pointing to current rootfs directory` +- {vytask}`T5440` `(bug): Restore pre/postconfig scripts if user deleted them` + +## 2023-08-12 + +- {vytask}`T5467` `(bug): ospf(v3): removing an interface from the OSPF process does not clear FRR configuration` + +## 2023-08-11 + +- {vytask}`T5465` `(feature): adjust-mss: config migration fails if applied to a VLAN or Q-in-Q interface` +- {vytask}`T2665` `(bug): vyos.xml.defaults for tag nodes` +- {vytask}`T5434` `(enhancment): Replace remaining calls of vyos.xml library` +- {vytask}`T5319` `(enhancment): Remove remaining workarounds for incorrect defaults` +- {vytask}`T5464` `(feature): ipv6: add support for per-interface dad (duplicate address detection) setting` + +## 2023-08-10 + +- {vytask}`T5416` `(bug): Ignoring "ipsec match-none" for firewall` +- {vytask}`T5329` `(bug): Wireguard interface as GRE tunnel source causes configuration error on boot` + +## 2023-08-09 + +- {vytask}`T5452` `(bug): Uncaught error in generate_cache during vyos-1x build` +- {vytask}`T5443` `(enhancment): Add merge_defaults as Config method` +- {vytask}`T5435` `(enhancment): Expose utility function for default values at path` + +## 2023-08-07 + +- {vytask}`T5406` `(bug): "update webproxy blacklists" fails when vrf is being configured` +- {vytask}`T5302` `(bug): QoS class with multiple matches generates one filter rule but expects several rules` +- {vytask}`T5266` `(bug): QoS- HTB error when match with a dscp parameter for queue-type 'priority'` +- {vytask}`T5071` `(bug): QOS-Rewrite: DSCP match missing` + +## 2023-08-06 + +- {vytask}`T5420` `(feature): nftables - upgrade to latest 1.0.8` +- {vytask}`T5445` `(feature): dyndns: add possibility to specify update interval (timeout)` + +## 2023-08-05 + +- {vytask}`T5291` `(bug): vyatta-cfg-cmd-wrapper missing ${vyos_libexec_dir} variable` +- {vytask}`T5290` `(bug): Failing commits for SR-IOV interfaces using ixgbevf driver due to change speed/duplex settings` +- {vytask}`T5439` `(bug): Upgrade to FRR version 9.0 added new daemons which must be adjusted` + +## 2023-08-04 + +- {vytask}`T5427` `(bug): Change migration script len arguments checking` + +## 2023-08-03 + +- {vytask}`T5301` `(bug): NTP: chrony only allows one bind address` +- {vytask}`T5154` `(bug): Chrony - multiple listen addresses` + +## 2023-08-02 + +- {vytask}`T5374` `(feature): Ability to set 24-hour time format` +- {vytask}`T5350` `(bug): Confusing warning message when committing VRRP config` +- {vytask}`T5430` `(bug): bridge: vxlan interfaces are not listed as bridgable in completion helpers` +- {vytask}`T5429` `(bug): vxlan: source-interface is not honored and throws config error` +- {vytask}`T5415` `(feature): Upgrade FRR to version 9.0` +- {vytask}`T5422` `(feature): Support LXD Agent` + +## 2023-08-01 + +- {vytask}`T5399` `(bug): "show ntp" fails when vrf is being configured` +- {vytask}`T5346` `(bug): MPLS sysctl not persistent for L2TP interfaces` +- {vytask}`T5343` `(feature): BGP peer group VPNv4 & VPNv6 Address Family Support` +- {vytask}`T5339` `(feature): Geneve interface - option to use IPv4 as inner protocol` +- {vytask}`T5335` `(bug): ISIS: error when loading config from file` + +## 2023-07-31 + +- {vytask}`T5421` `(feature): Add arg to completion helper 'list_interfaces' to filter out vlan subinterfaces` + +## 2023-07-29 + +- {vytask}`T5403` `(feature): Add support for extending xml cache` + +## 2023-07-28 + +- {vytask}`T4602` `` (bug): DHCP `ping-check` enabled by default `` +- {vytask}`T5411` `(feature): Remove old background monitoring implementation` +- {vytask}`T5317` `(enhancment): configtree: remove mutable references` +- {vytask}`T5316` `(enhancment): configtree: use a single pass of the diff algorithm` + +## 2023-07-27 + +- {vytask}`T5368` `(feature): FastNetmon service ids ddos-protection add support sflow mode` + +## 2023-07-26 + +- {vytask}`T5398` `(bug): FRR mangles container network interface names` +- {vytask}`T5365` `(bug): Container systemd units require authentication` +- {vytask}`T4974` `(feature): OpenVPN- Data Channel Offload(DCO)` + +## 2023-07-25 + +- {vytask}`T5377` `(feature): ospf: add graceful restart FRR feature (RFC 3623)` + +## 2023-07-21 + +- {vytask}`T5373` `(bug): LLDP seems to be running even if its disabled on all interfaces` +- {vytask}`T5328` `(default): bgp: Incorrect warning showed for address-family configured with neighbor as interface` +- {vytask}`T5363` `(bug): Bash history file does not exists after reboot and ony other file in home directory` +- {vytask}`T5385` `(bug): reference_tree: catch parse error on non-transcluded files` +- {vytask}`T5361` `(bug): "monitor log" behaves like "show log"` + +## 2023-07-20 + +- {vytask}`T5362` `` (bug): `set high-availability vrrp global-parameters version 3` seems to have no effect `` +- {vytask}`T5355` `(bug): IPSec: OP cmd : "show vpn ike sa" does not show output` +- {vytask}`T5330` `(enhancment): Keep track of source of config dict value when merging defaults` +- {vytask}`T4497` `(feature): ping cannot force ipv4 or ipv6` +- {vytask}`T4288` `(bug): IPsec tunnel will break when ESP timeout` + +## 2023-07-19 + +- {vytask}`T5340` `(bug): SNMP and VRF` +- {vytask}`T5059` `(feature): add 'disable' option to DHCP relay config` + +## 2023-07-17 + +- {vytask}`T2051` `(bug): Throughput anomalies` + +## 2023-07-16 + +- {vytask}`T141` `(feature): TACACS+ Support` + +## 2023-07-15 + +- {vytask}`T5341` `(feature): Improve CLI for high-availability virtual-server to work with multiple ports` + +## 2023-07-14 + +- {vytask}`T5358` `(bug): 99-ipsec-dhclient-hook prevents DHCP stateless routes from being installed in VRF table` +- {vytask}`T4376` `(bug): DNAT with multiwan and policy routing, incoming connections only work on primary interface` +- {vytask}`T305` `(default): loadbalancing does not work with one pppoe connection and another connection of either dhcp or static` + +## 2023-07-13 + +- {vytask}`T4713` `(bug): vyos@vyos:~$ show nat destination rules | doesn't work` +- {vytask}`T2315` `(feature): Ability to have right address-family for BGP peers.` + +## 2023-07-12 + +- {vytask}`T5347` `(bug): Compare commit revision bug` +- {vytask}`T5161` `(default): BFD Static Route Monitoring` +- {vytask}`T5105` `(bug): DHCP Server - Wrong error message` +- {vytask}`T4927` `(bug): Need to change restart to reload-or-restart in Webproxy module` +- {vytask}`T3835` `(bug): vyos router 1.2.7 snmp Dos bug` +- {vytask}`T5352` `(default): Fix missing dependency for netavark` +- {vytask}`T4959` `(feature): Add container registry authentication config for containers` + +## 2023-07-11 + +- {vytask}`T5314` `(bug): QOS Default classes are not configured with correct qdisc` +- {vytask}`T4862` `(bug): webproxy domain-block does not work` +- {vytask}`T4844` `(bug): Incorrect permissions of the safeguard DB directory` +- {vytask}`T4815` `(bug): Fix various name server config issues` +- {vytask}`T4810` `(bug): Op-mode show/monitor log pppoe interface does not show any logs` +- {vytask}`T4758` `(feature): Rewrite show dhcp server to vyos.opmode format` +- {vytask}`T4262` `(bug): install image doesn't respect chosen root partition size` +- {vytask}`T3810` `(bug): webproxy squidguard rules don't work properly after rewriting to python.` +- {vytask}`T1928` `(bug): Is the 'Welcome to VyOS' message when using SSH an information leak?` +- {vytask}`T1877` `(default): Feature Request: Allow NAT to use network and address groups` +- {vytask}`T4813` `(feature): L3VPN over GRE Tunnels` +- {vytask}`T4943` `(bug): Radius SSH login displays "permission denied" on 1.4 rolling release` +- {vytask}`T4542` `(default): route-map: "match prefix-len" incorrect behavior` +- {vytask}`T4392` `(default): Multiline login banner text reports error on commit` + +## 2023-07-10 + +- {vytask}`T5345` `(bug): Error incorrectly raised in revised multi_to_list when tag node value name == tag node name` +- {vytask}`T3578` `(bug): Prefix-List(6) update cause empty prefix-list(6)` +- {vytask}`T762` `(feature): Include rulseset in firewall` + +## 2023-07-06 + +- {vytask}`T5336` `(feature): Add Swedish keyboard-layout` + +## 2023-07-04 + +- {vytask}`T5333` `(bug): Policy base routing PBR generetes incorrect rules with name POSTROUTING` +- {vytask}`T5081` `(feature): ISIS and OSPF syncronization with IGP-LDP sync` + +## 2023-07-03 + +- {vytask}`T5295` `(bug): QoS shaper incorrect rate limit the traffic` +- {vytask}`T5334` `(feature): ospf: add support for External Route Summarisation Type-5 and Type-7` + +## 2023-07-02 + +- {vytask}`T5332` `(bug): Show policy route not working when no interface is configured` + +## 2023-07-01 + +- {vytask}`T5304` `(feature): Containers add bind-propagation option rshared` +- {vytask}`T5296` `(bug): QoS class cannot calculate correctly the default bandwidth auto` +- {vytask}`T5210` `(bug): IPSec cosmetic bug for Warning vti inrerface` +- {vytask}`T5277` `(bug): Dhcpv6-relay does not start on boot` + +## 2023-06-30 + +- {vytask}`T5315` `(feature): vrrp: add support for version 3` +- {vytask}`T5283` `(bug): IPoE server assigns network address` +- {vytask}`T5313` `(bug): UDP broadcast relay - missing verify() that relay interfaces have an IP address assigned` + +## 2023-06-29 + +- {vytask}`T5320` `(enhancment): Add warning when entering config mode after a boot configuration error` + +## 2023-06-28 + +- {vytask}`T1237` `(feature): Static Route Path Monitoring, failover` + +## 2023-06-26 + +- {vytask}`T5159` `(bug): DHCPv6-server leases op-command shows warning message even if configured` + +## 2023-06-25 + +- {vytask}`T5240` `(bug): Service router-advert failed to start radvd with more then 3 name-servers` +- {vytask}`T5312` `(bug): Nonescaped special character in help text` + +## 2023-06-24 + +- {vytask}`T5303` `(bug): Rsyslog.service is not working` +- {vytask}`T5298` `(bug): Add RFKILL support into kernel.` +- {vytask}`T5308` `(enhancment): Remove workarounds for incorrect defaults in get_interface_dict` +- {vytask}`T5228` `(enhancment): Simplify get_config_dict and add argument with_defaults` +- {vytask}`T5310` `(bug): Need some help troubleshooting NIC detection.` + +## 2023-06-22 + +- {vytask}`T5297` `(default): Utility function to check if config under node has been changed between revisions` + +## 2023-06-20 + +- {vytask}`T5300` `(bug): verification of port availability can return false negative on boot` +- {vytask}`T5248` `(feature): Ability to load config via API in JSON format` + +## 2023-06-19 + +- {vytask}`T5281` `(feature): Add kernel options for vhost-net` +- {vytask}`T5072` `(default): QOS-Rewrite: protocol name used literally` +- {vytask}`T4969` `(bug): QoS Policy - Unable to set class match mark number` + +## 2023-06-18 + +- {vytask}`T5256` `(bug): QoS expects protocol number but not protocol name` + +## 2023-06-13 + +- {vytask}`T5258` `(bug): git Actions use ubuntu-22.04 instead of deprecated ubuntu-18.04 for PR conflicts checker` +- {vytask}`T5222` `(feature): Add load-balancing reverse-proxy based on haproxy` +- {vytask}`T5213` `(feature): Accel-ppp sending accounting interim updates acct-interim-interval option` +- {vytask}`T5171` `(feature): Use XML for conf-mode "load-balancing wan" instead of legacy templates` + +## 2023-06-12 + +- {vytask}`T5282` `(bug): Poweroff now does not work` +- {vytask}`T5264` `(feature): Add Mellanox Technologies firmware flash module mlxfw to kernel` +- {vytask}`T5286` `(feature): Remove XDP support` + +## 2023-06-10 + +- {vytask}`T5231` `(feature): Add op-mode for load-balancing reverse-proxy` + +## 2023-06-09 + +- {vytask}`T5253` `(bug): MPLS config removed at boot when wireguard interfaces present` + +## 2023-06-05 + +- {vytask}`T5259` `(bug): Openconnect cannot pass migration 1-to-2` + +## 2023-06-02 + +- {vytask}`T5252` `(bug): Route distinguisher and route targets changing upon adding interface to new VRF` +- {vytask}`T5251` `(bug): Uncaught errors for functions delete/delete_value in Python module configtree.py` + +## 2023-06-01 + +- {vytask}`T5127` `(bug): VPNv4/VPNv6 routes are not reinstalled following link flap` + +## 2023-05-28 + +- {vytask}`T5244` `(feature): dropbear: update to 2022.83` +- {vytask}`T5242` `(feature): interfaces: smoketest: automatically detect "capabilities"` +- {vytask}`T5234` `(feature): Add bash identifier for given VRF instance` + +## 2023-05-25 + +- {vytask}`T5237` `(feature): interfaces virtual-ethernet - Extend capabilitys of Vlans/QinQ` +- {vytask}`T4686` `(feature): Provides support for veth` + +## 2023-05-24 + +- {vytask}`T4605` `(feature): Firewall change default table names` +- {vytask}`T4550` `(feature): router-advert: Add deprecate-prefix & decrement-lifetimes options` + +## 2023-05-23 + +- {vytask}`T4916` `(feature): Rewrite IPsec authentication` + +## 2023-05-22 + +- {vytask}`T5214` `(bug): PPPoE-server incorrect warning if a named pool is defined` +- {vytask}`T4977` `(feature): Babel routing protocol support` + +## 2023-05-21 + +- {vytask}`T4733` `(default): Feature Request: dhcp server: add VRF support` +- {vytask}`T5218` `(enhancment): Revise vyos xml lib for bug fixes and extensions` + +## 2023-05-17 + +- {vytask}`T5226` `(default): Deduplicate and standardize validators and constraints for hostname and IP address` +- {vytask}`T5225` `(bug): BGP allowas-in unusable` +- {vytask}`T5208` `(bug): Failed to start nvmf-autoconnect.service during the boot` + +## 2023-05-16 + +- {vytask}`T5194` `(default): Add reference tree to vyos1x-config` + +## 2023-05-15 + +- {vytask}`T3896` `(feature): Extend ocserv support to allow for per-group configs` + +## 2023-05-12 + +- {vytask}`T2778` `(feature): Migrate "system syslog" to get_config_dict() to support new features` +- {vytask}`T2769` `(feature): Add VRF support for syslog` + +## 2023-05-10 + +- {vytask}`T5209` `(bug): dhclient load-balancing exit hook 04-dhcp-wanlb returned non-zero exit status` +- {vytask}`T5065` `` (bug): Mixing `destination port xxx` and `destination group port-group yyy` in firewall rules doesn't work, but can be commited `` +- {vytask}`T5060` `(feature): add a VRRP 'maintenance mode'` + +## 2023-05-09 + +- {vytask}`T5202` `(bug): After removal load-balancing a pid remained which used in dhclient-exit-hooks` + +## 2023-05-06 + +- {vytask}`T5206` `(bug): ethtool.py:Ethtool.__init__ has always true conditional due to typo` + +## 2023-05-05 + +- {vytask}`T5082` `(feature): container: switch to netavark network stack` + +## 2023-05-04 + +- {vytask}`T5193` `(feature): Ability to specify NS records to specify NS servers for subdomains` +- {vytask}`T3891` `(bug): X550-T2/Possibly other X550/X540 cards no link on VyOS` +- {vytask}`T5010` `(bug): bgp: EVPN route-target not honored` +- {vytask}`T5196` `(feature): wwan: op-mode should inform user if there is no WWAN interface` + +## 2023-05-03 + +- {vytask}`T5163` `(feature): Policy route-map add match source-protocol` + +## 2023-05-02 + +- {vytask}`T5042` `(bug): Command 'show vpn ipsec remote-access' does not work` + +## 2023-04-27 + +- {vytask}`T5185` `(bug): Static IPv6 route with blackhole fails` +- {vytask}`T5175` `(bug): http-api: error in MultiPart parser for FastAPI version >= 0.91.0` +- {vytask}`T5183` `(bug): IPv6 route6 problem` +- {vytask}`T5181` `(bug): Wrong dependencies or priorities for zebra vni vrf interfaces and bgpd` +- {vytask}`T5128` `(feature): Policy route - Allow wildcard interfaces` +- {vytask}`T5055` `(feature): Firewall - Add packet type matcher (pkttype)` +- {vytask}`T5050` `(feature): Firewall - Add options for logging packets` +- {vytask}`T5037` `(feature): Firewall - Add queue action` +- {vytask}`T5176` `(bug): http-api: update vyos-http-api-tools for FastAPI security vulnerability` +- {vytask}`T5174` `(bug): vrf: ensure no duplicate VNIs can be created` +- {vytask}`T5123` `(default): Display route originator in show ospf table command` + +## 2023-04-25 + +- {vytask}`T5179` `(bug): multi nodes defined in XML are not properly represented as list in get_config_dict()` + +## 2023-04-17 + +- {vytask}`T5052` `(bug): Error displaying dhcpv6 prefix delegation leases` +- {vytask}`T5150` `(feature): Rework CLI definitions to apply route-maps between routing daemons and zebra/kernel` +- {vytask}`T3734` `(bug): Move EVPN VRF up in FRR config` + +## 2023-04-13 + +- {vytask}`T5152` `(bug): Telegraf agent hostname isn't qualified` +- {vytask}`T4727` `(feature): Add RADIUS rate limit support to PPTP server` +- {vytask}`T4939` `(bug): VRRP command no-preempt not work as expected` +- {vytask}`T4791` `(default): Consistent normalization of 'raw' output of op-mode scripts for CLI and API` +- {vytask}`T3608` `(default): Standardize warnings from configure scripts` + +## 2023-04-11 + +- {vytask}`T4924` `(bug): Systemctl strongswan.service for some reason is not disabled` +- {vytask}`T4197` `(bug): Vyos arm64-latest build issue with telegraf pkg` +- {vytask}`T4051` `(bug): Connected routes strange / not working` + +## 2023-04-10 + +- {vytask}`T5151` `(bug): EAP-TLS TLSv1.0/1.1 regression after T5003` +- {vytask}`T5148` `(bug): OpenVPN cannot start due to could not load plugin shared object /openvpn-otp.so` +- {vytask}`T5110` `(bug): Show frr op-mode vtysh_pam: Failed in account validation` +- {vytask}`T5078` `(feature): VyOS BGP does not support 'show bgp neighbors $NB filtered-routes'` +- {vytask}`T5070` `(feature): show bgp nexthop unavailable in VRF` +- {vytask}`T5061` `(bug): All containers restart on config change` + +## 2023-04-07 + +- {vytask}`T5149` `(bug): op-mode openvpn should not raise error in case interface is disabled` + +## 2023-04-06 + +- {vytask}`T5147` `(bug): Can't Commit with Container Network` +- {vytask}`T5142` `(feature): One of the requirements is to use a system auditing tool to monitor and log all security-relevant events.` +- {vytask}`T5125` `(feature): Add op-mode commands for hsflowd based sflow` + +## 2023-04-05 + +- {vytask}`T5145` `(feature): Add maxsyslogins maximum number of all logins on system` +- {vytask}`T5135` `(default): Rewrite opennhrp script using vyos.ipsec library` +- {vytask}`T4975` `(bug): CLI does not work after cutting off the power or reset` +- {vytask}`T5136` `(bug): Possible config corruption on upgrade` + +## 2023-04-04 + +- {vytask}`T5141` `(feature): Add numbers for dhclient-exit-hooks.d to enforce script order execution` +- {vytask}`T5093` `(bug): Command 'reset vpn ipsec-profile' doesn't work` +- {vytask}`T4362` `(bug): Wan Load Balancing - Can't create routing tables` + +## 2023-04-03 + +- {vytask}`T5139` `(feature): IKE life-time should start from 0 for disable rekey` +- {vytask}`T4173` `(bug): Wan Load Balancing - Error on firewall NAT rules` + +## 2023-04-02 + +- {vytask}`T5134` `(feature): Try if netavark networks can be moved to a VRF instance` + +## 2023-04-01 + +- {vytask}`T5047` `(bug): Recreate only a specific container` +- {vytask}`T5132` `(default): Operational command "show isis vrf XXX route | neighbord" aren't working` + +## 2023-03-31 + +- {vytask}`T5129` `(feature): Add AWS build flavour` +- {vytask}`T5126` `(feature): http-api: add 'allow-client' to restrict IP address of client connections` + +## 2023-03-30 + +- {vytask}`T5130` `(bug): op-mode: drop remaining reference to obsoleted 'show_interfaces.py'` +- {vytask}`T4866` `(feature): Rewrite show_interfaces to standardized form` +- {vytask}`T366` `(bug): SNMP Query for BGP Tunnels Returns IPv4 Tunnels Only` + +## 2023-03-29 + +- {vytask}`T5100` `(feature): Update FRR to 8.5` +- {vytask}`T5094` `(bug): FRR systemd logs unknow key LimitNOFILESoft` +- {vytask}`T5085` `(bug): ospfv3 route-map not applied in FRR configuration` +- {vytask}`T5056` `(bug): IPoE server vlan-mon is not working` +- {vytask}`T5033` `(bug): generate-public-key command fails for address with multiple public keys like GitHub` +- {vytask}`T4876` `(bug): mpls - LSP broken on FRR 8.4.1` +- {vytask}`T5097` `(bug): the operational command "show interfaces ethernet ethx" doesn't reflect a call to 'clear counters'` +- {vytask}`T5089` `(enhancment): Add unit test of config_diff` +- {vytask}`T5088` `(enhancment): Add lexicographical-numeric compare function for vytree/configtree` +- {vytask}`T5087` `(enhancment): Add support for lexical ordering of nodes in config_tree` +- {vytask}`T4885` `(feature): Rewrite 'clear interfaces counters' from Perl to Python` +- {vytask}`T4846` `(bug): L3VPN- network command doesn't install direct connected prefix` + +## 2023-03-28 + +- {vytask}`T5043` `(feature): Need to create reset command for IKEv2 remote-access vpn connections` + +## 2023-03-27 + +- {vytask}`T5099` `(feature): IPoE server add option 'next-pool' for named ip pools` +- {vytask}`T5106` `(feature): Extend generation of API client requests to configsession native functions and composite requests` +- {vytask}`T5104` `(bug): DHCP default route issues with static routes in VRFs` +- {vytask}`T5079` `(feature): xml: schema extension to support defaultValues on tagNodes` +- {vytask}`T5114` `(feature): bgp: implement new CLI commands introduced in FRR 8.5` + +## 2023-03-23 + +- {vytask}`T5108` `(feature): Get rate limit for L2TP/PPTP/SSTP/IPoE in raw format` +- {vytask}`T5086` `(feature): Integrate hsflowd for sflow accounting` +- {vytask}`T5107` `(bug): Raise error in op-mode dns.py instead of calling exit` + +## 2023-03-22 + +- {vytask}`T5068` `(feature): Generate op-mode API client requests along with schema generation` + +## 2023-03-21 + +- {vytask}`T5098` `(feature): PPPoE client holdoff configuration` +- {vytask}`T3694` `(bug): Static routes not installed into kernel nor frr` +- {vytask}`T5102` `(feature): ospf: "redistribute babel" is always set` + +## 2023-03-20 + +- {vytask}`T5057` `(bug): IPoE server incorrect interface regex` +- {vytask}`T5095` `(feature): Return list instead of dict for 'raw' output of op-mode openvpn` + +## 2023-03-19 + +- {vytask}`T4925` `(feature): Need to add the possibility to configure Pseudo-Random Functions (PRF) in IKEv2` + +## 2023-03-17 + +- {vytask}`T5092` `(bug): IPoE-server named pool must not rely on the authentication type` +- {vytask}`T5091` `(bug): IPoE server with RADIUS authentication does not verify radius configuration` + +## 2023-03-16 + +- {vytask}`T5073` `(bug): IPoE-server interface option failed to parse` +- {vytask}`T5063` `(bug): IPoE-server ethX vlan must not be used with client-subnet` +- {vytask}`T5058` `(feature): Extend template filter range_to_regex` +- {vytask}`T3083` `(feature): Add feature event-handler` +- {vytask}`T2516` `(bug): vyos-container: cannot configure ethernet interface` + +## 2023-03-13 + +- {vytask}`T5074` `(bug): Show IPSEC SA failed if remote access IKEv2 vpn is used.` +- {vytask}`T4973` `(bug): show dhcp server leases error for lease time 4294967295` + +## 2023-03-11 + +- {vytask}`T5076` `(feature): CI/CD: Docker container is bloated by legacy and conflicting dependencies` + +## 2023-03-09 + +- {vytask}`T5066` `(bug): Different GRE tunnel but same tunnel keys error` +- {vytask}`T4952` `(feature): Improve interface completion helper CLI experience` + +## 2023-03-08 + +- {vytask}`T4381` `(default): OpenVPN: Add "Tunnel IP" column in "show openvpn server" operational command` +- {vytask}`T4872` `(bug): Op-mode show openvpn misses a case when parsing for tunnel IP` + +## 2023-03-07 + +- {vytask}`T2838` `(bug): Ethernet device names changing, multiple hw-id being added` +- {vytask}`T5051` `(feature): Use Literal types to provide op-mode CLI choices and API enums` +- {vytask}`T4900` `(default): Cache intermediary results of get_config_diff in Config instance` + +## 2023-03-05 + +- {vytask}`T5040` `(default): Generate API GraphQL schema on installation, rather than dynamically` + +## 2023-03-03 + +- {vytask}`T4625` `(enhancment): Update ocserv to current revision (1.1.6)` + +## 2023-03-02 + +- {vytask}`T4967` `(feature): Ability to set hostname for the container` + +## 2023-03-01 + +- {vytask}`T5015` `(bug): Invalid format character error at hfsc class settings help text` + +## 2023-02-28 + +- {vytask}`T5029` `(feature): Nginx change default root directory and fix regex` +- {vytask}`T5025` `(bug): Time-zone validation failed` +- {vytask}`T4955` `(bug): Openconnect radiusclient.conf generating with extra authserver` +- {vytask}`T4843` `(feature): Command-line arguments in container config` +- {vytask}`T4219` `(feature): support incoming-interface (iif) in local PBR` +- {vytask}`T3903` `(bug): Containers: after command "reboot" the host system will reboot after 1.5 minutes` + +## 2023-02-27 + +- {vytask}`T5028` `(feature): Add package exfatprogs to VyOS` +- {vytask}`T4985` `(bug): reset vpn ipsec-peer command with peer name does not work` + +## 2023-02-26 + +- {vytask}`T4979` `(feature): Add API request 'show_user_info' for UI` + +## 2023-02-25 + +- {vytask}`T5008` `(bug): MACsec CKN of 32 chars is not allowed in CLI, but works fine` +- {vytask}`T5007` `(bug): Interface multicast setting is invalid` +- {vytask}`T5027` `(bug): OpenVPN options and site-to-site cannot pass smoketest` +- {vytask}`T4978` `(bug): KeyError: 'memory' container_config['memory'] on upgrading to 1.4-rolling-202302041536` +- {vytask}`T5034` `(bug): Migrate multicast CLI node to valueLess` +- {vytask}`T4948` `(feature): pppoe: add CLI option to allow definition of host-uniq flag` + +## 2023-02-24 + +- {vytask}`T5030` `(bug): HTTPS-API delete key without id error` + +## 2023-02-23 + +- {vytask}`T5013` `(feature): Extend accelppp.py op-mode to get subnet start stop info from config` +- {vytask}`T5002` `(feature): Add uk (United Kingdom) keymap` + +## 2023-02-22 + +- {vytask}`T5024` `(bug): check-qemu-install VM is not shutdown the first time` +- {vytask}`T5011` `(bug): Some interface drivers don't support min_mtu and max_mtu and verify_mtu check should be skipped` + +## 2023-02-21 + +- {vytask}`T5021` `(bug): IPsec SA is closed before negotiating a new one or it is negotiated on every second if big life-time is set in swanctl.conf` +- {vytask}`T5020` `(feature): Extend openvpn.py op-mode to get a list of configured clients` + +## 2023-02-20 + +- {vytask}`T5005` `(feature): Skip user authentication for PPPoE Server with noauth option` + +## 2023-02-16 + +- {vytask}`T4971` `(feature): Radius attribute "Framed-Pool" for PPPoE` + +## 2023-02-15 + +- {vytask}`T4991` `(bug): Restore path level information to compare output` + +## 2023-02-14 + +- {vytask}`T4968` `(bug): VPN IPsec check dpd and close action for empty values` +- {vytask}`T1993` `(feature): Extended pppoe rate-limiter` + +## 2023-02-13 + +- {vytask}`T4905` `(feature): Convert show nhrp tunnel to tabulate format` +- {vytask}`T4153` `(bug): Monitor bandwidth-test initiate not working` + +## 2023-02-12 + +- {vytask}`T4998` `(bug): pppoe username validation too restrictive (regression)` + +## 2023-02-11 + +- {vytask}`T2603` `(feature): pppoe-server: reduce min MTU` + +## 2023-02-10 + +- {vytask}`T4857` `(feature): SNMP - Implement FRR SNMP recommendations` +- {vytask}`T4995` `(feature): pppoe, wwan and sstp-client - rename user -> username on authentication` + +## 2023-02-07 + +- {vytask}`T4980` `(bug): chrony not listening as a server` +- {vytask}`T4868` `(bug): L2TP ppp-options ipv6 does not work without ipv6 pool but should` +- {vytask}`T4117` `(bug): Does not possible to configure PoD/CoA for L2TP vpn` + +## 2023-02-01 + +- {vytask}`T4970` `(default): pin OCaml pcre package to avoid JIT support` + +## 2023-01-31 + +- {vytask}`T4964` `(bug): FRR bgp address-family l2vpn-evpn route-target export/import not working` +- {vytask}`T4780` `(feature): Firewall - Add interface group` +- {vytask}`T4157` `(default): Add jinja2 to pip test requirements` + +## 2023-01-30 + +- {vytask}`T4958` `(feature): Add OpenConnect RADIUS Accounting support` +- {vytask}`T4954` `(bug): DNS cannot be configured via Network-Config v1 received from ConfigDrive / Cloud-Init` +- {vytask}`T4118` `(default): IPsec syntax overhaul` + +## 2023-01-29 + +- {vytask}`T4965` `(default): empty description in firewall group causes configuration error on migration` + +## 2023-01-28 + +- {vytask}`T4961` `(bug): Uncaught configtree error allows ntp migration 1-to-2 to fail silentlly on config.boot.default` + +## 2023-01-27 + +- {vytask}`T4960` `` (bug): Bugs in `cc_vyos.py` code (Cloud-Init) `` + +## 2023-01-26 + +- {vytask}`T4886` `(feature): Firewall and Policy - Add connection mark` +- {vytask}`T4957` `(bug): config-mgmt should not attempt to archive config at boot` +- {vytask}`T4962` `(bug): Fix typo in regex in vyos.config_mgmt compare function` +- {vytask}`T4912` `(default): Rewrite the IGMP op mode in the new style` + +## 2023-01-25 + +- {vytask}`T4941` `(bug): Accel-ppp IPoE incompatibility with kernel 6.1` + +## 2023-01-24 + +- {vytask}`T4947` `(feature): Support mounting container volumes as ro or rw` + +## 2023-01-23 + +- {vytask}`T4798` `(default): Migrate the file-exists validator away from Python` +- {vytask}`T4683` `(enhancment): Add kitty-terminfo package to build` +- {vytask}`T4953` `(bug): Remove convert_kwargs_to_snake_case decorator in dynamic generation of GraphQL resolvers` +- {vytask}`T4875` `(default): Replace Python validator 'interface-name' to avoid Python startup cost` +- {vytask}`T4664` `(bug): Add validation to reject whitespace in tag node value names` + +## 2023-01-22 + +- {vytask}`T4906` `(bug): ipsec connections shows only one connection as up` + +## 2023-01-21 + +- {vytask}`T4799` `(bug): PowerDNS >= 4.7 does not get reloaded by vyos-hostsd` +- {vytask}`T4878` `(bug): Any interface bonding changes cause interface flapping` +- {vytask}`T4387` `(default): Create additional smoketests for multiwan PBR & load-balanced configurations` + +## 2023-01-20 + +- {vytask}`T4551` `(bug): IPsec rekeying collisions bug` +- {vytask}`T4942` `(feature): Rewrite vyatta-config-mgmt to Python/XML` + +## 2023-01-17 + +- {vytask}`T4938` `(bug): Interface input ifb does not work` +- {vytask}`T4902` `(bug): snmpd: exclude container storage from monitoring` +- {vytask}`T4140` `(bug): Lack of SNMP IANA mibs` + +## 2023-01-15 + +- {vytask}`T4832` `(feature): dhcp: Add IPv6-only dhcp option support (RFC 8925)` +- {vytask}`T4937` `(feature): ocserv: upgrade package to version 1.1.6` +- {vytask}`T4918` `(bug): Odd show interface behavior` +- {vytask}`T3008` `(feature): Migrate from ntpd to chronyd` + +## 2023-01-13 + +- {vytask}`T4911` `(default): Rewrite the LLDP op mode in the new format` +- {vytask}`T4928` `(feature): Upgrade Linux Kernel to 6.1.y (2022 LTS edition)` + +## 2023-01-12 + +- {vytask}`T4934` `(bug): ospf: Fix inter-area route summarization` +- {vytask}`T4929` `(feature): Update Intel QAT drivers to 4.20.0-00001` + +## 2023-01-10 + +- {vytask}`T4880` `(feature): Expose 'add/delete container image' in HTTP-API` + +## 2023-01-09 + +- {vytask}`T4922` `(feature): Add ssh-client source-interface CLI option` +- {vytask}`T4524` `(bug): Squid webproxy not working properly` + +## 2023-01-08 + +- {vytask}`T4920` `` (bug): ospf: Fix `passive-interface default` option `` + +## 2023-01-07 + +- {vytask}`T4884` `(bug): Missing a community6 in snmpd config` + +## 2023-01-05 + +- {vytask}`T4904` `(feature): Allow multiple ports for high-availability virtual-server` +- {vytask}`T4789` `(feature): Ability to get L2TP/PPTP/SSTP sessions info in a machine readable format` +- {vytask}`T3937` `(default): Rewrite "show system memory" in Python to make it usable as a library function` + +## 2023-01-04 + +- {vytask}`T4848` `(bug): Minor bug in OpenConnect server with default route` +- {vytask}`T4656` `(feature): Support the listen-host config field of openconnect server` + +## 2023-01-03 + +- {vytask}`T4907` `(bug): nat source translations couldn't show metrics` + +## 2023-01-02 + +- {vytask}`T4893` `(feature): l2tp add ppp-options IPv6 interface identifier` +- {vytask}`T4717` `(feature): Connect to console server by name` +- {vytask}`T725` `(feature): Cake and FQ-PIE` + +## 2022-12-31 + +- {vytask}`T4898` `(feature): Add mtu config option for dummy interfaces` + +## 2022-12-30 + +- {vytask}`T4834` `(bug): Limit container network name to 15 characters` +- {vytask}`T4901` `(bug): Update Podman to v4.3.1` +- {vytask}`T4899` `(bug): Podman systemd services not being installed correctly` + +## 2022-12-28 + +- {vytask}`T4593` `(feature): Upgrade strongswan to 5.9.8` + +## 2022-12-26 + +- {vytask}`T4511` `(bug): IPv6 DNS lookup` +- {vytask}`T4809` `(feature): radvd: Allow use of AdvRASrcAddress` + +## 2022-12-25 + +- {vytask}`T3579` `(feature): Rewrite vyatta-conntrack in new XML and Python flavour` + +## 2022-12-24 + +- {vytask}`T4890` `(bug): show conntrack table ipv4 fail` +- {vytask}`T4879` `(bug): IPSec migration failed with missing remote-id` +- {vytask}`T4870` `(feature): Containers switch to using overlay driver for podman storage` + +## 2022-12-23 + +- {vytask}`T4792` `(feature): Add SSTP VPN client` + +## 2022-12-21 + +- {vytask}`T4887` `(bug): Schema generation from op-mode functions should set default 'false' on boolean arguments` + +## 2022-12-18 + +- {vytask}`T4882` `(bug): Missing ICMPv6 type names in firewall configuration` + +## 2022-12-15 + +- {vytask}`T4671` `(bug): linux-firmware package is missing symlinks defined in WHENCE file` + +## 2022-12-14 + +- {vytask}`T4881` `(bug): Return opmode.Error on openconnect.py show_sessions` + +## 2022-12-12 + +- {vytask}`T4861` `(feature): Openconnect restart on adding users - Aborts all active connections` + +## 2022-12-09 + +- {vytask}`T4865` `(bug): container impossible to generate local image from a file if it requires install some pkgs` + +## 2022-12-05 + +- {vytask}`T4860` `(bug): Openconnect server incorrect unconfigured check` +- {vytask}`T4804` `(bug): PPPoE server incorrect unconfigured check` +- {vytask}`T4854` `(feature): BGP-route reflector allows to apply route-maps` + +## 2022-12-04 + +- {vytask}`T4825` `(feature): interfaces veth/veth-pairs -standalone used` +- {vytask}`T4805` `(bug): PPPoE server does not restart service if pool was changed` + +## 2022-12-02 + +- {vytask}`T4830` `(bug): nat66 - Error in port translation rules` +- {vytask}`T4859` `(bug): Correct calling of config mode script dependencies from http-api.py` +- {vytask}`T4820` `(enhancment): Support for inter-config-mode script dependencies` +- {vytask}`T4858` `(bug): L3VPN- Route Distinguisher notations` +- {vytask}`T1024` `(feature): Policy Based Routing by DSCP` + +## 2022-12-01 + +- {vytask}`T4841` `(feature): add fan control` +- {vytask}`T4847` `(bug): Correct calling of config mode script dependencies from pki.py` + +## 2022-11-29 + +- {vytask}`T4842` `(bug): Routing config broken if mpls config exists` +- {vytask}`T4845` `(default): Add smoketest to detect cycles in config-mode script dependency calls` + +## 2022-11-27 + +- {vytask}`T4739` `(feature): ISIS and OSPF segment routing being refactored` + +## 2022-11-24 + +- {vytask}`T4794` `(bug): show firewall name <name> - Can't use .items() on a list` +- {vytask}`T4714` `(feature): Delete unused ipset from the filecaps` +- {vytask}`T3541` `(bug): Route Map large community set additive is missing` + +## 2022-11-23 + +- {vytask}`T4836` `(feature): Kernel: enable new features like switchdev, ESP in TCP and HSR` +- {vytask}`T4835` `(bug): SNMPD configuration incorrect for IPv6` +- {vytask}`T4819` `(feature): Allow printing Warning messages in multiple lines with \n` +- {vytask}`T4807` `(feature): Need to fix traceroute help completion` +- {vytask}`T4660` `(feature): Reorganize route map set community CLI` +- {vytask}`T4526` `(bug): keepalived-fifo.py unable to load config` +- {vytask}`T4793` `(feature): Create warning message about disable-route-autoinstall when ipsec vti is used` +- {vytask}`T4492` `(bug): Incorrect list of neighbors in help for "show bgp vrf VRF neighbors"` +- {vytask}`T4496` `(feature): ping vrf help does not list VRFs` + +## 2022-11-22 + +- {vytask}`T4823` `(bug): swanctl.conf is broken when ipsec site-to-site peer set.` +- {vytask}`T4706` `(bug): NAT and NAT66 issues` +- {vytask}`T4670` `(feature): policy route - Update matching criteria` + +## 2022-11-21 + +- {vytask}`T4812` `(feature): IPsec ability to show all configured connections` +- {vytask}`T4829` `(default): Tunnel argument to 'reset_peer' in ipsec.py should have type hint Optional` + +## 2022-11-20 + +- {vytask}`T4827` `(bug): route-map issues , not load configuration FRR` + +## 2022-11-19 + +- {vytask}`T4826` `(bug): Wrong key type is used for SSH SK public keys` +- {vytask}`T4720` `(feature): Ability to configure SSH HostKeyAlgorithms` +- {vytask}`T4828` `(default): Raise appropriate op-mode errors in ipsec.py 'reset_peer'` + +## 2022-11-18 + +- {vytask}`T4821` `(bug): Correct calling of config mode script dependencies from firewall.py` + +## 2022-11-17 + +- {vytask}`T4750` `(feature): Support of higher level SSH keys (sk-ssh-ed25519)` + +## 2022-11-15 + +- {vytask}`T4808` `(feature): Add details of configtree operations to migration log` + +## 2022-11-12 + +- {vytask}`T4814` `(bug): Regression in bundled powerdns version` + +## 2022-11-09 + +- {vytask}`T4800` `(bug): undefined var includes_chroot_dir in build-vyos-image` + +## 2022-11-08 + +- {vytask}`T4771` `(feature): Rewrite protocol BGP op-mode to vyos.opmode format` +- {vytask}`T4806` `(default): Update FRR to 8.4 in 1.4 version` + +## 2022-11-06 + +- {vytask}`T4803` `(bug): The header 'Authorization' needs to be explictly allowed in http-api CORS middleware` + +## 2022-11-05 + +- {vytask}`T4802` `(feature): Ability to define per container shared-memory size` + +## 2022-11-01 + +- {vytask}`T4764` `(bug): NAT tables vyos_nat and vyos_static_nat not deleting after deleting nat` +- {vytask}`T4177` `(bug): Strip-private doesn't work for service monitoring` + +## 2022-10-31 + +- {vytask}`T4786` `(feature): Add package python3-pyhumps` +- {vytask}`T1875` `(feature): Add the ability to use network address as BGP neighbor (bgp listen range)` +- {vytask}`T4785` `(feature): snmp: Allow !, @, * and # in community name` +- {vytask}`T4787` `(feature): ipsec: add support for road-warrior/remote-access RADIUS timeout` + +## 2022-10-29 + +- {vytask}`T4783` `(default): Add support for stunnel` +- {vytask}`T4784` `(feature): Add description node for static route/route6 tagNodes` + +## 2022-10-28 + +- {vytask}`T4291` `(default): Consolidate component version read/write functions` + +## 2022-10-27 + +- {vytask}`T4763` `(feature): Change XML for Show nat destination statistics` +- {vytask}`T4762` `(bug): Show nat rules with empty rules incorrect error` +- {vytask}`T4778` `(bug): Raise error UnconfiguredSubsystem if op-mode ipsec.py fails initialization` + +## 2022-10-26 + +- {vytask}`T4773` `(default): Add camel_case to snake_case conversion utility` + +## 2022-10-25 + +- {vytask}`T4574` `(default): Add token based authentication to GraphQL API` + +## 2022-10-24 + +- {vytask}`T4772` `(default): Return list of dicts in 'raw' output of route.py instead of dict with redundant information` + +## 2022-10-23 + +- {vytask}`T3723` `(bug): op-mode IPSec show vpn ipsec sa output with underscores` + +## 2022-10-21 + +- {vytask}`T4768` `(default): Change name of api child node from 'gql' to 'graphql'` + +## 2022-10-18 + +- {vytask}`T4684` `(feature): Rewrite show ip route by protocol to vyos.opmode format` +- {vytask}`T4533` `(bug): Radius clients don’t have simple permissions` +- {vytask}`T4753` `(enhancment): Extend automatic generation of schema to query SystemStatus` + +## 2022-10-17 + +- {vytask}`T4725` `(bug): Unable to reset vpn IPsec peer` + +## 2022-10-14 + +- {vytask}`T4672` `(bug): RADIUS server disable does not work` +- {vytask}`T4749` `(enhancment): Use config_dict for conf_mode http-api.py` + +## 2022-10-13 + +- {vytask}`T4746` `(bug): Monitoring nft. table vyos_filter by default does not exist but telegraf checks this table` +- {vytask}`T4744` `(bug): BGP directly connected neighbors don't compatible with ebgp-multihop` +- {vytask}`T4716` `(feature): SSH ability to configure RekeyLimit` +- {vytask}`T4343` `(default): Expose powerdns network-timeout for service dns forwarding` +- {vytask}`T4312` `(bug): Telegraf configuration doesn't accept IPs for URL` +- {vytask}`T4274` `(default): Extend OpenConnect RADIUS Timeout to Permit 2FA Entry` + +## 2022-10-12 + +- {vytask}`T4747` `(bug): Monitoring influxdb template input exec plugin does not work` +- {vytask}`T4740` `(bug): Show conntrack table ipv6 fail` +- {vytask}`T4730` `(bug): Conntrack-sync error - listen-address is not the correct type in config as it should be` + +## 2022-10-11 + +- {vytask}`T4742` `(bug): Autocomplete in policy route rule x set table / does not show the tables created in the static protocols` +- {vytask}`T4741` `(bug): set firewall zone Local local-zone failed` +- {vytask}`T4680` `(bug): Telegraf prometheus-client listen-address invalid format` + +## 2022-10-10 + +- {vytask}`T538` `(feature): Support for network mapping in NAT` + +## 2022-10-09 + +- {vytask}`T4738` `(enhancment): Extend automatic generation of schema definition files to native configsession functions; use single resolver/directive` + +## 2022-10-08 + +- {vytask}`T4707` `(feature): Enable OSPF segment routing` + +## 2022-10-07 + +- {vytask}`T4736` `(bug): Error on JSON output of API query ShowConfig` + +## 2022-10-04 + +- {vytask}`T4708` `(bug): 'show nat destination rules' throwing an error` +- {vytask}`T4700` `(feature): Firewall - Add interface match criteria` +- {vytask}`T4699` `(feature): Firewall - Add jump action - Add return action` +- {vytask}`T4651` `(feature): Firewall - Add options to match packet size` +- {vytask}`T4702` `(bug): Wireguard peers configuration is not synchronized with CLI` +- {vytask}`T4685` `(bug): Interface does not exist on boot when used as inbound-interface for local policy route` +- {vytask}`T4652` `(feature): Upgrade PowerDNS recursor to 4.7 series` +- {vytask}`T4582` `(default): Router-advert: Preferred lifetime cannot equal valid lifetime in PIOs` + +## 2022-09-29 + +- {vytask}`T4715` `(feature): Auto logout user after a period of inactivity` +- {vytask}`T4697` `(bug): policy route: Generating ConfigError failes when tcp flag is missing on set tcp-mss rule commit` + +## 2022-09-27 + +- {vytask}`T4711` `(feature): Ability to terminate user TTY and PTS sessions` +- {vytask}`T4557` `(feature): fastnetmon: allow configure limits per protocol (tcp, udp, icmp)` + +## 2022-09-21 + +- {vytask}`T4678` `(feature): Rewrite service ipoe-server to get_config_dict` +- {vytask}`T4703` `(feature): accel-ppp: combine vlan-id and vlan-range into single CLI node` + +## 2022-09-20 + +- {vytask}`T4693` `(bug): ISIS segment routing was broken...` + +## 2022-09-17 + +- {vytask}`T4666` `(bug): EAP-TLS no longer allows TLSv1.0 after T4537, T4584` +- {vytask}`T4665` `(bug): Keepalived cannot use same VRID for VRRPv2 and VRRPv3` + +## 2022-09-16 + +- {vytask}`T4698` `(enhancment): Drop validator name="range" and replace it with numeric` +- {vytask}`T4695` `(feature): Add 'es' and 'jp106' keymap option keyboard-layout` +- {vytask}`T4669` `(enhancment): Extend numeric.ml for inversion of values and range values` + +## 2022-09-15 + +- {vytask}`T4679` `(bug): OpenVPN site-to-site incorrect check for IPv6 local and remote address` +- {vytask}`T4691` `(feature): Upgrade Linux Kernel to latest 5.15.y train` +- {vytask}`T4630` `(bug): Prevent attempts to use the same interface as a source interface for pseudo-ethernet and MACsec at the same time` +- {vytask}`T4696` `(default): Extend bgp parameters for bgp bestpath peer-type multipath-relax` + +## 2022-09-12 + +- {vytask}`T4617` `(feature): VRF specification is needed for telegraf prometheus-client listen-address <address>` +- {vytask}`T4690` `(bug): Update GraphQL resolver for 'SystemStatus' following changes to 'show_uptime' op-mode script` +- {vytask}`T4647` `(feature): Add Google Virtual NIC (gVNIC) support` +- {vytask}`T4170` `(feature): Rename "policy ipv6-route" -> "policy route6"` + +## 2022-09-09 + +- {vytask}`T4682` `(feature): Rewrite 'show system storage' in standardized format` +- {vytask}`T4681` `(feature): Complete standardization of show_uptime.py` + +## 2022-09-06 + +- {vytask}`T4640` `(enhancment): Integrate op-mode exception hierarchy into API` +- {vytask}`T4597` `(bug): Check bind port before assign service HTTPS API and openconnect` +- {vytask}`T4674` `(bug): API should show op-mode error message, if present` +- {vytask}`T4673` `(bug): op-mode bridge.py should raise error on show_fdb for nonexistent bridge interface` + +## 2022-09-05 + +- {vytask}`T4668` `(bug): Adding/removing members from bond doesn't work/results in incorrect interface state` +- {vytask}`T4663` `(bug): Interface pseudo-ethernet does not change mode` +- {vytask}`T4655` `(bug): Firewall in 1.4 sets the default action 'accept' instead of 'drop'` +- {vytask}`T4628` `(bug): ConfigTree() throws ValueError() if tagNode contains whitespaces` + +## 2022-09-01 + +- {vytask}`T4606` `(bug): monitor nat destination translation shows missing script` +- {vytask}`T4435` `(bug): Policy route and firewall - error when using undefined group` +- {vytask}`T4147` `(bug): New Firewall Implementation - proposed changes on group implementation` + +## 2022-08-31 + +- {vytask}`T4650` `(feature): Rewire show nat translation to vyos.opmode format` +- {vytask}`T4644` `(bug): Check bind port before assign vpn sstp` +- {vytask}`T4643` `(bug): Smoketest exclude either sstp or openconnect from pki-misc default listen port` +- {vytask}`T4569` `(feature): Rewrite show bridge to new format` +- {vytask}`T4547` `(bug): Show vpn ipsec sa show unexpected prefix 'B' in packets` +- {vytask}`T4367` `(bug): NAT - Config tmp file not available` + +## 2022-08-29 + +- {vytask}`T4645` `(bug): show nat source statistics lack argument --family` +- {vytask}`T4634` `(bug): Bgp neighbor disable-connected-check does not work` +- {vytask}`T4631` `(feature): Add port and protocol to nat66` +- {vytask}`T4623` `(feature): Add show conntrack statistics` +- {vytask}`T4595` `(bug): DPD interval and timeout do not work in DMVPN` +- {vytask}`T4594` `(feature): Rewrite op-mode IPsec to vyos.opmode format` +- {vytask}`T4508` `(bug): Problem with values of the same environment in different event handlers` +- {vytask}`T4653` `(bug): Interface offload options are not applied correctly` +- {vytask}`T4546` `(bug): Does not connect Cisco spoke to VyOS hub.` +- {vytask}`T4061` `(default): Add util function to check for completion of boot config` +- {vytask}`T4654` `(bug): RPKI cache incorrect description` +- {vytask}`T4572` `(bug): Add an option to force interface MTU to the value received from DHCP` + +## 2022-08-26 + +- {vytask}`T4642` `(bug): proxy: hyphen not allowed in proxy URL` + +## 2022-08-25 + +- {vytask}`T4626` `(bug): Error showing nat66 source and destination` +- {vytask}`T4622` `(feature): Firewall allow drop packets by TCP MSS size` + +## 2022-08-24 + +- {vytask}`T4641` `(bug): prefix-list allows ipv6 prefix as input` +- {vytask}`T4633` `(feature): Change keepalived to v2.2.7` + +## 2022-08-23 + +- {vytask}`T4618` `(bug): Traffic policy not set on virtual interfaces` +- {vytask}`T4538` `(bug): Macsec does not work correctly when the interface status changes.` + +## 2022-08-22 + +- {vytask}`T4089` `(bug): Show nat destination rules shows ip address instead of interface 'any'` +- {vytask}`T4632` `(bug): VLAN-aware bridge not working` +- {vytask}`T4637` `(feature): Upgrade to podman 4.2.0` + +## 2022-08-20 + +- {vytask}`T4596` `(bug): "show openconnect-server sessions" command does not work in the openconnect module` + +## 2022-08-19 + +- {vytask}`T4620` `(bug): UPnP does not work due to incorrect template` +- {vytask}`T4619` `(bug): Static arp is not set if another entry is present` +- {vytask}`T4611` `(bug): UPnP rule IP should be a prefix instead of an address` +- {vytask}`T4614` `(feature): OpenConnect split-dns directive` + +## 2022-08-18 + +- {vytask}`T4613` `(bug): UPnP configuration without listen option fail` +- {vytask}`T4570` `(bug): Exception when trying to set up VXLAN over Wireguard` + +## 2022-08-17 + +- {vytask}`T4598` `(feature): nat66 - Add exclude options` +- {vytask}`T4480` `(default): add an ability to configure squid acl safe ports and acl ssl safe ports` + +## 2022-08-16 + +- {vytask}`T4592` `(bug): macsec: can not create two interfaces using the same source-interface` +- {vytask}`T4584` `(bug): hostap: create custom package build` +- {vytask}`T4413` `(default): Add an API endpoint with basic system stats` +- {vytask}`T4537` `(bug): MACsec not working with cipher gcm-aes-256` + +## 2022-08-15 + +- {vytask}`T4609` `(bug): Unable to Restart Container VyOS 1.4` +- {vytask}`T4565` `(bug): vlan aware bridge not working with - Kernel: T3318: update Linux Kernel to v5.4.205 #249` +- {vytask}`T3988` `(default): Feature Request: IPsec Multiple local/remote prefix for the tunnel` +- {vytask}`T2763` `(feature): New SNMP resource request - SNMP over TCP` + +## 2022-08-14 + +- {vytask}`T4579` `(bug): bridge: can not delete member interface CLI option when VLAN is enabled` +- {vytask}`T4421` `(default): Add support for floating point numbers in the numeric validator` +- {vytask}`T3507` `(bug): Bond with mode LACP show u/u in show interfaces even if peer is not configured` + +## 2022-08-12 + +- {vytask}`T4603` `(feature): Need a config option to specify NAS-IP-Address for vpn l2tp` + +## 2022-08-10 + +- {vytask}`T4408` `(feature): Add sshguard to protect against brut-forces` + +## 2022-08-08 + +- {vytask}`T4586` `(feature): Add to NAT66: SNAT destination address and DNAT source address.` + +## 2022-08-04 + +- {vytask}`T4257` `(feature): Discussion on changing BGP autonomous system number syntax` + +## 2022-08-02 + +- {vytask}`T4585` `(feature): Rewrite op-mode containers to vyos.opmode` +- {vytask}`T4515` `(default): Reduce telegraf binary size` + +## 2022-08-01 + +- {vytask}`T4581` `(bug): 'show system cpu' not working` +- {vytask}`T4578` `(feature): Rewrite show dns forwarding statistics to new format` + +## 2022-07-31 + +- {vytask}`T4580` `(bug): Handle the case of op-mode file names with hyphens in GraphQL schema/resolver generation` + +## 2022-07-30 + +- {vytask}`T4575` `(feature): vyos.utill add new wrapper "rc_cmd" to get the return code and output` +- {vytask}`T4562` `(feature): Rewrite show vrf to new format` +- {vytask}`T4545` `(feature): Rewrite show nat source rules` +- {vytask}`T4543` `(bug): Show source nat statistics shows incorrect interface` +- {vytask}`T4503` `(default): Prevent op mode scripts from restarting services if there's a commit in progress` +- {vytask}`T4411` `(feature): Add migration for service monitoring telegraf influxdb` + +## 2022-07-29 + +- {vytask}`T4554` `(enhancment): Implement GraphQL resolvers for standardized op-mode scripts` +- {vytask}`T4518` `(feature): Add XML for CLI conf mode load-balancing wan` +- {vytask}`T4544` `(enhancment): Generate schema definitions from standardized op-mode scripts` + +## 2022-07-28 + +- {vytask}`T4531` `(bug): NAT op-mode errors with exclude rules` +- {vytask}`T3435` `(bug): NAT rules show corruption` + +## 2022-07-27 + +- {vytask}`T4571` `(bug): Sflow with vrf configured does not use vrf to validate agent-address IP from vrf-configured interfaces` +- {vytask}`T4552` `(bug): Unable to reset IPsec IPv6 peer` + +## 2022-07-26 + +- {vytask}`T4568` `(bug): show vpn debug peer doesn't work` +- {vytask}`T4556` `(feature): fastnetmon: Allow configure white_list_path and populate with hosts/networks that should be ignored.` +- {vytask}`T4495` `(feature): Combine BGP reset op commands` + +## 2022-07-25 + +- {vytask}`T4567` `(default): Merge experimental branch of GraphQL development` +- {vytask}`T4560` `(bug): VRF and BGP neighbor local-as error` +- {vytask}`T4493` `(bug): Incorrect help for "show bgp neighbors"` +- {vytask}`T1233` `(bug): ipsec vpn sa showing down` + +## 2022-07-22 + +- {vytask}`T4145` `(bug): Conntrack table not showing after firewall rewriting` + +## 2022-07-21 + +- {vytask}`T4555` `(feature): fastnetmon: add IPv6 support` +- {vytask}`T4553` `(default): Allow to set ban time on ddos-protection configuration` + +## 2022-07-20 + +- {vytask}`T4056` `(bug): Traffic policy not set in live configuration` + +## 2022-07-18 + +- {vytask}`T4523` `(feature): OP-mode Extend conntrack output to get marks, zones and directions` +- {vytask}`T4228` `(bug): bond: OS error thrown when two bonds use the same member` +- {vytask}`T4539` `(feature): qat: update Intel QuickAssist release version 1.7.L.4.16.0-00017` +- {vytask}`T4534` `(bug): bond: bridge: error out if member interface is assigned to a VRF instance` +- {vytask}`T4525` `(bug): Delete interface from VRF and add it to bonding error` +- {vytask}`T4522` `(feature): bond: add ability to specify mii monitor interval via CLI` +- {vytask}`T4535` `(feature): FRR: upgrade to stable/8.3 version` +- {vytask}`T4521` `(bug): bond: ARP monitor interval is not configured despite set via CLI` +- {vytask}`T4540` `(feature): firmware: update to Linux release 20220708` + +## 2022-07-17 + +- {vytask}`T4028` `(bug): FRR 8.1 routes not being applied to routing table after reboot if an interface has 2 ip addresses` + +## 2022-07-15 + +- {vytask}`T4494` `(bug): Cannot reset BGP peer within VRF` +- {vytask}`T4536` `(feature): FRR: move to systemd for daemon control` + +## 2022-07-14 + +- {vytask}`T4491` `(bug): Use empty string for internal name of root node of config_tree` + +## 2022-07-13 + +- {vytask}`T1375` `(feature): Add clear dhcp server lease function` + +## 2022-07-12 + +- {vytask}`T4527` `(bug): Prevent to create VRF name default` +- {vytask}`T4084` `(default): Dehardcode the default login banner` +- {vytask}`T3948` `(feature): IPSec VPN: Add a new option "none" for the connection-type` +- {vytask}`T235` `(feature): Ability to configure manual IP Rules` + +## 2022-07-10 + +- {vytask}`T3836` `(bug): Setting a default IPv6 route while getting IPv4 gateway via DHCP removes the IPv4 gateway` + +## 2022-07-09 + +- {vytask}`T4507` `(feature): IPoE-server add multiplier option for shaper` +- {vytask}`T4499` `(bug): NAT source translation not showing a single output` +- {vytask}`T4468` `(bug): web-proxy source group cannot start with a number bug` +- {vytask}`T4373` `(feature): PPPoE-server add multiplier option for shaper` +- {vytask}`T3353` `(bug): PPPoE server wrong vlan-range generating config` +- {vytask}`T3648` `(bug): op-mode: nat rules broken` +- {vytask}`T4517` `(feature): ip: Add options to enable directed broadcast forwarding` + +## 2022-07-07 + +- {vytask}`T4456` `(bug): NTP client in VRF tries to bind to interfaces outside VRF, logs many messages` +- {vytask}`T4509` `(feature): Feature Request: DNS64` + +## 2022-07-06 + +- {vytask}`T4513` `(bug): Webproxy monitor commands do not work` +- {vytask}`T4299` `(feature): Firewall - GeoIP filtering` + +## 2022-07-05 + +- {vytask}`T4378` `(bug): Unable to submit wildcard ("*.example.com") A or AAAA records in dns forwarder` +- {vytask}`T2683` `(default): no dual stack in system static-host-mapping host-name` +- {vytask}`T478` `(feature): Firewall address group (multi and nesting)` + +## 2022-07-04 + +- {vytask}`T4501` `(bug): Syslog-identifier does not work in event handler` +- {vytask}`T3600` `(bug): DHCP Interface static route breaks PBR` +- {vytask}`T4498` `(feature): bridge: Add option to enable/disable IGMP/MLD snooping` + +## 2022-07-01 + +- {vytask}`T2455` `(bug): No support for the IPv6 VTI` +- {vytask}`T4490` `(feature): BGP- warning message that AFI/SAFI is needed to establish the neighborship` +- {vytask}`T4489` `(bug): MPLS sysctl not persistent for tunnel interfaces` + +## 2022-06-29 + +- {vytask}`T4477` `(feature): router-advert: support RDNSS lifetime option` + +## 2022-06-28 + +- {vytask}`T4486` `(bug): Container can't be deleted` +- {vytask}`T4473` `(bug): Use container network without network declaration error` +- {vytask}`T4458` `(feature): Firewall - add support for matching ip ttl in firewall rules` +- {vytask}`T3907` `(feature): Firewall - Set log levels` + +## 2022-06-27 + +- {vytask}`T4484` `(default): Firewall op-mode summary doesn't correctly handle address group containing ranges` + +## 2022-06-25 + +- {vytask}`T4482` `(bug): dhcp: toggle of "dhcp-options no-default-route" has no effect` +- {vytask}`T4483` `(feature): Upgrade fastnetmon to v1.2.2 community edition` + +## 2022-06-22 + +- {vytask}`T1748` `(feature): vbash: beautify tab completion output/line breaks` + +## 2022-06-20 + +- {vytask}`T1856` `(feature): Support configuring IPSec SA bytes` + +## 2022-06-18 + +- {vytask}`T4467` `(bug): Validator Does Not Accept Signed Numbers` + +## 2022-06-17 + +- {vytask}`T4209` `(bug): Firewall incorrect handler for recent count and time` + +## 2022-06-16 + +- {vytask}`T4352` `(bug): wan-load balance - priority traffic rule doesn't work` + +## 2022-06-15 + +- {vytask}`T4450` `(feature): Route-map - Extend options for ip|ipv6 address match` +- {vytask}`T4449` `(feature): Route-map - Extend options for ip next-hop match` +- {vytask}`T990` `(feature): Make DNAT/SNAT a valid state in firewall rules.` + +## 2022-06-12 + +- {vytask}`T4420` `(feature): Feature Request: ocserv: show configured 2FA OTP key` +- {vytask}`T4380` `(default): Feature Request: ocserv: 2FA OTP key generator in VyOS CLI` + +## 2022-06-10 + +- {vytask}`T4365` `(bug): NAT - Error on setting up tables` +- {vytask}`T4465` `(feature): node.def generation misses whitespace on multiple use of <path>` + +## 2022-06-09 + +- {vytask}`T4444` `(default): sstp: Feature request. Port number changing support` +- {vytask}`T2580` `(feature): Support for ip pools for ippoe` + +## 2022-06-08 + +- {vytask}`T4447` `` (bug): DHCPv6 prefix delegation `sla-id` limited to 128 `` + +## 2022-05-31 + +- {vytask}`T4212` `(default): PermissionError when generating/installing server Certificate (generate pki certificate sign ...)` +- {vytask}`T4199` `(bug): Commit failed when setting icmpv6 type any` +- {vytask}`T4148` `(bug): Firewall - Error messages not that clear as it were in old firewall` +- {vytask}`T3659` `(bug): Configuration won't accept IPv6 addresses for site-to-site VPN tunnel prefixes/traffic selectors` + +## 2022-05-30 + +- {vytask}`T4315` `(feature): Telegraf - Output to prometheus` + +## 2022-05-29 + +- {vytask}`T2473` `(feature): Xml for EIGRP [conf_mode]` + +## 2022-05-28 + +- {vytask}`T4448` `(feature): rip: add support for explicit version selection` + +## 2022-05-26 + +- {vytask}`T4442` `(feature): HTTP API add action "reset"` + +## 2022-05-25 + +- {vytask}`T4410` `(feature): Telegraf - Output to Splunk` +- {vytask}`T4382` `(bug): Replacing legacy loadFile exposes missing steps in migration scripts and other errors` + +## 2022-05-21 + +- {vytask}`T4437` `(bug): flow-accounting: support IPv6 flow collectors` + +## 2022-05-20 + +- {vytask}`T4418` `(feature): Telegraf - output Plugin azure-data-explorer` + +## 2022-05-19 + +- {vytask}`T4434` `(bug): DMVPN: cisco-authentication password length is 8 characters` +- {vytask}`T3938` `(default): Rewrite the uptime script in Python to allow using it as a library` +- {vytask}`T4334` `(default): Make the config lexer reentrant` + +## 2022-05-17 + +- {vytask}`T4424` `(bug): policy local-route6 shows ipv4 format` + +## 2022-05-16 + +- {vytask}`T4377` `(default): generate tech-support archive includes previous archives` + +## 2022-05-12 + +- {vytask}`T4417` `(bug): VRRP doesn't start with conntrack-sync` +- {vytask}`T4100` `(feature): Firewall increase maximum number of rules` + +## 2022-05-11 + +- {vytask}`T4405` `` (bug): DHCP client sometimes ignores `no-default-route` option of an interface `` + +## 2022-05-10 + +- {vytask}`T4156` `(default): Adding DHCP Option 13 (bootfile-size)` +- {vytask}`T1972` `(feature): Allow setting interface name for virtual_ipaddress in VRRP VRID` + +## 2022-05-07 + +- {vytask}`T4361` `` (bug): `vyos.config.exists()` does not work for nodes with multiple values `` +- {vytask}`T4354` `(bug): Slave interfaces fall out from bonding during configuration change` +- {vytask}`T4419` `(feature): vrf: support to disable IP forwarding within a given VRF` + +## 2022-05-06 + +- {vytask}`T4385` `(bug): bgp: peer-group member cannot override remote-as of peer-group` + +## 2022-05-05 + +- {vytask}`T4414` `(feature): Add route-map "as-path prepend last-as x" option` + +## 2022-05-03 + +- {vytask}`T4395` `(feature): Extend show vpn debug` + +## 2022-05-01 + +- {vytask}`T4369` `(bug): OpenVPN: daemon not restarted on changes to "openvpn-option" CLI node` +- {vytask}`T4363` `(bug): salt-minion: default mine_interval option is not set` +- {vytask}`T4353` `(feature): Add Jinja2 linter to vyos-1x build process` + +## 2022-04-29 + +- {vytask}`T4388` `(bug): dhcp-server: missing constraint on tftp-server-name option` +- {vytask}`T4366` `(bug): geneve: interface is removed on changes to e.g. description` + +## 2022-04-28 + +- {vytask}`T4400` `(bug): Container OP mode has delete where show and update should be` + +## 2022-04-27 + +- {vytask}`T4398` `(bug): IPSec site-to-site generates unexpected passthrough option` +- {vytask}`T4397` `(feature): arp: migrate static ARP entry configuration to get_config_dict() and make it VRF aware` +- {vytask}`T4357` `(feature): Allow free-form setting of DHCPv6 server options` + +## 2022-04-26 + +- {vytask}`T4210` `(bug): NAT source/destination negated ports throws an error` +- {vytask}`T4235` `(default): Add config tree diff algorithm` + +## 2022-04-25 + +- {vytask}`T4390` `(feature): op-mode: extend "show log" and "monitor log" with additional daemons/subsystems to read journalctl logs` +- {vytask}`T4391` `(bug): PPPoE: IPv6 not working after system boot` + +## 2022-04-24 + +- {vytask}`T4342` `(bug): "show ip ospf neighbor address x.x.x.x" gives "unknown command" error` + +## 2022-04-23 + +- {vytask}`T4386` `(default): Applying limiter on traffic-policy "in" fails, incorrectly reports mirror or redirect policy in use` + +## 2022-04-22 + +- {vytask}`T4389` `(feature): dhcp: add vendor option support for Ubiquity Unifi controller` + +## 2022-04-21 + +- {vytask}`T4384` `(feature): pppoe: replace default-route CLI option with common CLI nodes already present for DHCP` + +## 2022-04-20 + +- {vytask}`T4345` `(bug): New firewall code does not accept "rate/time interval" syntax used in old config` +- {vytask}`T4231` `(feature): Feature Request: ocserv: 2FA (password+OTP) support in Openconnect` + +## 2022-04-19 + +- {vytask}`T4379` `(bug): PPPoE: default-route lost after applying additional static routes` +- {vytask}`T4344` `(bug): DHCP statistics not matching, conf-mode generates incorrect pool name with dash` +- {vytask}`T4268` `(bug): Elevated LA while using VyOS monitoring feature` + +## 2022-04-18 + +- {vytask}`T4351` `(bug): Openvpn conf-mode "openvpn-option" is not respected` +- {vytask}`T4278` `(default): vyos-vm-images: fix vagrant libvirt box` +- {vytask}`T4368` `(bug): bgp: AS specified for local as is the same as the remote as and this is not allowed.` +- {vytask}`T4370` `(feature): vxlan: geneve: support configuration of df bit option` + +## 2022-04-15 + +- {vytask}`T4327` `(default): Ethernet interface configuration fails on Hyper-V due to speed/duplex/autoneg ethtool command error` +- {vytask}`T4364` `(feature): salt-minion: Upgrade to 3004 and migrate to get_config_dict()` + +## 2022-04-13 + +- {vytask}`T4333` `(feature): Jinja2: add plugin to test if a variable is defined and not none to reduce template complexity` + +## 2022-04-08 + +- {vytask}`T4331` `(bug): IPv6 link local addresses are not configured when an interface is in a VRF` +- {vytask}`T4347` `(default): Return complete and consistent error codes from HTTP API` +- {vytask}`T4339` `(bug): wwan: tab-completion results in "No such file or directory" if there is no WWAN interface` +- {vytask}`T4338` `(bug): wwan: changing interface description should not trigger reconnect` +- {vytask}`T4324` `(bug): wwan: check alive script should only be run via cron if a wwan interface is configured at all` + +## 2022-04-07 + +- {vytask}`T4330` `(bug): MTU settings cannot be applied when IPv6 is disabled` +- {vytask}`T4346` `(feature): Deprecate "system ipv6 disable" option to disable address family within OS kernel` +- {vytask}`T4319` `(bug): The command "set system ipv6 disable" doesn't work as expected.` +- {vytask}`T4341` `(feature): login: disable user-account prior to deletion and wait until deletion is complete` +- {vytask}`T4336` `(feature): isis: add support for MD5 authentication password on a circuit` + +## 2022-04-06 + +- {vytask}`T4308` `(feature): Op-comm "Show log frr" to view specific protocol logs` + +## 2022-04-04 + +- {vytask}`T4329` `(bug): Bgp policy route-map bug with set several extcommunity rt` + +## 2022-04-02 + +- {vytask}`T4335` `(bug): open-vmdk fails to build under gcc-10.+` + +## 2022-04-01 + +- {vytask}`T4332` `(bug): bgp: deterministic-med cannot be disabled while addpath-tx-bestpath-per-AS is in use` + +## 2022-03-31 + +- {vytask}`T4326` `(feature): Add bgp option no-suppress-duplicates` +- {vytask}`T4323` `(default): ospf6d crashes on latest vyos nightly` + +## 2022-03-29 + +- {vytask}`T3686` `(bug): Bridging OpenVPN tap with no local-address breaks` +- {vytask}`T3635` `(default): Add ability to use mDNS repeater with VRRP` + +## 2022-03-26 + +- {vytask}`T4321` `(default): Allow BGP neighbors between different VIFs on the same VyOS` + +## 2022-03-24 + +- {vytask}`T4301` `(bug): The "arp-monitor" option in bonding interface settings does not work` +- {vytask}`T4294` `(bug): Adding a new openvpn-option does not restart the OpenVPN process` +- {vytask}`T4290` `(bug): BGP source-interface fails to commit` +- {vytask}`T4230` `(bug): OpenVPN server configuration deleted after reboot when using a VRRP virtual-address` + +## 2022-03-23 + +- {vytask}`T4314` `(bug): Latest 1.4 Rolling release config migration error` + +## 2022-03-21 + +- {vytask}`T4304` `(feature): [OSPF]import/export filter inter-area prefix` + +## 2022-03-20 + +- {vytask}`T4298` `(default): vyos-vm-images: fix ansible group name and remove obsolete empty command` + +## 2022-03-18 + +- {vytask}`T4286` `(bug): Fix for firewall ipv6 name address validator` + +## 2022-03-15 + +- {vytask}`T4302` `(feature): FRRouting upgrade to release 8.2.2` +- {vytask}`T4293` `(default): Add "set ip-next-hop unchanged" in route-map` + +## 2022-03-14 + +- {vytask}`T4275` `(default): Incorrect val_help for local/remote prefix in ipsec vpn` + +## 2022-03-12 + +- {vytask}`T4296` `(bug): Interface config injected by Cloud-Init may interfere with VyOS native` +- {vytask}`T4265` `(feature): Add op-mode for bgp flowspec state and routes` + +## 2022-03-11 + +- {vytask}`T4297` `(bug): Interface configuration saving fails for ice/iavf based interfaces because they can't change speed/duplex settings` + +## 2022-03-09 + +- {vytask}`T3981` `(feature): VRF support for flow-accounting` + +## 2022-03-05 + +- {vytask}`T4259` `(bug): The conntrackd daemon can be started wrongly` + +## 2022-03-03 + +- {vytask}`T4283` `(feature): Add support to "reject" routes - emit an ICMP unreachable when matched` + +## 2022-03-01 + +- {vytask}`T4277` `(feature): flow-accounting: support sending flow-data via VRF interface` + +## 2022-02-28 + +- {vytask}`T4273` `(bug): ssh: Upgrade from 1.2.X to 1.3.0 breaks config` +- {vytask}`T4115` `(bug): reboot in <x> not working as expected` +- {vytask}`T3656` `(bug): IPSec 1.4 : "show vpn ike sa" does not show the correct default ike version` + +## 2022-02-26 + +- {vytask}`T4272` `(feature): lldp: migrate Python script to use get_config_dict()` + +## 2022-02-24 + +- {vytask}`T4267` `(bug): Error - Missing required "ip key" parameter` + +## 2022-02-23 + +- {vytask}`T4194` `(bug): prefix-list no check for duplicate entries` +- {vytask}`T4264` `(bug): vxlan: interface is destroyed and rebuild on description change` +- {vytask}`T4263` `(bug): vyos.util.leaf_node_changed() dos not honor valueLess nodes` + +## 2022-02-21 + +- {vytask}`T4120` `(feature): [VXLAN] add ability to set multiple unicast-remotes` + +## 2022-02-20 + +- {vytask}`T4254` `(feature): VPN IPSec charon add options cisco_flexvpn and install_virtual_ip_on` +- {vytask}`T4249` `(feature): Add support for device mapping in containers` +- {vytask}`T3617` `(bug): IPSec 1.4 generate invalid configuration` +- {vytask}`T4261` `(feature): MACsec: add DHCP client support` +- {vytask}`T4203` `(bug): Reconfigure DHCP client interface causes brief outages` + +## 2022-02-19 + +- {vytask}`T4258` `(bug): [DHCP-SERVER] error parameter on Failover` + +## 2022-02-17 + +- {vytask}`T4255` `(bug): Unexpected print of dict bridge on delete` +- {vytask}`T4240` `(bug): Cannot add wlan0 to bridge via configure` +- {vytask}`T4154` `(bug): Error add second gre tunnel with the same source interface` + +## 2022-02-16 + +- {vytask}`T4237` `(bug): Conntrack-sync error - error adding listen-address command` + +## 2022-02-15 + +- {vytask}`T4160` `(bug): Firewall - Error in rules that matches everything except something` +- {vytask}`T3006` `(bug): Accel-PPP & vlan-mon config get invalid VLAN` +- {vytask}`T3494` `(bug): DHCPv6 leases traceback when PD using` +- {vytask}`T1292` `(bug): Issues while deleting all rules from a firewall` + +## 2022-02-13 + +- {vytask}`T4242` `(bug): ethernet speed/duplex can never be switched back to auto/auto` +- {vytask}`T4191` `(bug): Lost access to host after VRF re-creating` + +## 2022-02-11 + +- {vytask}`T3872` `(feature): Add configurable telegraf monitoring service` + +## 2022-02-08 + +- {vytask}`T4227` `(bug): Typo in help completion of hello-time option of bridge interface` + +## 2022-02-07 + +- {vytask}`T4233` `(bug): ssh: sync regex for allow/deny usernames to "system login"` + +## 2022-02-06 + +- {vytask}`T4223` `(bug): policy route cannot have several entries with the same table` +- {vytask}`T4216` `(bug): Firewall: can't use negated groups in firewall rules` +- {vytask}`T4178` `(bug): policy based routing tcp flags issue` +- {vytask}`T4164` `` (bug): PBR: network groups (as well as address and port groups) don't resolve in `nftables_policy.conf` `` +- {vytask}`T3970` `(feature): Add support for op-mode PKI direct install into an active config session` +- {vytask}`T3828` `(bug): ipsec: Subtle change in "pfs enable" behavior from equuleus -> sagitta` + +## 2022-02-05 + +- {vytask}`T4226` `(bug): VRRP transition-script does not work for groups name which contains -(minus) sign` + +## 2022-02-04 + +- {vytask}`T4196` `(bug): DHCP server client-prefix-length parameter results in non-functional leases` + +## 2022-02-03 + +- {vytask}`T4218` `(bug): firewall: rule name is not allowed to start with a number` +- {vytask}`T3643` `(bug): show vpn ipsec sa doesn't show tunnels in "down" state` + +## 2022-02-01 + +- {vytask}`T4224` `(bug): Ethernet interfaces configured for DHCP not working on latest rolling snapshot (vyos-1.4-rolling-202201291849-amd64.iso)` +- {vytask}`T4225` `(bug): Performance degration with latest rolling release` +- {vytask}`T4220` `(bug): Commit broke dhclient 78b247b724f74bdabab0706aaa7f5b00e5809bc1` +- {vytask}`T4138` `(bug): NAT configuration allows to set incorrect port range and invalid port` + +## 2022-01-28 + +- {vytask}`T4184` `(bug): NTP allow-clients address doesn't work it allows to use ntp server for all addresses` +- {vytask}`T4217` `(bug): firewall: port-group requires protocol to be set - but not in VyOS 1.3` + +## 2022-01-27 + +- {vytask}`T4213` `(default): ipv6 policy routing not working anymore` +- {vytask}`T4188` `(bug): Firewall does not correctly handle conntracking` +- {vytask}`T3762` `(feature): Support network and address groups for policy ipv6-route` +- {vytask}`T3560` `(feature): Ability to create groups of MAC addresses` +- {vytask}`T3495` `(feature): Modernising port/protocol definitions` + +## 2022-01-25 + +- {vytask}`T4205` `(feature): Disable Debian Version in SSH (DebianBanner->no)` +- {vytask}`T4131` `(bug): Show firewall group incorrect format members` + +## 2022-01-24 + +- {vytask}`T4204` `(feature): Update Accel-PPP to a newer revision` +- {vytask}`T1795` `(default): Commit rollback by timeout` + +## 2022-01-23 + +- {vytask}`T4186` `(bug): Firewall icmp type - Offered options not supported` +- {vytask}`T4181` `(bug): Firewall ipv6-network-group - incorrect description on helper` + +## 2022-01-21 + +- {vytask}`T4200` `(bug): Assigning ipv6-name to interface is not generating nftables rules` +- {vytask}`T4144` `(bug): Firewall address-group - Improve error messages` +- {vytask}`T4137` `(bug): Firewall group configuration allows to set incorrect port range and invalid port` +- {vytask}`T4133` `(bug): Firewall network group error with zone-based firewall rules` + +## 2022-01-20 + +- {vytask}`T4171` `(bug): Interface config migration error on 1.2.8 -> 1.4 upgrade` + +## 2022-01-19 + +- {vytask}`T4195` `(feature): [OSPF-ECMP]enable set maximun-path` + +## 2022-01-18 + +- {vytask}`T4159` `(bug): Empty firewall group (address, network & port) generates invalid nftables config, commit fails` +- {vytask}`T4155` `` (bug): PBR: `set table main` fails in `firewall.py` with newer rolling releases `` +- {vytask}`T3873` `(feature): Zone based Firewall - Filter traffic in same zone` +- {vytask}`T3286` `(feature): Switch the firewall from iptables to nftables` +- {vytask}`T292` `(feature): [ZBF] Allow filtering intra zone traffic` + +## 2022-01-17 + +- {vytask}`T3164` `(bug): console-server ssh does not work with RADIUS PAM auth` + +## 2022-01-15 + +- {vytask}`T4183` `(feature): IPv6 link-local address not accepted as wireguard peer` +- {vytask}`T4150` `(bug): VRRP with conntrack-sync does not work` +- {vytask}`T4110` `(feature): [IPV6-SSH/DNS} enable IPv6 link local adresses as listen-address %eth0` + +## 2022-01-14 + +- {vytask}`T4182` `(bug): Show vrrp if vrrp not configured bug` +- {vytask}`T4179` `(feature): Add op-mode CLI for show high-availability virtual-server` + +## 2022-01-13 + +- {vytask}`T4175` `(bug): BGP configuration failed` +- {vytask}`T4109` `(feature): Extend high-availability/keepalived for support virtual-server lb` + +## 2022-01-12 + +- {vytask}`T4174` `(bug): Validation fails when entering port range with upper port 65535` +- {vytask}`T4162` `(bug): VPN ipsec ike-group - Incorrect value help for ikev2-reauth` +- {vytask}`T4161` `(bug): Policy route-map - Incorrect value help for local preference` +- {vytask}`T4152` `(bug): NHRP shortcut-target holding-time does not work` + +## 2022-01-11 + +- {vytask}`T4149` `(bug): [Firewall-IPV6] Error delete Fw rules on VIF/INT` +- {vytask}`T3950` `(bug): CLI backtrace on update if DNS not defined` +- {vytask}`T4166` `(bug): Debug output missing when frr.py called under vyos-configd` + +## 2022-01-10 + +- {vytask}`T3299` `(bug): Allow the web proxy service to listen on all IP addresses` +- {vytask}`T3115` `(feature): Add support for firewall on L3 VIF bridge interface` + +## 2022-01-09 + +- {vytask}`T4142` `(bug): Input ifbX interfaces not displayed in op-mode` +- {vytask}`T3914` `(bug): VRRP rfc3768-compatibility doesn't work with unicast peers` + +## 2022-01-08 + +- {vytask}`T4116` `(bug): Webproxy/Squid not working with IPv6 listen-address` + +## 2022-01-07 + +- {vytask}`T3924` `(bug): VRRP stops working with VRF` + +## 2022-01-06 + +- {vytask}`T4135` `(bug): Declare zone policy firewall without local zone errors` +- {vytask}`T4130` `(bug): Firewall state policy errors chain` +- {vytask}`T4141` `(bug): Set high-availability vrrp sync-group without members error` + +## 2022-01-04 + +- {vytask}`T4134` `(bug): Incorrect firewall protocol completion help uppercase and duplicates` +- {vytask}`T4132` `(bug): Impossible to show a specific firewall group` + +## 2022-01-03 + +- {vytask}`T4126` `(feature): Ability to set priority to site to site IPSec vpn tunnels` +- {vytask}`T4052` `(bug): Validator return traceback on VRRP configuration with the script path not in config dir` +- {vytask}`T4128` `(bug): keepalived: Upgrade package to add VRF support` + +## 2021-12-31 + +- {vytask}`T4081` `(bug): VRRP health-check script stops working when setting up a sync group` + +## 2021-12-30 + +- {vytask}`T4124` `(feature): snmp: migrate to get_config_dict()` + +## 2021-12-29 + +- {vytask}`T4111` `(bug): IPSec generates wrong configuration colons for IPv6 peers` +- {vytask}`T4023` `(feature): Add grepcidr or similar functionality` +- {vytask}`T4086` `(default): system login banner is not removed on deletion.` + +## 2021-12-28 + +- {vytask}`T3380` `(bug): "show vpn ike sa" does not display IPv6 peers` + +## 2021-12-27 + +- {vytask}`T3979` `(bug): vyos-hostd unable to hostfile-update` +- {vytask}`T2566` `(bug): sstp not able to run tunnels ipv6 only` +- {vytask}`T4093` `(bug): SNMPv3 snmpd.conf generation bug` +- {vytask}`T2764` `(enhancment): Increase maximum number of NAT rules` + +## 2021-12-26 + +- {vytask}`T4104` `(bug): RAID1: "add raid md0 member sda1" does not restore boot sector` +- {vytask}`T4108` `(default): OSPFv3: add support for auto-cost parameter` +- {vytask}`T4107` `(default): OSPFv3: add support for "default-information originate"` + +## 2021-12-25 + +- {vytask}`T4101` `(bug): commit-archive: Use of uninitialized value $source_address in concatenation` +- {vytask}`T4099` `(feature): flow-accounting: sync "source-ip" and "source-address" between netflow and sflow ion CLI` +- {vytask}`T4097` `(feature): flow-accounting: migrate implementation to get_config_dict()` +- {vytask}`T4105` `(feature): flow-accounting: drop "sflow agent-address auto"` +- {vytask}`T4106` `(feature): flow-accounting: support specification of capture packet lenght` +- {vytask}`T4102` `(feature): OSPFv3: add support for NSSA area-type` +- {vytask}`T4055` `(feature): Add VRF support for HTTP(S) API service` + +## 2021-12-24 + +- {vytask}`T3854` `(bug): Missing op-mode commands for conntrack-sync` + +## 2021-12-23 + +- {vytask}`T3354` `(default): Convert strip-private script from Perl to Python` + +## 2021-12-22 + +- {vytask}`T3678` `(bug): VyOS 1.4: Invalid error message while deleting ipsec vpn configuration` +- {vytask}`T3356` `(feature): Script for remote file transfers` + +## 2021-12-21 + +- {vytask}`T4083` `(bug): Cluster heartbeat doesn't start b.c lack of directory /run/heartbeat/` +- {vytask}`T4070` `(bug): NATv4 : inbound-interface type "any" is missing.` +- {vytask}`T4053` `(bug): VRRP impossible to set scripts out of the /config directory` +- {vytask}`T3931` `(bug): SSTP doesn't work after rewriting to PKI` + +## 2021-12-20 + +- {vytask}`T4088` `(default): Fix typo in login banner` + +## 2021-12-19 + +- {vytask}`T3912` `(default): Use a more informative default post-login banner` + +## 2021-12-17 + +- {vytask}`T4059` `(bug): VRRP sync-group transition script does not persist after reboot` + +## 2021-12-16 + +- {vytask}`T4046` `(feature): Sflow - Add Source address parameter` +- {vytask}`T3556` `(bug): Commit-archive via scp causes 100% CPU on boot` +- {vytask}`T4076` `(enhancment): Allow setting CORS options in HTTP API` +- {vytask}`T4037` `(default): HTTP transfers do not follow redirects` +- {vytask}`T4029` `(default): Broken SFTP uploads` + +## 2021-12-15 + +- {vytask}`T4077` `(bug): op-mode: bfd: drop "show protocols bfd" in favour of "show bfd"` +- {vytask}`T4073` `(bug): "show protocols bfd peer <>" shows incorrect peer information.` + +## 2021-12-14 + +- {vytask}`T4071` `(feature): Allow HTTP API to bind to unix domain socket` + +## 2021-12-12 + +- {vytask}`T4069` `(feature): BGP: add additional available parameters to VyOS CLI` +- {vytask}`T4036` `(bug): VXLAN incorrect raiseError if set multicast network instead of singe address` + +## 2021-12-10 + +- {vytask}`T4068` `(feature): Python: ConfigError should insert line breaks into the error message` + +## 2021-12-09 + +- {vytask}`T4033` `(bug): VRRP - Error security when setting scripts` +- {vytask}`T4064` `(bug): IP address for vif is not removed from the system when deleted in configuration` +- {vytask}`T4060` `(enhancment): Extend configquery for use before boot configuration is complete` +- {vytask}`T4058` `(bug): BFD: add BGP and OSPF "bfd profile" support` +- {vytask}`T4054` `(bug): BFD profiles configuration incorrect behavior.` + +## 2021-12-07 + +- {vytask}`T4041` `(servicerequest): "transition-script" doesn't work on "sync-group"` + +## 2021-12-06 + +- {vytask}`T4012` `(feature): Add VRF support for TFTP` + +## 2021-12-04 + +- {vytask}`T4049` `(feature): support command-style output with compare command` +- {vytask}`T4047` `(bug): Wrong regex validation in XML definitions` +- {vytask}`T4042` `(bug): BGP L2VPN / EVPN and RD type 0 set` +- {vytask}`T4048` `(bug): BGP: L2VPN/EVPN and individual RD and RT settings for each VNI` +- {vytask}`T4045` `(bug): Unable to "format disk <new> like <old>"` +- {vytask}`T4044` `(feature): BFD: add vrf support` +- {vytask}`T4043` `(feature): BFD: add support for passive mode` + +## 2021-12-02 + +- {vytask}`T4035` `(bug): Geneve interfaces aren't displayed by operational mode commands` + +## 2021-12-01 + +- {vytask}`T3695` `(bug): OpenConnect reports commit success when ocserv fails to start due to SSL cert/key file issues` + +## 2021-11-30 + +- {vytask}`T4010` `(bug): DMVPN generates incorrect configuration life_time for swanctl.conf` +- {vytask}`T3725` `(feature): show configuration in json format` + +## 2021-11-29 + +- {vytask}`T3946` `(enhancment): Automatically resize the root partition if the drive has extra space` + +## 2021-11-28 + +- {vytask}`T3999` `(bug): show lldp neighbor Traceback error` +- {vytask}`T3928` `(feature): Add OSPFv3 VRF support` + +## 2021-11-27 + +- {vytask}`T3755` `(feature): ospf: adjust to new FRR 8 syntax where "no passive-interface " moved to interface section` +- {vytask}`T3753` `(feature): frr: upgrade to stable/8.1 release train` + +## 2021-11-26 + +- {vytask}`T3978` `(bug): containers add network without declaring prefix raise ConfigError` + +## 2021-11-25 + +- {vytask}`T4006` `(default): Add additional Linux capabilities to container configuration` +- {vytask}`T3986` `(bug): Incorrect description for vpn ipsec site-to-site authentication and connection` + +## 2021-11-24 + +- {vytask}`T4015` `(feature): Update Accel-PPP to a newer revision` +- {vytask}`T3865` `(bug): loadkey command help text missing escape sequence` +- {vytask}`T1083` `(feature): Implement persistent/random address and port mapping options for NAT rules` + +## 2021-11-23 + +- {vytask}`T3990` `(bug): WATCHFRR: crashlog and per-thread log buffering unavailable (due to files left behind in /var/tmp/frr/ after reboot)` + +## 2021-11-20 + +- {vytask}`T3998` `(bug): route-target completion incorrect description` + +## 2021-11-19 + +- {vytask}`T4003` `(bug): API for "show interfaces ethernet" does not include the interface description` +- {vytask}`T4011` `(bug): ethernet: deleting interface should place interface in admin down state` + +## 2021-11-18 + +- {vytask}`T3612` `(bug): IPoE Server address pool issues.` +- {vytask}`T3995` `(feature): OpenVPN: do not stop/start service on configuration change` +- {vytask}`T4008` `(feature): dhcp: change client retry interval form 300 -> 60 seconds` +- {vytask}`T3795` `(bug): WWAN: issues with non connected interface / no signal` +- {vytask}`T3510` `(bug): RADIUS usersname is not shown on CLI` + +## 2021-11-17 + +- {vytask}`T3350` `(bug): OpenVPN config file generation broken` +- {vytask}`T3996` `(bug): SNMP service error in log` + +## 2021-11-15 + +- {vytask}`T3994` `(bug): VRF: unable to delete vrf when name contains numbers, hyphen or underscore` +- {vytask}`T3960` `(bug): FRR Misconfig when using multiple VRF VNI` +- {vytask}`T3724` `(feature): Allow setting host-name in l2tp section of accel-ppp` +- {vytask}`T645` `(feature): Allow multiple prefixes in ipsec tunnel` + +## 2021-11-10 + +- {vytask}`T3966` `(default): OpenVPN fix the smoketests` +- {vytask}`T3834` `(default): [OPENVPN] Support for Two Factor Authentication totp.` +- {vytask}`T3982` `(bug): DHCP server commit fails if static-mapping contains + or .` + +## 2021-11-09 + +- {vytask}`T3962` `(bug): Image cannot be built without open-vm-tools` + +## 2021-11-07 + +- {vytask}`T3626` `(bug): Configuring and disabling DHCP Server` + +## 2021-11-06 + +- {vytask}`T3514` `(bug): NIC flap at any interface change` + +## 2021-11-05 + +- {vytask}`T3972` `(bug): Removing vif-c interface raises KeyError` + +## 2021-11-04 + +- {vytask}`T3969` `(bug): Container incorrect raiseError format if network doesn't exist` +- {vytask}`T3662` `(bug): Container configuration upgrade destroys system` +- {vytask}`T3964` `(bug): SSTP: local-user static-ip CLI node accepts invalid IPv4 addresses` + +## 2021-11-03 + +- {vytask}`T3952` `(default): Add sh bgp ipv4/ipv6 vpn command` +- {vytask}`T3610` `(bug): DHCP-Server creation for not primary IP address fails` + +## 2021-11-01 + +- {vytask}`T3958` `(default): OpenVPN breaks the smoketests` +- {vytask}`T3956` `(bug): GRE tunnel - unable to move from source-interface to source-address, commit error` + +## 2021-10-31 + +- {vytask}`T3945` `(feature): Add route-map for bgp aggregate-address` +- {vytask}`T3954` `(bug): FTDI cable makes VyOS sagitta latest hang, /dev/serial unpopulated, config system error` +- {vytask}`T3943` `(bug): "netflow source-ip" prevents image upgrades if IP address does not exist locally` + +## 2021-10-29 + +- {vytask}`T3942` `(feature): Generate IPSec debug archive from op-mode` + +## 2021-10-28 + +- {vytask}`T3951` `(bug): After resetting vti ipsec tunnel old child SA still active` +- {vytask}`T3941` `(bug): "show vpn ipsec sa" shows established time of parent SA not child SA's` +- {vytask}`T3916` `(feature): Add additional Linux capabilities to container configuration` + +## 2021-10-27 + +- {vytask}`T3944` `(bug): VRRP fails over when adding new group to master` + +## 2021-10-22 + +- {vytask}`T3897` `(feature): Dynamic DNS doesn't work with IPv6 addresses` +- {vytask}`T3832` `(feature): Allow to set DHCP client-id in hexadecimal format` +- {vytask}`T3188` `(bug): Tunnel local-ip to dhcp-interface Change Fails to Update` +- {vytask}`T3917` `(default): Use Avahi as mDNS repeater for IPv6 support` + +## 2021-10-21 + +- {vytask}`T3926` `(bug): strip-private does not sanitize "cisco-authentication" from NHRP configuration` +- {vytask}`T3925` `(feature): Tunnel: dhcp-interface not implemented - use source-interface instead` +- {vytask}`T3923` `(feature): Kernel: Enable TLS/IPSec offload support for Mellanox ConnectX NICs` +- {vytask}`T3927` `(feature): Kernel: Enable kernel support for HW offload of the TLS protocol` + +## 2021-10-20 + +- {vytask}`T3918` `(bug): DHCPv6 prefix delegation incorrect verify error` +- {vytask}`T3921` `(bug): tunnel: KeyError when using dhcp-interface` + +## 2021-10-19 + +- {vytask}`T3396` `(bug): syslog can't be configured with an ipv6 literal destination in 1.2.x` + +## 2021-10-18 + +- {vytask}`T3002` `(default): VRRP change on IPSec interface causes packet routing issues` + +## 2021-10-17 + +- {vytask}`T3786` `(bug): GRE tunnel source address 0.0.0.0 error` +- {vytask}`T3217` `(default): Save FRR configuration on each commit` +- {vytask}`T3381` `(bug): Change GRE tunnel failed` +- {vytask}`T3254` `(bug): Dynamic DNS status shows incorrect last update time` +- {vytask}`T1243` `(bug): BGP local-as accept wrong values` +- {vytask}`T697` `(bug): Clean up and sanitize package dependencies` +- {vytask}`T578` `(feature): Support Linux Container` + +## 2021-10-16 + +- {vytask}`T3879` `(bug): GPG key verification fails when upgrading from a 1.3 beta version` + +## 2021-10-15 + +- {vytask}`T3748` `(bug): Container deletion bug` +- {vytask}`T3693` `(feature): ISIS Route redistribution ipv6 support missing` +- {vytask}`T3676` `(feature): Container option to add Linux capabilities` +- {vytask}`T3613` `(feature): Selectors for route-based IPsec tunnel (vti)` +- {vytask}`T3692` `(bug): VyOS build failing due to repo.saltstack.com` +- {vytask}`T3673` `(feature): BGP large-community del operation missing` + +## 2021-10-14 + +- {vytask}`T3811` `(bug): NAT (op_mode): NAT op_mode command fails.` +- {vytask}`T3801` `(feature): containers: do not use podman CLI to create container networks` + +## 2021-10-13 + +- {vytask}`T3904` `(bug): NTP pool associations silently fail` +- {vytask}`T3277` `(feature): DNS Forwarding - reverse zones` + +## 2021-10-12 + +- {vytask}`T3216` `(bug): Removal of restricted-shell broke configure mode for RADIUS users` +- {vytask}`T3881` `(bug): Wrong description for container section restart` +- {vytask}`T3868` `(bug): Regex and/or wildcard not accepted with large-community-list` +- {vytask}`T3701` `(bug): ipoe server fails to start when configuring radius dynamic-author on ipoe` + +## 2021-10-10 + +- {vytask}`T3750` `(bug): pdns-recursor 4.4 issue with dont-query and private DNS servers` +- {vytask}`T3885` `(default): dhcpv6-pd: randomly generated DUID is not persisted` +- {vytask}`T3899` `(enhancment): Add support for hd44780 LCD displays` + +## 2021-10-09 + +- {vytask}`T3894` `` (bug): Tunnel Commit Failed if system does not have `eth0` `` + +## 2021-10-08 + +- {vytask}`T3893` `(bug): MGRE Tunnel commit crash If sit tunnel available` + +## 2021-10-05 + +- {vytask}`T3741` `(feature): [BGP] default no-ipv4-unicast - by default` + +## 2021-10-04 + +- {vytask}`T3888` `(bug): Incorrect warning when poweroff command executed from configure mode.` +- {vytask}`T3890` `(feature): dhcp(v6): provide op-mode commands to retrieve both server and client logfiles` +- {vytask}`T3889` `(feature): Migrate to journalctl when reading daemon logs` + +## 2021-10-03 + +- {vytask}`T3880` `(bug): EFI boot shows error on display` + +## 2021-10-02 + +- {vytask}`T3882` `(feature): Upgrade PowerDNs recursor to 4.5 series` +- {vytask}`T3883` `(bug): VRF - Delette vrf config on interface` + +## 2021-09-30 + +- {vytask}`T3874` `(bug): D-Link Ethernet Interface not working.` +- {vytask}`T3869` `(default): Rewrite vyatta_net_name/vyatta_interface_rescan in Python` + +## 2021-09-28 + +- {vytask}`T3853` `(default): nat66 rules gets deleted on reboot in 1.4-rolling-202109240217` + +## 2021-09-27 + +- {vytask}`T3863` `(default): nat66: commit fails/hangs on non existing interface` + +## 2021-09-26 + +- {vytask}`T3860` `(bug): Error on pppoe, tunnel and wireguard interfaces for IPv6 EUI64 addresses` +- {vytask}`T3857` `(feature): reboot: send wall message to all users for information` +- {vytask}`T3867` `(bug): vxlan: multicast group address is not validated` +- {vytask}`T3859` `(bug): Add "log-adjacency-changes" to ospfv3 process` +- {vytask}`T3826` `(bug): PKI: op-mode - do input validation when listing certificates` + +## 2021-09-25 + +- {vytask}`T3657` `(default): BGP neighbors ipv6 not able to establish with IPv6 link-local addresses` + +## 2021-09-23 + +- {vytask}`T3850` `(bug): Dots are no longer allowed in SSH public key names` + +## 2021-09-21 + +- {vytask}`T3847` `(feature): keepalived/vrrp: migrate to get_config_dict() - cleanup` + +## 2021-09-20 + +- {vytask}`T3823` `(bug): strip-private does not filter public IPv6 addresses` + +## 2021-09-19 + +- {vytask}`T3841` `(feature): dhcp-server: add ping-check option to CLI` +- {vytask}`T2738` `(bug): Modifying configuration in the "interfaces" section from VRRP transition scripts causes configuration lockup and high CPU utilization` +- {vytask}`T3840` `(feature): dns forwarding: Cache size should allow values > 10k` +- {vytask}`T3672` `(bug): DHCP-FO with multiple subnets results in invalid/non-functioning dhcpd.conf configuration file output` + +## 2021-09-18 + +- {vytask}`T3831` `(bug): External traffic stops routing when IPSEC tunnel comes up with interface vti0` +- {vytask}`T1968` `(default): Allow multiple static routes in dhcp-server` +- {vytask}`T3838` `(feature): dhcp-server - sync cli for name-servers to other subsystems` +- {vytask}`T3839` `(feature): dhcp-server: Allow configuration of a DNS server and domain name on the shared-network level` + +## 2021-09-17 + +- {vytask}`T3830` `(bug): ipsec: remote-id no longer included in IKE AUTH if not explicitly specified` + +## 2021-09-11 + +- {vytask}`T3402` `(feature): Add VyOS programming library for operational level commands` + +## 2021-09-10 + +- {vytask}`T3802` `(bug): Commit fails if ethernet interface doesn't support flow control` +- {vytask}`T3819` `(bug): Upgrade Salt Stack 3002.3 -> 3003 release train` +- {vytask}`T915` `(feature): MPLS Support` + +## 2021-09-09 + +- {vytask}`T3812` `(bug): Vyos and frr route-map config out of sync` +- {vytask}`T3814` `(bug): wireguard: commit error showing incorrect peer name from the configured name` +- {vytask}`T3805` `(bug): OpenVPN insufficient privileges for rtnetlink when closing TUN/TAP interface` +- {vytask}`T3815` `(bug): pki : the file command 'generate pki wireguard key-pair file' is not working` + +## 2021-09-07 + +- {vytask}`T1894` `(bug): FRR config not loaded after daemons segfault or restart` +- {vytask}`T3807` `(bug): Op Command "show interfaces wireguard" does not show the output` + +## 2021-09-06 + +- {vytask}`T3806` `(bug): Don't set link local ipv6 address if MTU less then 1280` +- {vytask}`T3803` `(default): Add source-address option to the ping CLI` +- {vytask}`T3431` `(bug): Show version all bug` +- {vytask}`T2920` `(bug): Commit crash when adding the second mGRE tunnel with the same key` + +## 2021-09-05 + +- {vytask}`T3804` `(feature): cli: Migrate and merge "system name-servers-dhcp" into "system name-server"` + +## 2021-09-04 + +- {vytask}`T3619` `(bug): Performance Degradation 1.2 --> 1.3 | High ksoftirqd CPU usage` + +## 2021-09-03 + +- {vytask}`T3788` `(bug): Keys are not allowed with ipip and sit tunnels` +- {vytask}`T3634` `(feature): Add op command option for ping for do not fragment bit to be set` +- {vytask}`T3798` `(feature): bgp: add support for "neighbor <X> local-as replace-as" option` + +## 2021-09-02 + +- {vytask}`T3792` `(bug): login: A hypen present in a username from "system login user" is replaced by an underscore` +- {vytask}`T3790` `(bug): Does not possible to configure PPTP static ip-address to users` +- {vytask}`T2947` `(bug): Nat translation many-many with prefix does not map 1-1.` + +## 2021-08-31 + +- {vytask}`T3789` `(feature): Add custom validator for base64 encoded CLI data` +- {vytask}`T3782` `(default): Ingress Shaping with IFB No Longer Functional with 1.3` + +## 2021-08-30 + +- {vytask}`T3768` `(default): Remove early syntaxVersion implementation` +- {vytask}`T2941` `(default): Using a non-ASCII character in the description field causes UnicodeDecodeError in configsource.py` +- {vytask}`T3787` `(bug): Remove deprecated UDP fragmentation offloading option` + +## 2021-08-29 + +- {vytask}`T3708` `(bug): isisd and gre-bridge commit error` +- {vytask}`T3783` `(bug): "set protocols isis spf-delay-ietf" is not working` +- {vytask}`T2750` `(default): Use m4 as a template processor` + +## 2021-08-28 + +- {vytask}`T3743` `(bug): l2tp doesn't work after reboot if outside-address not 0.0.0.0` + +## 2021-08-27 + +- {vytask}`T3182` `(bug): Main blocker Task for FRR 7.4/7.5 series update` +- {vytask}`T3568` `(feature): Add XML for firewall conf-mode` +- {vytask}`T2108` `(default): Use minisign/signify instead of GPG for release signing` + +## 2021-08-26 + +- {vytask}`T3776` `(default): Rename FRR daemon restart op-mode commands` +- {vytask}`T3739` `(feature): policy: route-map: add EVPN match support` + +## 2021-08-25 + +- {vytask}`T3773` `(bug): Delete the "show system integrity" command (to prepare for a re-implementation)` +- {vytask}`T3775` `(bug): Typo in generated Strongswan VPN-config` + +## 2021-08-24 + +- {vytask}`T3772` `(bug): VRRP virtual interfaces are not shown in show interfaces` + +## 2021-08-23 + +- {vytask}`T3769` `(feature): Containers: Network Bridging` + +## 2021-08-22 + +- {vytask}`T3090` `(feature): Move 'adjust-mss' firewall options to the interface section.` +- {vytask}`T3765` `(default): container: additional op-mode commands` + +## 2021-08-20 + +- {vytask}`T1950` `(default): Store VyOS configuration syntax version data in JSON file` + +## 2021-08-19 + +- {vytask}`T3751` `(bug): pki generate ca add new line after passphrase` +- {vytask}`T3764` `(bug): Unconfigurable IKE and ESP lifetime` +- {vytask}`T3234` `(bug): multi_to_list fails in certain cases, with root cause an element redundancy in XML interface-definitions` +- {vytask}`T3732` `(feature): override-default helper should support adding defaultValues to default less nodes` +- {vytask}`T3759` `(default): [L3VPN] VPNv4/VPNv6 add commands` + +## 2021-08-18 + +- {vytask}`T3752` `(bug): generate pki certificate file xxx doesn't touch file` + +## 2021-08-16 + +- {vytask}`T3738` `(default): openvpn fails if server and authentication are configured` +- {vytask}`T1594` `(bug): l2tpv3 error on IPv6 local-ip` + +## 2021-08-15 + +- {vytask}`T3756` `(default): VyOS generates invalid QR code for wireguard clients` +- {vytask}`T3757` `(default): OSPF: add support to configure the area at an interface level` + +## 2021-08-14 + +- {vytask}`T3745` `(feature): op-mode IPSec show vpn ipse sa sorting` + +## 2021-08-13 + +- {vytask}`T3749` `(bug): V4/V6 Counters in network container validation aren't being reset` +- {vytask}`T3728` `(bug): FRR not respect configured RD and RT for L3VNI` +- {vytask}`T3727` `(bug): VPN IPsec ESP proposal and ESP presented in config missmatch` +- {vytask}`T3740` `(bug): HTTPs API breaks when the address is IPv6` + +## 2021-08-12 + +- {vytask}`T3731` `(bug): verify_accel_ppp_base_service return wrong config error for SSP` +- {vytask}`T3405` `(feature): PPPoE server unit-cache` +- {vytask}`T2432` `(default): dhcpd: Can't create new lease file: Permission denied` +- {vytask}`T3746` `(feature): Inform users logging into the system about a pending reboot` +- {vytask}`T3744` `(default): Dns forwarding statistics formatting missing a new line` + +## 2021-08-11 + +- {vytask}`T3709` `(feature): Snmp: Allow enable MIDs/OIDs ipCidrRouteTable` + +## 2021-08-09 + +- {vytask}`T3720` `(bug): IPSec set vti secondary address cause interface disable` + +## 2021-08-08 + +- {vytask}`T3705` `(bug): IPSec: VTI interface does not honor default-esp-group` +- {vytask}`T2027` `(bug): get_config_dict is failing when the configuration section is empty/missing` + +## 2021-08-05 + +- {vytask}`T3719` `(bug): Restart vpn shows some missed files` + +## 2021-08-04 + +- {vytask}`T3704` `(feature): Add ability to interact with Areca RAID adapers` +- {vytask}`T3718` `(bug): VPN IPsec IKE group by default not use DH-group 2` + +## 2021-08-02 + +- {vytask}`T3601` `(default): Error in ssh keys for vmware cloud-init if ssh keys is left empty.` + +## 2021-08-01 + +- {vytask}`T3707` `(bug): Ping incorrect ip host checks` + +## 2021-07-31 + +- {vytask}`T3716` `(feature): Linux kernel parameters ignore_routes_with_link_down- ignore disconnected routing connections` + +## 2021-07-30 + +- {vytask}`T1176` `(default): FRR - BGP replicating routes` +- {vytask}`T1210` `(feature): About IKEv2 IPSec VPN remote access` + +## 2021-07-23 + +- {vytask}`T3699` `(bug): login: verify selected "system login user" name is not already used by the base system.` +- {vytask}`T3698` `(default): Support bridge monitoring` + +## 2021-07-13 + +- {vytask}`T3679` `(default): Point the unexpected exception message link to the new rolling release location` + +## 2021-07-11 + +- {vytask}`T3665` `(bug): Missing VRF support for VxLAN but already documented` + +## 2021-07-10 + +- {vytask}`T3636` `(feature): SSTP / L2TP ipv6 support broken` + +## 2021-07-09 + +- {vytask}`T3667` `(bug): brctl is damaged` + +## 2021-07-06 + +- {vytask}`T3660` `(feature): Conntrack-Sync configuration command to specify destination udp port for peer` + +## 2021-07-03 + +- {vytask}`T57` `(enhancment): Make it possible to disable the entire IPsec peer` + +## 2021-07-01 + +- {vytask}`T3658` `(feature): Add support for dhcpdv6 fixed-prefix6` +- {vytask}`T2035` `(bug): Executing vyos-smoketest multiple times makes ssh test fail on execution` + +## 2021-06-29 + +- {vytask}`T3593` `(bug): PPPoE server called-sid format does not work` +- {vytask}`T1441` `(feature): Add support for IPSec XFRM interfaces` + +## 2021-06-25 + +- {vytask}`T3641` `(feature): Upgrade base system from Debian Buster -> Debian Bullseye` +- {vytask}`T3649` `(feature): Add bonding additional hash-policy` + +## 2021-06-23 + +- {vytask}`T3647` `(feature): Bullseye: gcc defaults to passing --as-needed to linker` + +## 2021-06-22 + +- {vytask}`T3629` `(bug): IPoE server shifting address in the range` +- {vytask}`T3645` `(feature): Bullseye: ethtool changed output for ring-buffer information` + +## 2021-06-21 + +- {vytask}`T3563` `(default): commit-archive breaks with IPv6 source addresses` + +## 2021-06-20 + +- {vytask}`T3637` `(bug): vrf: bind-to-all didn't work properly` +- {vytask}`T3639` `(default): GCC preprocessor clobbers C comments` + +## 2021-06-19 + +- {vytask}`T3633` `(feature): Add LRO offload for interface ethernet` + +## 2021-06-18 + +- {vytask}`T3599` `(default): Migrate NHRP to XML/Python` + +## 2021-06-17 + +- {vytask}`T3624` `(feature): BGP: add support for extended community bandwidth definition` + +## 2021-06-16 + +- {vytask}`T3623` `(default): Fix for dummy interface option in the operational command "clear interfaces dummy"` +- {vytask}`T3630` `(feature): op-mode: add "show version kernel" command` + +## 2021-06-13 + +- {vytask}`T3620` `(feature): Rename WWAN interface from wirelessmodem to wwan to use QMI interface` +- {vytask}`T2173` `(feature): Add the ability to use VRF on VTI interfaces` +- {vytask}`T3622` `(feature): WWAN: add support for APN authentication` +- {vytask}`T3606` `(bug): SNMP unknown notification OID` +- {vytask}`T3621` `(bug): PPPoE interface does not validate if password is supplied when username is set` + +## 2021-06-12 + +- {vytask}`T3611` `(bug): WWAN interface (MC7710) no longer works on Kernel 5.10` +- {vytask}`T1534` `(bug): IPSec w/ IKEv2 Invalid local-address "any"` +- {vytask}`T3616` `(bug): Update to FastAPI causes regression in vyos-http-api-server` + +## 2021-06-11 + +- {vytask}`T3614` `(bug): Container network name with hyphen fail` + +## 2021-06-10 + +- {vytask}`T3250` `(bug): PPPoE server: wrong local usernames` +- {vytask}`T3138` `(bug): ddclient improperly updated when apply rfc2136 config` +- {vytask}`T2645` `(default): Editing route-map action requires adding a new rule` + +## 2021-06-08 + +- {vytask}`T3605` `(default): Allow to set prefer-global for ipv6-next-hop` +- {vytask}`T3607` `(feature): [route-map] set ipv6 next-hop prefer-global` +- {vytask}`T3289` `(bug): No description for node "service" conf-mode` + +## 2021-06-07 + +- {vytask}`T3461` `(bug): OpenConnect Server redundancy check` +- {vytask}`T3455` `(bug): system users can not be added in "edit"` +- {vytask}`T3588` `(default): IPSec: migrate no longer available options from CLI which are now hardcoded/enabled in strongSwan` + +## 2021-06-06 + +- {vytask}`T842` `(feature): Adopt VyOS CLI to latest StrongSwan options and deprecated Keywords` + +## 2021-06-04 + +- {vytask}`T3595` `(default): Cannot create new VTI interface` +- {vytask}`T3592` `(feature): Set default TTL 64 for tunnels` + +## 2021-06-03 + +- {vytask}`T3384` `(feature): Support UDP bandwidth testing` + +## 2021-06-02 + +- {vytask}`T3233` `(bug): Interface redirect to dum0` + +## 2021-06-01 + +- {vytask}`T3585` `(default): Fix NHRP module for updated interfaces tunnel syntax` +- {vytask}`T3594` `(bug): Disable by default service strongswan-starter` + +## 2021-05-30 + +- {vytask}`T3518` `(bug): Warning messages when using SCP commit-archive` +- {vytask}`T3093` `(default): Add xml for vpn ipsec` +- {vytask}`T1866` `(bug): Commit archive over SFTP doesn't work with non-standard ports` +- {vytask}`T3590` `(feature): bgp: add option for limiting maximum number of prefixes to be sent to a peer` +- {vytask}`T3589` `(feature): op-mode: support clearing out logfiles from CLI` +- {vytask}`T2641` `(feature): Rewrite vpn ipsec OP commands in new style XML syntax` +- {vytask}`T3351` `(feature): Installer checking MD5 checksums on the ISO image` + +## 2021-05-29 + +- {vytask}`T1944` `(bug): FRR: Invalid route in BGP causes update storm, memory leak, and failure of Zebra` +- {vytask}`T1888` `(feature): Update to StrongSwan 5.9.1` + +## 2021-05-27 + +- {vytask}`T3561` `(feature): router-advert: support advertising specific routes` +- {vytask}`T2669` `(bug): DHCP-server overlapping ranges.` + +## 2021-05-26 + +- {vytask}`T3540` `(bug): Keepalived memory utilisation issue when constantly getting its state in JSON format` + +## 2021-05-24 + +- {vytask}`T3575` `(bug): pseudo-ethernet: must check source-interface MTU` +- {vytask}`T3571` `(bug): Broken Show Tab Complete` +- {vytask}`T3555` `(bug): GRE TAP tunnel does not silent fragment packets / kernel fix available` +- {vytask}`T3576` `(bug): ISIS does not support IPV6` + +## 2021-05-23 + +- {vytask}`T3570` `(default): Prevent setting of a larger MTU on child interfaces` +- {vytask}`T3573` `(bug): as-path-prepend Description Invalid` +- {vytask}`T3572` `(feature): Basic Drive Diagnostic Tools` + +## 2021-05-22 + +- {vytask}`T3564` `(default): Multiple BGP Confederation Peers Not Allowed` + +## 2021-05-21 + +- {vytask}`T3551` `(bug): QoS control failure of VLAN sub interface` + +## 2021-05-20 + +- {vytask}`T3554` `(feature): Add area-type stub for ospfv3` +- {vytask}`T3565` `(feature): sysctl: rewrite in XML and Python and drop from vyatta-cfg-system` + +## 2021-05-19 + +- {vytask}`T3562` `(feature): Update Accel-PPP to a newer revision` +- {vytask}`T3559` `(feature): Add restart op-command for OpenConnect Server` + +## 2021-05-18 + +- {vytask}`T3525` `(default): VMWare resume script syntax errors` + +## 2021-05-15 + +- {vytask}`T3549` `(bug): DHCPv6 "service dhcpv6-server global-parameters name-server" is not correctly exported to dhcpdv6.conf when multiple name-server entries are present` +- {vytask}`T3532` `(bug): Not possible to change ethertype after interface creation` +- {vytask}`T3550` `(bug): Router-advert completion typo` +- {vytask}`T3547` `(feature): conntrackd: remove deprecated config options` +- {vytask}`T3535` `(feature): Rewrite vyatta-conntrack-sync in new XML and Python flavor` + +## 2021-05-14 + +- {vytask}`T3346` `(bug): nat 4-to-5 migration script fails when a 'source' or 'destination' node exists but there are no rules` +- {vytask}`T3248` `(default): Deal with VRRP mode-force command that exists in 1.2 but not in 1.3` +- {vytask}`T3426` `(default): add support for script arguments to vyos-configd` + +## 2021-05-13 + +- {vytask}`T3539` `(bug): Typo in RPKI interface definition` +- {vytask}`T439` `(feature): local PBR support` +- {vytask}`T3544` `(feature): DHCP server should validate configuration before applying it` +- {vytask}`T3543` `(feature): Support for setting lacp_rate on LACP bonded interfaces` + +## 2021-05-12 + +- {vytask}`T3302` `(default): Make vyos-configd relay stdout from scripts to the user's console` +- {vytask}`T3542` `(bug): udev net.rules not installed in image since may 2nd` + +## 2021-05-10 + +- {vytask}`T3374` `(bug): IPv6 GRE Tunnel issues` + +## 2021-05-09 + +- {vytask}`T3530` `(bug): BGP peer-group can't contain a hyphen` + +## 2021-05-06 + +- {vytask}`T3523` `(bug): VRF BGP daemon route-map command missing` +- {vytask}`T3519` `(bug): Cannot add / assign L2TPv3 to vrf` + +## 2021-05-05 + +- {vytask}`T3520` `(bug): Cannot add tunnel interface to isis within vrf` +- {vytask}`T3335` `(bug): Some OSPFv3 show commands do not work` + +## 2021-05-04 + +- {vytask}`T3504` `(feature): BGP Per Peer Graceful Restart` + +## 2021-05-02 + +- {vytask}`T3511` `(bug): Update libnss-mapuser and libpam-radius packages from CUMULUS Linux` + +## 2021-05-01 + +- {vytask}`T3379` `(feature): Add global-parameters name-server for dhcpv6-server` +- {vytask}`T3491` `(default): Change Kernel HZ to 1000` + +## 2021-04-29 + +- {vytask}`T3503` `(bug): "route-reflector-client" fails when "remote-as" is "internal"` +- {vytask}`T3502` `(bug): "system ip multipath layer4-hashing" doesn't work` + +## 2021-04-28 + +- {vytask}`T3473` `(bug): IPSec op-mode show sa error` + +## 2021-04-27 + +- {vytask}`T2946` `(bug): Calling 'stty_size' causes show interfaces API to fail` + +## 2021-04-25 + +- {vytask}`T3490` `(bug): priority inversion on PBR "policy route" create, breaks default route from dhcp (live iso)` +- {vytask}`T3468` `(bug): Tunnel interfaces aren't suggested as being available for bridging (regression)` +- {vytask}`T3497` `(bug): Prefix list with rule containing only action is not detected as error during parse` +- {vytask}`T3492` `(bug): BGP Configuration Migration failed (badly!) from rolling 202102240218 to rolling 202104221210` +- {vytask}`T1802` `(feature): Wireguard QR code in cli for mobile devices` + +## 2021-04-24 + +- {vytask}`T3472` `(bug): commit-confirm script not found` +- {vytask}`T3439` `(bug): Commit-archive location not working for scp` + +## 2021-04-23 + +- {vytask}`T3395` `(bug): WAN load-balancing fails with nexthop dhcp` +- {vytask}`T3290` `(bug): Disabling GRE conntrack module fails` + +## 2021-04-20 + +- {vytask}`T3488` `(bug): Specifying an invalid "interface address" like dhcph leads to commit error` + +## 2021-04-18 + +- {vytask}`T3481` `(default): Exclude tag node values from key mangling` +- {vytask}`T3475` `(bug): XML dictionary cache unable to process syntaxVersion elements` + +## 2021-04-17 + +- {vytask}`T3470` `(bug): as-override isn't applied to frr` + +## 2021-04-15 + +- {vytask}`T3386` `(bug): PPPoE-server don't start with local authentication` +- {vytask}`T3190` `(feature): Unable to subtract value from local-preference in route-map` + +## 2021-04-14 + +- {vytask}`T3398` `(bug): Can't commit` +- {vytask}`T3055` `(bug): op-mode incorrect naming for ipsec policy-based tunnels` + +## 2021-04-13 + +- {vytask}`T3436` `(feature): Refactoring ospf op-mode for support vrf` +- {vytask}`T3434` `(feature): Refactoring bgp op-mode for support vrf` + +## 2021-04-12 + +- {vytask}`T3454` `(enhancment): dhclient reject option` +- {vytask}`T3328` `(bug): Bgp not possible to delete bgp route-map` + +## 2021-04-10 + +- {vytask}`T3460` `(bug): bgp, Configuration FRR failed while commiting code` + +## 2021-04-09 + +- {vytask}`T3464` `(bug): OSPF: route-map names containing a hypen are not "found"` + +## 2021-04-08 + +- {vytask}`T3462` `(default): show ipv6 bgp -- missing` +- {vytask}`T3463` `(bug): Prevent IPv4 Route exchange with IPv6 neighbors` + +## 2021-04-05 + +- {vytask}`T3438` `(bug): VRF: removing vif which belongs to a vrf, will delete the entire vrf from the operating system` +- {vytask}`T3418` `(bug): BGP: system wide known interface can not be used as neighbor` + +## 2021-04-04 + +- {vytask}`T3457` `(feature): Output the "monitor log" command in a colorful way` + +## 2021-03-31 + +- {vytask}`T3445` `(bug): vyos-1x build include not all nodes` + +## 2021-03-30 + +- {vytask}`T3448` `(bug): Loading vyos on a system without xdp installed fails` + +## 2021-03-29 + +- {vytask}`T3415` `(feature): bridge: add support for isolated interfaces (private-vlan)` +- {vytask}`T1711` `(feature): BGP - migrate from tagNode to node (remove ASN from tagNode)` + +## 2021-03-28 + +- {vytask}`T3440` `(bug): HTTP API: give uvicorn time to initialize before restarting Nginx proxy` + +## 2021-03-27 + +- {vytask}`T3423` `(bug): Cannot create ipv4 static route for default gateway in vrf` + +## 2021-03-26 + +- {vytask}`T3412` `(default): HTTP API: move to FastAPI as web framework` +- {vytask}`T2397` `(feature): HTTP API: export OpenAPI definition` + +## 2021-03-24 + +- {vytask}`T3419` `(bug): show interfaces | strip-private fails` + +## 2021-03-22 + +- {vytask}`T3284` `(bug): merge/load fail silently if unable to resolve host` + +## 2021-03-21 + +- {vytask}`T3417` `(default): ISIS: provide per VRF instance support` +- {vytask}`T3416` `(bug): NTP: when running inside a VRF op-mode commands do not work` + +## 2021-03-20 + +- {vytask}`T3392` `(bug): vrrp over dhcp default route bug (unexpected vrf)` +- {vytask}`T3373` `(feature): Upgrade to SaltStack version 3002.5` +- {vytask}`T3329` `(default): "system conntrack ignore" rules can no longer be created due to an iptables syntax change` +- {vytask}`T3300` `(feature): Add DHCP default route distance` +- {vytask}`T3306` `(feature): Extend set route-map aggregator as to 4 Bytes` + +## 2021-03-18 + +- {vytask}`T3411` `(default): Extend the redirect_stdout context manager in vyos-configd to redirect stdout from subprocesses` +- {vytask}`T3271` `(bug): qemu-kvm grub issue` + +## 2021-03-17 + +- {vytask}`T3413` `(bug): Configuring invalid IPv6 EUI64 address results in "OSError: illegal IP address string passed to inet_pton"` + +## 2021-03-14 + +- {vytask}`T3345` `(default): BGP: add per VRF instance support` +- {vytask}`T3344` `(default): Per VRF dynamic routing support` +- {vytask}`T3325` `(bug): Bgp listen-range wrong commit message` +- {vytask}`T1513` `(default): Move OSPF and RIP interface configuration under protocols` + +## 2021-03-13 + +- {vytask}`T3406` `(bug): tunnel: interface no longer supports specifying encaplimit none - or migrator is missing` +- {vytask}`T3407` `(bug): console-server: do not allow to spawn a console-server session on serial port used by "system console"` + +## 2021-03-11 + +- {vytask}`T3305` `(bug): Ingress qdisc does not work anymore in 1.3-rolling-202101 snapshot` +- {vytask}`T2927` `(bug): isc-dhcpd release and expiry events never execute` + +## 2021-03-09 + +- {vytask}`T3382` `(bug): Error creating Console Server` + +## 2021-03-08 + +- {vytask}`T3387` `(bug): Command "Monitor vpn ipsec" is not working` + +## 2021-03-07 + +- {vytask}`T3388` `(bug): show interfaces doesn't display pppoeX` +- {vytask}`T3211` `(feature): ability to redistribute ISIS into other routing protocols` + +## 2021-03-04 + +- {vytask}`T3377` `(bug): show interfaces throws error` + +## 2021-03-02 + +- {vytask}`T3375` `(bug): Interface becomes up at boot even when disabled` + +## 2021-02-28 + +- {vytask}`T3370` `(bug): dhcp: Invalid domain name "private"` +- {vytask}`T3369` `(feature): VXLAN: add IPv6 underlay support` +- {vytask}`T3363` `(bug): VyOS-Build interactive prompt when using Podman` +- {vytask}`T3320` `(bug): Bgp neighbor peer-group without peer-group fail` + +## 2021-02-27 + +- {vytask}`T3365` `(bug): Bgp neighbor interface ordering for remote-as` +- {vytask}`T3225` `(bug): Adding a BGP neighbor with an address on a local interface throws a vyos.frr.CommitError: Configuration FRR failed while committing code: ''` +- {vytask}`T3368` `(feature): macsec: add support for gcm-aes-256 cipher` +- {vytask}`T3173` `(feature): Need 'nopmtudisc' option for tunnel interface` + +## 2021-02-26 + +- {vytask}`T3324` `(bug): Bgp space in the password` +- {vytask}`T3357` `(default): HTTP-API redirect from http correct https port` +- {vytask}`T3323` `(bug): Bgp ttl-security and ebgp-multihop fail` + +## 2021-02-24 + +- {vytask}`T3303` `(feature): Change welcome message on boot` + +## 2021-02-22 + +- {vytask}`T3322` `(bug): Bgp neighbor timers not applyed to FRR config` +- {vytask}`T3327` `(bug): OSPFv3: Cannot add dummy interface` + +## 2021-02-21 + +- {vytask}`T3331` `(bug): Bgp unsuppress-map should be as "value leafNode"` +- {vytask}`T3330` `(bug): Bgp capability orf prefix-list fail` +- {vytask}`T3163` `(feature): ethernet ring-buffer can be set with an invalid value` + +## 2021-02-19 + +- {vytask}`T3326` `(bug): OSPFv3: Cannot add L2TPv3 interface` +- {vytask}`T3332` `(bug): BGP unnumbered - UnboundLocalError: local variable 'peer_group' referenced before assignment` + +## 2021-02-18 + +- {vytask}`T3259` `(default): many dnat rules makes the vyos http api crash, even showConfig op timeouts` + +## 2021-02-17 + +- {vytask}`T3312` `(feature): SolarFlare NICs support` + +## 2021-02-16 + +- {vytask}`T3313` `(bug): ospfv3 interface missing options` +- {vytask}`T3318` `(feature): Update Linux Kernel to v5.4.208 / 5.10.142` + +## 2021-02-15 + +- {vytask}`T3311` `(bug): BGP Error: Remote AS must be set for neighbor or peer-group` + +## 2021-02-14 + +- {vytask}`T2848` `(feature): bgp-add-path configuration options` + +## 2021-02-12 + +- {vytask}`T3301` `(bug): Wrong format and valueHelp for policy as-path-list regex` + +## 2021-02-11 + +- {vytask}`T3281` `(default): Rewrite protocol RIPng [conf-mode] to new XML/Python style` +- {vytask}`T3282` `(default): Add XML for [conf-mode] RIPng` +- {vytask}`T3279` `(default): Rewrite protocol STATIC [op-mode] to new XML/Python style` +- {vytask}`T3297` `(bug): Optimize irrelevant error stack hints` + +## 2021-02-08 + +- {vytask}`T3295` `(feature): Update Linux Kernel to v5.4.96 / 5.10.14` + +## 2021-02-05 + +- {vytask}`T3030` `(feature): Support ERSPAN Tunnel Protocol` + +## 2021-02-04 + +- {vytask}`T3283` `(feature): Support for IPv4 neigh tables` +- {vytask}`T3280` `(default): Add XML for [conf-mode] STATIC` + +## 2021-02-03 + +- {vytask}`T3278` `(feature): Add XML for "protocols vrf" [conf-mode]` +- {vytask}`T3239` `(default): XML: override 'defaultValue' for mtu of certain interfaces; remove workarounds` +- {vytask}`T2910` `(feature): XML: generator should support override of variables` + +## 2021-02-02 + +- {vytask}`T3018` `(bug): Unclear behaviour when configuring vif and vif-s interfaces` +- {vytask}`T3255` `(default): Rewrite protocol RPKI to new XML/Python style` +- {vytask}`T3263` `(feature): OSPF Hello subsecond timer` + +## 2021-01-31 + +- {vytask}`T3276` `(feature): Update Linux Kernel to v5.4.94 / 5.10.12` + +## 2021-01-30 + +- {vytask}`T3240` `(feature): Support per-interface DHCPv6 DUIDs` +- {vytask}`T3273` `(default): PPPoE static default-routes deleted on interface down when not added by interface up` + +## 2021-01-29 + +- {vytask}`T3261` `(bug): Does not possible to disable pppoe client interface.` +- {vytask}`T3272` `(default): OSPF: interface config is not removed` + +## 2021-01-27 + +- {vytask}`T3257` `(feature): tcpdump supporting complete protocol` +- {vytask}`T3244` `(default): Rewrite protocol OSPFv3 to new XML/Python style` + +## 2021-01-26 + +- {vytask}`T3251` `(bug): PPPoE client trying to authorize with the wrong username` +- {vytask}`T3256` `(default): Add XML for protocol RPKI [conf-mode]` + +## 2021-01-25 + +- {vytask}`T3249` `(feature): Support operation mode forwarding table output` + +## 2021-01-24 + +- {vytask}`T3227` `(bug): Latest releases don't work with RPKI (crash)` +- {vytask}`T3230` `(bug): RPKI can't be deleted` +- {vytask}`T3221` `(bug): FRR config` +- {vytask}`T3245` `(default): Add XML for protocol ospfv3 [conf-mode]` + +## 2021-01-23 + +- {vytask}`T3236` `(default): Add XML for [conf-mode] OSPF` + +## 2021-01-17 + +- {vytask}`T3222` `(bug): Typo in BGP dampening description` +- {vytask}`T3226` `(bug): Repair bridge smoke test damage` + +## 2021-01-16 + +- {vytask}`T3215` `(bug): Operational command "show ipv6 route" is broken` +- {vytask}`T3157` `(bug): salt-minion fails to start due to permission error accessing /root/.salt/minion.log` +- {vytask}`T3137` `(feature): Let VLAN aware bridge approach the behavior of professional equipment` + +## 2021-01-15 + +- {vytask}`T3210` `(feature): ISIS three-way-handshake` +- {vytask}`T3184` `(feature): Add correct desctiptions for BGP neighbors` + +## 2021-01-14 + +- {vytask}`T3213` `(bug): show interface command python error` + +## 2021-01-12 + +- {vytask}`T3205` `(bug): Does not possible to configure tunnel mode gre-bridge` + +## 2020-12-20 + +- {vytask}`T3132` `(feature): Enable egress flow accounting` + +## 2020-11-29 + +- {vytask}`T2297` `(feature): NTP add support for pool configuration` diff --git a/docs/changelog/md-1.5.md b/docs/changelog/md-1.5.md new file mode 100644 index 00000000..1471358f --- /dev/null +++ b/docs/changelog/md-1.5.md @@ -0,0 +1,32 @@ +# 1.5 Circinus + +% Please don't add anything by hand. +% This file is managed by the script: +% _ext/releasenotes.py + +## 2023-09-11 + +- {vytask}`T5562` `(bug): Smoketests fail for vyos:current (test_netns.py)` +- {vytask}`T5551` `(bug): Missing check for boot_configuration_complete raises error in vyos-save-config.py` +- {vytask}`T5353` `(bug): config-mgmt: normalize archive updates and commit log entries` + +## 2023-09-10 + +- {vytask}`T5555` `(bug): Fix timezone migrator (system 13-to-14)` + +## 2023-09-09 + +- {vytask}`T5423` `(bug): ipsec: no output for op-cmd "show vpn ike secrets"` + +## 2023-09-08 + +- {vytask}`T5560` `(bug): VyOS version in current branch should be changed from 1.4 to 1.5` + +## 2023-09-07 + +- {vytask}`T5556` `(bug): reboot now and poweroff does not work` +- {vytask}`T5489` `(feature): Change to BBR as TCP congestion control, or at least make it an config option` + +## 2023-09-06 + +- {vytask}`T5548` `(bug): HAProxy renders timeouts incorrectly` diff --git a/docs/changelog/md-index.md b/docs/changelog/md-index.md new file mode 100644 index 00000000..82511ed6 --- /dev/null +++ b/docs/changelog/md-index.md @@ -0,0 +1,19 @@ +(release-notes)= + +# Changelog + +```{eval-rst} +.. toctree:: + :maxdepth: 1 + :includehidden: + + 1.5 + 1.4 + 1.3 + 1.2.6 + 1.2.5 + 1.2.4 + 1.2.3 + 1.2.2 + 1.2.1 +``` diff --git a/docs/conf.py b/docs/conf.py index 02135cc1..b2bc2c86 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -13,6 +13,7 @@ # documentation root, use os.path.abspath to make it absolute, like shown here. # import os +import shutil import sys sys.path.append(os.path.abspath("./_ext")) @@ -48,7 +49,7 @@ extensions = ['sphinx.ext.intersphinx', 'autosectionlabel', 'myst_parser', 'sphinx_design', - 'vyos' + 'vyos', ] # Add any paths that contain templates here, relative to this directory. @@ -57,13 +58,15 @@ templates_path = ['_templates'] # autosectionlabel autosectionlabel_prefix_document = True - # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # # source_suffix = ['.rst', '.md'] source_suffix = ['.rst', '.md'] +myst_enable_extensions = ["colon_fence", "deflist", "fieldlist", "substitution"] +myst_fence_as_directive = ["cfgcmd", "opcmd", "cmdincludemd"] + # The master toctree document. master_doc = 'index' @@ -79,11 +82,20 @@ locale_dirs = ['_locale/'] gettext_compact = True gettext_uuid = False - # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path . -exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store', '_include/vyos-1x'] +exclude_patterns = [ + u'_build', 'Thumbs.db', '.DS_Store', '_include/vyos-1x', + 'md-*.md', '**/md-*.md', +] + +import pathlib +_build = pathlib.Path(__file__).parent / '_build' +if (_build / '_swap_state.json').exists() and (_build / '_swap_exclude.txt').exists(): + exclude_patterns.extend( + s for s in (line.strip() for line in (_build / '_swap_exclude.txt').read_text().splitlines()) if s + ) # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' @@ -138,19 +150,23 @@ html_context = { # The name of an image file (relative to this directory) to place at the top # of the sidebar. -html_logo = '_static/images/vyos-logo.png' +html_logo = '_static/images/vyos-logo.webp' # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. html_favicon = '_static/images/vyos-logo-icon.png' +# The "title" for HTML documentation generated with Sphinx's own templates. +# This is appended to the `<title>` tag of individual pages, and used +# in the navigation bar as the "topmost" element. +html_title = f'{project} rolling release (current)' + # -- Options for HTMLHelp output --------------------------------------------- # Output file base name for HTML help builder. htmlhelp_basename = 'VyOSdoc' - # -- Options fo_r LaTeX output ------------------------------------------------ latex_elements = { @@ -195,7 +211,6 @@ man_pages = [ [author], 1) ] - # -- Options for Texinfo output ---------------------------------------------- # Grouping the document tree into Texinfo files. List of tuples @@ -207,6 +222,24 @@ texinfo_documents = [ 'Miscellaneous'), ] +def _prefer_webp(app): + """Prepend WebP to supported image types for HTML builders.""" + if app.builder.name in ('html', 'dirhtml', 'readthedocs'): + types = app.builder.supported_image_types + if 'image/webp' not in types: + app.builder.supported_image_types = ['image/webp'] + types + +def _copy_md_sources(app, exception): + """Copy .md source files verbatim into the HTML output tree.""" + if exception is not None: + return + src = pathlib.Path(app.srcdir) + out = pathlib.Path(app.outdir) + for path in src.rglob("*.md"): + dest = out / path.relative_to(src) + dest.parent.mkdir(parents=True, exist_ok=True) + shutil.copy2(path, dest) def setup(app): - pass + app.connect('builder-inited', _prefer_webp) + app.connect('build-finished', _copy_md_sources) diff --git a/docs/configexamples/autotest/DHCPRelay_through_GRE/_include/topology.webp b/docs/configexamples/autotest/DHCPRelay_through_GRE/_include/topology.webp Binary files differnew file mode 100644 index 00000000..592484cb --- /dev/null +++ b/docs/configexamples/autotest/DHCPRelay_through_GRE/_include/topology.webp diff --git a/docs/configexamples/autotest/DHCPRelay_through_GRE/md-DHCPRelay_through_GRE.md b/docs/configexamples/autotest/DHCPRelay_through_GRE/md-DHCPRelay_through_GRE.md new file mode 100644 index 00000000..bf77bcc9 --- /dev/null +++ b/docs/configexamples/autotest/DHCPRelay_through_GRE/md-DHCPRelay_through_GRE.md @@ -0,0 +1,96 @@ +# DHCP Relay trough GRE-Bridge + +Testdate: 2023-05-11 + +Version: 1.4-rolling-202305100734 + +This simple structure shows how to configure a DHCP Relay over a GRE Bridge +interface. + +## Topology + +The topology has 3 VyOS routers and one client. Between the DHCP Server and +the DHCP Relay is a GRE tunnel. The `transport` VyOS represent a large +Network. + +```{image} _include/topology.png +:alt: Ansible Example topology image +``` + +## Configuration + +First, we configure the transport network and the Tunnel interface. + +Transport: + +```{eval-rst} +.. literalinclude:: _include/transport.conf + :language: none + +``` + +DHCP-Server + +```{eval-rst} +.. literalinclude:: _include/dhcp-server.conf + :language: none + :lines: 1-8 + +``` + +DHCP-Relay + +```{eval-rst} +.. literalinclude:: _include/dhcp-relay.conf + :language: none + :lines: 1-8 + +``` + +After this, we need the DHCP-Server and Relay configuration. +To get a testable result, we just have one IP in the DHCP range. +Expand it as you need it. + +DHCP-Server + +```{eval-rst} +.. literalinclude:: _include/dhcp-server.conf + :language: none + :lines: 9-13 + +``` + +DHCP-Relay + +```{eval-rst} +.. literalinclude:: _include/dhcp-relay.conf + :language: none + :lines: 9-10 + +``` + +## Test the result + +Ping the Client from the DHCP Server. + +```none +vyos@dhcp-server:~$ ping 192.168.0.30 count 4 +PING 192.168.0.30 (192.168.0.30) 56(84) bytes of data. +64 bytes from 192.168.0.30: icmp_seq=1 ttl=63 time=1.02 ms +64 bytes from 192.168.0.30: icmp_seq=2 ttl=63 time=1.06 ms +64 bytes from 192.168.0.30: icmp_seq=3 ttl=63 time=1.21 ms +64 bytes from 192.168.0.30: icmp_seq=4 ttl=63 time=1.16 ms + +--- 192.168.0.30 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 3004ms +rtt min/avg/max/mdev = 1.016/1.112/1.214/0.077 ms +``` + +And show all DHCP Leases + +```none +vyos@dhcp-server:~$ show dhcp server leases +IP Address MAC address State Lease start Lease expiration Remaining Pool Hostname +------------ ----------------- ------- ------------------- ------------------- ----------- ---------- ---------- +192.168.0.30 00:50:79:66:68:05 active 2023/05/11 13:08:50 2023/05/12 13:08:50 23:59:16 DHCPTun100 VPCS +``` diff --git a/docs/configexamples/autotest/L3VPN_EVPN/_include/topology.webp b/docs/configexamples/autotest/L3VPN_EVPN/_include/topology.webp Binary files differnew file mode 100644 index 00000000..f3218799 --- /dev/null +++ b/docs/configexamples/autotest/L3VPN_EVPN/_include/topology.webp diff --git a/docs/configexamples/autotest/L3VPN_EVPN/md-L3VPN_EVPN.md b/docs/configexamples/autotest/L3VPN_EVPN/md-L3VPN_EVPN.md new file mode 100644 index 00000000..38ae9e8f --- /dev/null +++ b/docs/configexamples/autotest/L3VPN_EVPN/md-L3VPN_EVPN.md @@ -0,0 +1,250 @@ +# L3VPN EVPN with VyOS + +Testdate: 2023-05-11 + +Version: 1.4-rolling-202305100734 + +I spun up a new lab in EVE-NG, which represents this as the +"Foo Bar - Service Provider Inc." that has 3 points of presence (PoP) in random +datacenters/sites named PE1, PE2, and PE3. Each PoP aggregates at least two +customers. + +I named the customers blue, red and green which is common practice in +VRF (Virtual Routing and Forwarding) documentation scenarios. + +- PE1 is located in an industrial area that holds multiple office buildings. + All customers have a site in this area. +- PE2 is located in a smaller area where by coincidence two customers + (blue and red) share an office building. +- PE3 is located in a smaller area where by coincidence two customers + (blue and green) are located. + +## Management VRF + +A brief excursion into VRFs: This has been one of the longest-standing feature +requests of VyOS (dating back to 2016) which can be described as +"a VLAN for layer 2 is what a VRF is for layer 3". +With VRFs, a router/system can hold multiple, isolated routing tables on the +same system. If you wonder what's the difference between multiple tables that +people used for policy-based routing since forever, it's that a VRF also +isolates connected routes rather than just static and dynamically learned +routes, so it allows NICs in different VRFs to use conflicting network +ranges without issues. + +VyOS 1.3 added initial support for VRFs (including IPv4/IPv6 static routing) +and VyOS 1.4 now enables full dynamic routing protocol support for +OSPF, IS-IS, and BGP for individual VRFs. + +The lab I built is using a VRF (called **mgmt**) to provide out-of-band +SSH access to the PE (Provider Edge) routers. + +```{eval-rst} +.. literalinclude:: _include/PE1.conf + :language: none + :lines: 1-6 + +``` + +## Topology + +We use the following network topology in this example: + +```{image} _include/topology.png +:alt: L3VPN EVPN with VyOS topology image +``` + +## Core network + +I chose to run OSPF as the IGP (Interior Gateway Protocol). +All required BGP sessions are established via a dummy interfaces +(similar to the loopback, but in Linux you can have only one loopback, +while there can be many dummy interfaces) on the PE routers. In case of a link +failure, traffic is diverted in the other direction in this triangle setup and +BGP sessions will not go down. One could even enable +BFD (Bidirectional Forwarding Detection) on the links for a faster +failover and resilience in the network. + +Regular VyOS users will notice that the BGP syntax has changed in VyOS 1.4 from +even the prior post about this subject. This is due to T1711, where it was +finally decided to get rid of the redundant BGP ASN (Autonomous System Number) +specification on the CLI and move it to a single leaf node +(set protocols bgp local-as). + +It's important to note that all your existing configurations will be migrated +automatically on image upgrade. Nothing to do on your side. + +PE1 + +```{eval-rst} +.. literalinclude:: _include/PE1.conf + :language: none + :lines: 8-38 +``` + +PE2 + +```{eval-rst} +.. literalinclude:: _include/PE2.conf + :language: none + :lines: 8-38 +``` + +PE3 + +```{eval-rst} +.. literalinclude:: _include/PE3.conf + :language: none + :lines: 8-38 + +``` + +## Tenant networks (VRFs) + +Once all routers can be safely remotely managed and the core network is +operational, we can now setup the tenant networks. + +Every tenant is assigned an individual VRF that would support overlapping +address ranges for customers blue, red and green. In our example, +we do not use overlapping ranges to make it easier when showing debug commands. + +Thus you can easily match it to one of the devices/networks below. + +Every router that provides access to a customer network needs to have the +customer network (VRF + VNI) configured. To make our own lives easier, +we utilize the same VRF table id (local routing table number) and +VNI (Virtual Network Identifier) per tenant on all our routers. + +- blue uses local routing table id and VNI 2000 +- red uses local routing table id and VNI 3000 +- green uses local routing table id and VNI 4000 + +PE1 + +```{eval-rst} +.. literalinclude:: _include/PE1.conf + :language: none + :lines: 40-96 +``` + +PE2 + +```{eval-rst} +.. literalinclude:: _include/PE2.conf + :language: none + :lines: 40-89 +``` + +PE3 + +```{eval-rst} +.. literalinclude:: _include/PE3.conf + :language: none + :lines: 40-89 +``` + +## Testing and debugging + +You managed to come this far, now we want to see the network and routing +tables in action. + +Show routes for all VRFs + +```none +vyos@PE1:~$ show ip route vrf all +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +VRF blue: +C>* 10.1.1.0/24 is directly connected, br2000, 00:01:13 +B>* 10.1.2.0/24 [200/0] via 172.29.255.2, br2000 onlink, weight 1, 00:00:49 +B>* 10.1.3.0/24 [200/0] via 172.29.255.3, br2000 onlink, weight 1, 00:00:49 + +VRF default: +O 172.29.0.2/31 [110/1] is directly connected, eth1, weight 1, 00:01:09 +C>* 172.29.0.2/31 is directly connected, eth1, 00:01:12 +O>* 172.29.0.4/31 [110/2] via 172.29.0.3, eth1, weight 1, 00:00:46 + * via 172.29.0.7, eth3, weight 1, 00:00:46 +O 172.29.0.6/31 [110/1] is directly connected, eth3, weight 1, 00:01:09 +C>* 172.29.0.6/31 is directly connected, eth3, 00:01:12 +C>* 172.29.255.1/32 is directly connected, dum0, 00:01:14 +O>* 172.29.255.2/32 [110/20] via 172.29.0.3, eth1, weight 1, 00:00:50 +O>* 172.29.255.3/32 [110/20] via 172.29.0.7, eth3, weight 1, 00:00:45 + +VRF green: +C>* 10.3.1.0/24 is directly connected, br4000, 00:01:13 +B>* 10.3.3.0/24 [200/0] via 172.29.255.3, br4000 onlink, weight 1, 00:00:49 + +VRF mgmt: +S>* 0.0.0.0/0 [210/0] via 10.100.0.1, eth0, weight 1, 00:01:45 +C>* 10.100.0.0/24 is directly connected, eth0, 00:01:45 + +VRF red: +C>* 10.2.1.0/24 is directly connected, br3000, 00:01:13 +B>* 10.2.2.0/24 [200/0] via 172.29.255.2, br3000 onlink, weight 1, 00:00:49 +``` + +Information about Ethernet Virtual Private Networks + +```none +vyos@PE1:~$ show bgp l2vpn evpn +BGP table version is 1, local router ID is 172.29.255.1 +Status codes: s suppressed, d damped, h history, * valid, > best, i - internal +Origin codes: i - IGP, e - EGP, ? - incomplete +EVPN type-1 prefix: [1]:[EthTag]:[ESI]:[IPlen]:[VTEP-IP]:[Frag-id] +EVPN type-2 prefix: [2]:[EthTag]:[MAClen]:[MAC]:[IPlen]:[IP] +EVPN type-3 prefix: [3]:[EthTag]:[IPlen]:[OrigIP] +EVPN type-4 prefix: [4]:[ESI]:[IPlen]:[OrigIP] +EVPN type-5 prefix: [5]:[EthTag]:[IPlen]:[IP] + + Network Next Hop Metric LocPrf Weight Path +Route Distinguisher: 10.1.1.1:5 +*> [5]:[0]:[24]:[10.1.1.0] + 172.29.255.1 0 32768 ? + ET:8 RT:100:2000 Rmac:4e:bb:3c:ba:bd:a6 +Route Distinguisher: 10.1.2.1:4 +*>i[5]:[0]:[24]:[10.1.2.0] + 172.29.255.2 0 100 0 ? + RT:100:2000 ET:8 Rmac:26:07:da:eb:fc:ea +Route Distinguisher: 10.1.3.1:4 +*>i[5]:[0]:[24]:[10.1.3.0] + 172.29.255.3 0 100 0 ? + RT:100:2000 ET:8 Rmac:26:98:28:24:6e:54 +Route Distinguisher: 10.2.1.1:6 +*> [5]:[0]:[24]:[10.2.1.0] + 172.29.255.1 0 32768 ? + ET:8 RT:100:3000 Rmac:50:00:00:01:00:05 +Route Distinguisher: 10.2.2.1:5 +*>i[5]:[0]:[24]:[10.2.2.0] + 172.29.255.2 0 100 0 ? + RT:100:3000 ET:8 Rmac:50:00:00:02:00:05 +Route Distinguisher: 10.3.1.1:7 +*> [5]:[0]:[24]:[10.3.1.0] + 172.29.255.1 0 32768 ? + ET:8 RT:100:4000 Rmac:50:00:00:01:00:06 +Route Distinguisher: 10.3.3.1:6 +*>i[5]:[0]:[24]:[10.3.3.0] + 172.29.255.3 0 100 0 ? + RT:100:4000 ET:8 Rmac:06:32:9d:22:55:8a + +Displayed 7 out of 7 total prefixes +``` + +If we need to retrieve information about a specific host/network inside +the EVPN network we need to run + +```none +vyos@PE2:~$ show bgp l2vpn evpn 10.3.1.10 +BGP routing table entry for 10.3.1.1:7:[5]:[0]:[24]:[10.3.1.0] +Paths: (1 available, best #1) + Not advertised to any peer + Route [5]:[0]:[24]:[10.3.1.0] VNI 4000 + Local + 172.29.255.1 (metric 20) from 172.29.255.1 (172.29.255.1) + Origin incomplete, metric 0, localpref 100, valid, internal, best (First path received) + Extended Community: RT:100:4000 ET:8 Rmac:50:00:00:01:00:06 + Last update: Thu May 11 13:31:13 2023 +``` diff --git a/docs/configexamples/autotest/OpenVPN_with_LDAP/_include/topology.webp b/docs/configexamples/autotest/OpenVPN_with_LDAP/_include/topology.webp Binary files differnew file mode 100644 index 00000000..13bf2d73 --- /dev/null +++ b/docs/configexamples/autotest/OpenVPN_with_LDAP/_include/topology.webp diff --git a/docs/configexamples/autotest/OpenVPN_with_LDAP/md-OpenVPN_with_LDAP.md b/docs/configexamples/autotest/OpenVPN_with_LDAP/md-OpenVPN_with_LDAP.md new file mode 100644 index 00000000..afc4e5af --- /dev/null +++ b/docs/configexamples/autotest/OpenVPN_with_LDAP/md-OpenVPN_with_LDAP.md @@ -0,0 +1,284 @@ +(examples-openvpn-with-ldap)= + +# OpenVPN with LDAP + +Testdate: 2023-05-11 + +Version: 1.4-rolling-202305100734 + +This LAB shows how to use OpenVPN with a Active Directory authentication method. + +Topology consists of: +: - Windows Server 2019 with a running Active Directory + - VyOS as a OpenVPN Server + - VyOS as Client + +```{image} _include/topology.png +:alt: OpenVPN with LDAP topology image +``` + +## Active Directory on Windows server + +The lab assumes a full running Active Directory on the Windows Server. +Here are some PowerShell commands to quickly add a Test Active Directory. + +```powershell +# install the Active Directory Server role +Install-WindowsFeature AD-Domain-Services -IncludeManagementTools + +# install the Active Directory Server role +Install-ADDSForest -DomainName "vyos.local" -DomainNetBiosName "VYOS" -InstallDns:$true -NoRebootCompletion:$true + +# create test user01 and binduser +New-ADUser binduser -AccountPassword(Read-Host -AsSecureString "Input Password") -Enabled $true +New-ADUser user01 -AccountPassword(Read-Host -AsSecureString "Input Password") -Enabled $true +``` + +## Configure VyOS as OpenVPN Server + +In this example OpenVPN will be setup with a client certificate and username / password authentication. + +First a CA, a signed server and client ceftificate and a Diffie-Hellman parameter musst be generated and installed. +Please look {ref}`here <configuration/pki/index:pki>` for more information. + +Add the LDAP plugin configuration file + +`/config/auth/ldap-auth.config` + +Check all possible settings + +[here](https://github.com/threerings/openvpn-auth-ldap/blob/master/auth-ldap.conf) + +```{eval-rst} +.. literalinclude:: _include/ldap-auth.config + :language: none + +``` + +Now generate all required certificates on the ovpn-server: + +First the CA + +```none +vyos@ovpn-server# run generate pki ca install OVPN-CA +``` + +after this create a signed server and a client certificate + +```none +vyos@ovpn-server# run generate pki certificate sign OVPN-CA install SRV +vyos@ovpn-server# run generate pki certificate sign OVPN-CA install CLIENT +``` + +and last the DH Key + +```none +vyos@ovpn-server# run generate pki dh install DH +``` + +after all these steps the config look like this: + +```none +set pki ca OVPN-CA certificate 'MIIFnTCCA4WgAwIBAgIUIPFIXvCxYdavCnSPFNjr6lUtlsswDQYJKoZIhvcNAQELBQAwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA1MTExMjM4MjJaFw0zMzA1MDgxMjM4MjJaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxEDAOBgNVBAMMB3Z5b3MuaW8wggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAwggIKAoICAQDg45vAzS6xNqU+Pa7wk1Imt1/az1C22Sbp3wPJLfgOmy0K3TA5qVsx/c/8gatsatMkCsekGnK5BPzCDd5eCCLo//B25HFO6fBYRNvHvVyCUx7QEXw4FHFNG88zCIizx114AGtVwZfGGG9xCc53xjLPUpH6iqTXme41cCFFQlqXwZ7fuySieSdoV8SAsJTTOsGCEUEcDEnNPn6tX3KWTzNuyFPECy8WCmNgWNyG2nmH+U7WRTX0ehZ5dZyU5au7TxpRN4a+JtE0gNqcWJ+nh1A543q2pcRoQpPAzHFclgj8wG/EyauQMY/LC4tLc6moPaNlTwA9HJv8s6xUqpzNptDoUHKOqKuw2JRFnno5SCQ788KkKNgVWBy2o3BGoewfHFhAdR61CXeLpmuneuhi96GcM031gW8ptXbd4DkCF7H6KRtqeIvwiyG79ttC8kZf01Sn1fM5fTjGxaE38dAk/RchtHRC6rtFavHJjB2cUcCkhhQofUE6IR2dYJZ1cw0Wy5CI3bXHf43BpvDGmuxIlNGirTq8wf5RCWzDJJgmkQpYhUYe8x4faF4gTo00uH4ZvAYjQu3JNZGkb50p4kM9Mu5rQAiZJUeMAz/QD+EIV9xXgOk14+BbnHKWbZ7Ou5emewFuE/bjl79oNJklpXdc4soRkCPCTEGK3zDBdmUtCYk1DwIDAQABo2EwXzAPBgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBhjAdBgNVHSUEFjAUBggrBgEFBQcDAgYIKwYBBQUHAwEwHQYDVR0OBBYEFP5NDac/yC+mQmaTpZDUv9GZMGMBMA0GCSqGSIb3DQEBCwUAA4ICAQDEqpF2ibwYFxsF1XDIPS5/Gs0sZTZBuByNm5d2+jTyO7d5alZUdbvobbwhxZOhWasmFNyPLr4TYmZm5zF+efFsiOxjyRuEoVU+Fe8rZmpRIF/+6+nYX5r9vMI4QxGjeeyP20OHJ85Kvz182CTsITrM15Vw/kVVjAVzFI5Gm/QolalAoFQza9rAL4kDqaUszjHjPbysvDpGF+NLPjiYDHXcty/BC48bnuzAeEM60SGZ7EXvf8l0X8YsO7z39w6780A/3rbZvFhCYMKp/+p5xBRDjnX91dM6DJw73RwYQ1KHbHk9wWUwnL1giL71jzp/y4Oj6SSK2PQv+OnO80J6Zg06WIQx9xYcxr108Xh9FotUrlG7GYPI3Udf95t6SjuydDhULAVD0lMBxlDe9DHW1k1q1pOXaHZg926tY66xx/lda6dcuwJjA2Dx5JI6L0u9ureQmQAtxvnoTCtf+hR1iX/IkskZCKs34SjNiCnBuw/DNfdOpfaABm7y+tWiXBwnu5l/K8poXcQYQByyZj6YMmpgsbVPr5KNsLWOgRA81M6IPof8qxvnFrkazhiQWh1YHSjnaHtA3z5/BdgwHVICuFyrIOlbkKyJOjKcKBsDdMwIV0tsnpnyli2xEPZKu1tAQFAavXrK/RGYYhOZ3e0aRSV8hlP8i/mf7p0I45cJiBCqPg==' +set pki ca OVPN-CA private key 'MIIJQwIBADANBgkqhkiG9w0BAQEFAASCCS0wggkpAgEAAoICAQDg45vAzS6xNqU+Pa7wk1Imt1/az1C22Sbp3wPJLfgOmy0K3TA5qVsx/c/8gatsatMkCsekGnK5BPzCDd5eCCLo//B25HFO6fBYRNvHvVyCUx7QEXw4FHFNG88zCIizx114AGtVwZfGGG9xCc53xjLPUpH6iqTXme41cCFFQlqXwZ7fuySieSdoV8SAsJTTOsGCEUEcDEnNPn6tX3KWTzNuyFPECy8WCmNgWNyG2nmH+U7WRTX0ehZ5dZyU5au7TxpRN4a+JtE0gNqcWJ+nh1A543q2pcRoQpPAzHFclgj8wG/EyauQMY/LC4tLc6moPaNlTwA9HJv8s6xUqpzNptDoUHKOqKuw2JRFnno5SCQ788KkKNgVWBy2o3BGoewfHFhAdR61CXeLpmuneuhi96GcM031gW8ptXbd4DkCF7H6KRtqeIvwiyG79ttC8kZf01Sn1fM5fTjGxaE38dAk/RchtHRC6rtFavHJjB2cUcCkhhQofUE6IR2dYJZ1cw0Wy5CI3bXHf43BpvDGmuxIlNGirTq8wf5RCWzDJJgmkQpYhUYe8x4faF4gTo00uH4ZvAYjQu3JNZGkb50p4kM9Mu5rQAiZJUeMAz/QD+EIV9xXgOk14+BbnHKWbZ7Ou5emewFuE/bjl79oNJklpXdc4soRkCPCTEGK3zDBdmUtCYk1DwIDAQABAoICACVsewzYmD6RU2pKJYSPX4pl1aO6ADqNZHZi0GR4K+FyXUqDiHTwA+cLz8K7aWV/WWeUC6j5ZcH4XH+Gg0yumfCgNsnyNhDlyUNHIjPZBT4Cywvg/QTwEfK8//wEHYudT6aam0IIF1O12UW8VgmEiAwMN5Kz476lNQjbgg3efujmJaQhpnULKE2q3V51BC8qhe05JdafDOEE11vOmGj/ARYcbCQhoFJQpDzyTLB8RuEj0cTCe7oVXwwTUF1O4wcmoMCHNvsJxqKwFrER5m+giu83NcKTT13yRlg9LVg094XoGDFtRgmW1dD6ONHzi3Yd28UOIoII8sRYugLU6YcnjXfrgxvKJHJywEEJobfS2o/2/mHh6kjv7pvppWdDhjkf+dWZ0frx2YyF5/dUgGG6e94hzOwRunEu4JVKl0Qr+Vfsqt/STVDA3vbhaMdMuIR2Ir0OkoYiqGBdiEGVx82lf4uDy2TXveqKUADXU5SchjP0JZpBANO4RVoxFpY2r1tEh/sRBu9wY+Fjk4FqdjjOmsbmFwhyG/j2VvKkVsq5itsxG/Rg1nTThE2LN+R6LUquujtn94rIaz6lukEr7Yq9qy14Prj5A7tYnuHbcN36b0A3xN7bxxeX6w12naVp0KZPmey6W4HNeNOOfTLh8BpG+TMPZLJq6U+fryHD2nIhk1mxAoIBAQD88A7vo3LIzas83bYaCa1BgjtJ6WUsqsriuG55pt8olzF/X0THkcDiozCy1IJchL4+GxxA0dp+NBispflvbFWZFAHMnbJx4cc7qMR9k8DDSHNQVgfV6nBa4xBvjBp+sanOOOLV4p+fQZW+n6VMzCcKC74awjbIKgPY0LhUQxIVjtzFyor+MLLoqeavxWzBVVBslwR2oyjbTtTMkeNuTyC4kQAJcfWDN/s2bl6P8Mldpik2WhW0GdxHyK3sgZWXIrnkTlQg3EMPb2sPhFZm6pQKpxXwl8gGgFzEx4mEpHxHm/igZPVRTnYfGwkPmHu3caF59IWHq4jsUAxRQperRgStAoIBAQDjnJ4dZgcnI4PxiDKDKXeb5ZgjnIL0eyxMZoLtaVYnO2lLG0uMlACUEuRwGz4acQcjRoW4FOh3NSberobSHOVBO9Y3qgEcTtgJvzkso5IXD76/vmpiYFdPo9aGaVR/fr+yPZ0h4S9wFShRBtDZapjAlds68ROQsvF/fdU4kqtfyIAst1lwtqMPeTmiZJxVubE0h2YEXOpwIEFcu3+MUvqtCd8X/T+VyF4ZQqn64NvYvkoWpfIiKmOGsCBc4agYuPs4Cy1QvN6oLXp+0b8mSzp+ot35n1lBGTSY2l4/9k6sIzWY7x23GS2g3AUJ2kYUTpQIq2pow8Sc8ptxLwZSQZwrAoIBABqhW7E3UDp8DO9XmHidVDR1dbCOdiyBvuKn8Fm2jABGCtwSN7ebTOePruzlGuSKxUzcpdjdP1fSPFbRErX8ffaj+JyGbec3kjZhym4+RClLU3i91g1bpYCsL2rPIWr9YZdovdkvBwdJbG6peEnhpKqWGenPUN06LzWApCea+Ch05iGc9Y1Vq0B7wuH2s0CXruP/8mRbQU31usnfAkb25ccI3SwhZ2vtVPGiJSqae1j0yZoDWg2gO2UDZ+xiqFFFQrUa2hirmBPj8y2rDT3ArN2CQfkWweSNVzcQmxXwC3Wuojqg5oMs85rKyeVudHgX6pxgdj6WfNAEjYdwr29E6/ECggEBAIHl7i7k/YwOrsx3aCyGy+ZC39LjDbGtYhiwIGSRy0NUmsDscO9nv/TB23FHeufoPaSaKNJnzEvMH8TSYcskBop2NclK0ptvO8hEQ8MADu3uZHRVna1LQkkHPfUzw6+HjKuSkky1kTcsO/gSJbsPJOI0JAu9becU2NJj4/4HZpqheNUMRpUXBnRcQNI3DSm3cjSCWWyAAqO/JM5hi2dwK/P5QEMWmuVGlr1f2FZ/YbiO0QWf61IoUuiZN78KYb7KQ0U2y8PaJlBgtBoQZkDaiiWfmYNOt8d5NRVO+p8SWM/QwFPpk1Hdora9GnsHARuxxLY17eKgZ2MS6jdsGPV00EUCggEBAPuNZ3peHYhIo2EMb6wpnAFV2fAUajymwenr+Bmv5BlAnW7bE2bSNuK0P342H047On8pSEHD4tk9C/GedKiUyxP2UnaFS24mWpe44X3UlC+KJLqJG+zVGXryC7bvhS3N1KlI6H2pRY1fPAhlfUk2KAe+ZP5C7iWwtR6FlPpjB3JoS77qFVhnYdlfnQEuJ7woEKD1TXQH0Sb2OGfPQW1UjIYoEp+9p2F5scB8rV6WaOIpwLY1H0ODvo1JYdTruWGHMKqhuLs5L2MeOluUOyHW7HkJLdLuyDIR9nA4+vNB1RNF3rz83L4Xs/NA1CW3iFWIyG57oFMX1td3i3xJwhjd40M=' +set pki certificate SRV certificate 'MIIFtTCCA52gAwIBAgIUeZnSAMPohIvKL/1Fy/pW2cV73HkwDQYJKoZIhvcNAQELBQAwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA1MTExMjM4MzFaFw0zMzA1MDgxMjM4MzFaMFsxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxFDASBgNVBAMMC292cG4tc2VydmVyMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEApDWzTcB5LFM/tacaRHvpchBKLigJ5FlqNNfJ2vnP87KfCmTA5tkWF7MtuY990tHZtl1vQ3Pim4d6XBOngiQmaw7tZeWAIrv1L2/VBjORUrLrQhkkg9nSpcYFxoyUQzukTY75PcwhYLkS6ZO/vPPSBuh97f3XR645Aauf7ZIk2NsUidP2uGZz/Sr5VC7ovH2l3zz1kIHPCinfvpPEVb5oTt7qEffk4vnKjy9RY+H1hZowvcAp1zfLaOt/dXaK6vfNutbmwDHbYAlIals0EcjtTr+63ymxmupn7RBjgWtK7MgocGZnt6HKJ4J6teP3WgiSd+I9pdFG4wHZOSVL3axf3rBx7q09DMn/Snvfbly+SlhXw9Ebk368J6j6rhNUkxo/M9fbfgxS0JnNjHInRNAvRQW5CgQfT9KyUdxR63BeSnngk2XYX+bDinb0ig+VDpZcr6PgOBR8aNFsCPbXRwDy0bmuFnFYMzs/7ZmFQhzE6rQykHvVvAsyv7FYrlW0E02H4+Xe6bEVpE1fLcH8OCGY2cfuTfq1Ax6R4r+tdHYW1kzFLjwdh3uqTLF11zcbkAwd78E/ItrfEadvgxrYR9gfhX79AkK0VHmZ/hzrLFeGznnVcqoTKgq21dfMfQG2P13QvqS7tCE5swM9N09ASVrifyVDuoL6jaW96wgeqR6eHMECAwEAAaN1MHMwDAYDVR0TAQH/BAIwADAOBgNVHQ8BAf8EBAMCB4AwEwYDVR0lBAwwCgYIKwYBBQUHAwEwHQYDVR0OBBYEFE1U3Zamfuv6ocYiF9q7H//U8h+AMB8GA1UdIwQYMBaAFP5NDac/yC+mQmaTpZDUv9GZMGMBMA0GCSqGSIb3DQEBCwUAA4ICAQBZwHvGj/jziNFwXS2W1Q11I12YANmVhISP39AA7DNhXR+E1hXFs+U52ehurZoLTi5YTjd8PD0KcE58mw8CLsFQB/+pni9EwJuAhpMb6XsmYEp0PeOH7C/q5eOc4TB/NBsvEa5IdTmUoewmjubKeJ8OHdRBMI77Me53lSC6iskc9DGyixSLqQogQW4aiTposFJOW/YugBy7kiuygmFNJv4luDbyRBb9131zH0qSSishLT4Bp5lXQNYWI4AU0JeyQcYaSHWCr0h6H9GN3QOf/emc3/2Tee40FcEMsszJBRnQ3IISzU5xVLlfU02SJMpjvFT2MGfHAs7obrNbwiFeoLZ6fQeGLe53aOQ5M9XeW5bdIeR2ZrLoO1hW33x5jYI8nLnU0FnqpMMY14r7LZE/mjwfdrTsGChFzsLasB0Tj++mGMOXw3DSusppub17AE2bO2uO6J9XMlbkOC8EmDCF1Hetija4D3aunhtu6jRBOcR8DHVBqNae2YgUk1ALqGrNUGFH4bEioTjDDx2GieOtp9rUwJMlkAyUEe0k/wzcBLjZaO8KBCtrmTdr1wMXizPT+XcjAlzRNXvHiZFq0NG5Rnim+LH9tp90EHzO7EeVXV+LegnIKQqboIrY3KOw5Qx8ska+t1WrWHpyzpwsA0WjA6sDTyWthgNYSxb1ikNGO8STCA==' +set pki certificate SRV private key 'MIIJQwIBADANBgkqhkiG9w0BAQEFAASCCS0wggkpAgEAAoICAQCkNbNNwHksUz+1pxpEe+lyEEouKAnkWWo018na+c/zsp8KZMDm2RYXsy25j33S0dm2XW9Dc+Kbh3pcE6eCJCZrDu1l5YAiu/Uvb9UGM5FSsutCGSSD2dKlxgXGjJRDO6RNjvk9zCFguRLpk7+889IG6H3t/ddHrjkBq5/tkiTY2xSJ0/a4ZnP9KvlULui8faXfPPWQgc8KKd++k8RVvmhO3uoR9+Ti+cqPL1Fj4fWFmjC9wCnXN8to6391dorq98261ubAMdtgCUhqWzQRyO1Ov7rfKbGa6mftEGOBa0rsyChwZme3ocongnq14/daCJJ34j2l0UbjAdk5JUvdrF/esHHurT0Myf9Ke99uXL5KWFfD0RuTfrwnqPquE1STGj8z19t+DFLQmc2McidE0C9FBbkKBB9P0rJR3FHrcF5KeeCTZdhf5sOKdvSKD5UOllyvo+A4FHxo0WwI9tdHAPLRua4WcVgzOz/tmYVCHMTqtDKQe9W8CzK/sViuVbQTTYfj5d7psRWkTV8twfw4IZjZx+5N+rUDHpHiv610dhbWTMUuPB2He6pMsXXXNxuQDB3vwT8i2t8Rp2+DGthH2B+Ffv0CQrRUeZn+HOssV4bOedVyqhMqCrbV18x9AbY/XdC+pLu0ITmzAz03T0BJWuJ/JUO6gvqNpb3rCB6pHp4cwQIDAQABAoICAQCgNLAZhFX0E8hNbplnBUltek0VGQUFnuLKaVlLZXwn8zXNCx1UW6l9N9e9eSw1uXzhueiqc247dQLAwIAlrSU6P9cHGdBYku4T+NRpd3gpqdtyolsItEQabccGvfKMYazb6khqrTRHTGkSL47aRzq6eKsbvRMCoQyG/61JN9LxK1SvX3gO0g4Jipq0MgvokeF5mdyuvqaC8PWU1k+vo9PaVwsguqy5cSDZbz3F6BcE4Lj693cavRmb5F52+E9yDI/P4IhCLKIt4QCgmxiC3XgA43fq75+SV21LUTjzc/0mY+VoO9CmzJcQ0vDrclzJnyFfCwBAPZweL5iBc0zAGcNxTA5/k86ejHdLlASH0dRf55F8ALeO22um21F7cEqOSYBtl009LDvpHte9wKWp9MpHABeDCigYMc05/IgVPQemtd6NtQ0ZVWHWUiWWqh5cY4v8d0CHWAv4HJZI5JuGWdWUc1QufMfu9UbTuNJe0RGQ/N9OJZzzwX+Vpuflrg9K0CT47Yo3NGFbYOuxn12JQBEYDNl5VHWZGAe1x/ljD0OjWmw3xkLNyRqwZnSTTJ4salCSW6qLrsqHWEeNyx+J4t2gBY0TNoylQ8hECxozFu/CYNIlY7+dJjFFe29r+FNBK+WOuUcSoyrABbqCkQH3iXOC97SQSyxdXMNvkkl9X8gvQQKCAQEA2VKt5k7HqvUTC26DNswNQGfd89GcQSeWaipzOBe0Oq12QA0G4ZfPTR00F6CqYnEOSuu2Qa++KEkTBsgl9mE0tdWCAXTTWuqmnsvX2FYQ8rD8FMce+Hs8nn3qNtxAkqPjIY0uEe5AJDzeB0ct7A5w5K5f6MUE/2rWhCeBGVqJKQ+qRjgk0KeVTcnTGzyujaHN1akUA1CRKEqtrCCspZjollWhxDygevMbXs/0QlDkUxaflPOzit6B5vDJqLGJUgvPI3Hc+9eDZXeCyCCdXOVGY8FUxMQ84RnDO8sVOthgahHsdbxjdUb0KcgaV5xNuMyuYsA++QG7fnsHCHnKT0c4eQKCAQEAwW8ppE0K/EmTp2OXKq+cuZHRZWaBtm3zDwfOz3FLVBXi3JGX9M6Hv6q/2cgLDudYiE3LCNagNkI7rRRO8Gfqd2i9KVRQHWCTl4mpTOwwmKWONNgS34aTPjD5UptNUzTvIItGGSMfg/DNrYg6G9HA666aIqpvodSfUv1ryJViml/3NtvmlRmRKEYe03txKhAN1Reuq30BoOGs4Tu5Hy8ijws9hOSCdZbOyte4EhDRSNyZB45YXooJOHEWTLjrZZqgGH3B/uUAUmyHbutPF/Wkep7M1LVeU8KS4HeVmwMRgPL10nxoHPE/UGBuqL09p4a1muXQ+TMHvnI59Shkn9cEiQKCAQEA10v/l/BoAse0TFj5iSnx3uKHkmsQX8P2UcsoRmPFW3RJd/7v2EJrTrwlxVqYMdpLDJIkB0MyIfry7H8QjNuUOqgAmazBToq08xCDD4GEXMpVkcgKuKRuU53ukNb26c+Ozshs4bqktMHQPGmZ5wgPc54EyjeVUezoBBiW3yVASPuJ9vLcFhJP6baOe6dMTmgD4S4V84q3o7EICUR9hbjMg1LmZeCiI+wAK5fdJm25JU9+XTRppKP3EXFudr8bibrFRRoikSTauYUCfX1CKKvDZkQ71IuMvHynW+8/YwLF0Y9cMO+noKHgdhwVbMIehXvRL2fBezLqKs17FDyD3rJyEQKCAQAdwFtHShJGe4qaVFcL2bbhU+xBDGMnDAI2bZ0BiwtrA3LBOiOFI779W+XmOT56LFsRm+V+loRN1CIZnOYHU/RcKV/u22j3G8OXqzS/ABT5ZX1Z42IDv08mYaH3cquSALJG7yT4+M4AHSmFZ06IuNpTZaePbWd+HJXkzdWmJFPmKpx7c5cjl6sb5q0XGgVt0spN3Dahabi2Zf+RJP50LWvDVJdBuWPXcjqcOFG3dZ669jMTVnGBGPoSFFK5ujd6iS3WloEgE1jZVJgAF3Ey3jVOJt6aWMsJVwQAQmRgUzh9/OCSX1AkI3b5hdt/WJwDCFUmXfKmYZLvV+JSMsRHUWsBAoIBAC2ZuZ3hYmSFMq+rZme72lIl3PUiOWPO9VVbs+PsRk58/ceCWnGCO647+KGb4jFw0vKPwP5RKmPny9a6ZSpYB2jsgWItKewdah+VPEOSLZQT/aPB5f61eiazCnuUuWrrycQVyLlELD0pj29mMxAJ0Nr1CIVboYp+YYA7dWNVSUT6T+EV6ASEC6jflb//UUUmCjOfxILGMkqvNJ2T7WguaPLOw21wLx0eDvQA/N8ZTiyKmE+GVRkDwGzC/yLeelgzyBgmyr15hfo7Q41VtAso6rzzExc4GasmgQe8z4Y0Gm7t3RDL3GXxBmonZtxNZt0vwvVyS/kAJedmPgcfxJunPnM=' +set pki certificate CLIENT certificate 'MIIFsDCCA5igAwIBAgIUSzQgwzGsfJFecGxCwLXVsGCLMkAwDQYJKoZIhvcNAQELBQAwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA1MTExMjM4MzlaFw0zMzA1MDgxMjM4MzlaMFYxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxDzANBgNVBAMMBmNsaWVudDCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBANHNJOSwcDbRqziL1gXYnHIq7P7vEUFvS8d/XLYJ1xIpcYTRXTut2CTGRar7fZZicu7x0yoK4TzrHvGVf1o4NC4NSGV5RX6kwRdrfWBmvpIkjSLGtCREFyhb+PHDpnsIS7cfN9udC0vocqVlx/xM/sfcP6Vja/uFp+9TQcneJIxYw34zkF+TtOVbE3pP5VxU7ZAj8F5/q1ONhTMdzG4Ol4/0nBqZfdYA3LVDeSSNIJNF5jlaKXXFHz1EJRemTYDx+f5bfCVcK2Qs8fU9jCFBlATjMu9O5rgk6nMLRwEnJZuZ1gj2tWQvz4e9yo5yUqf1PUhOrn3c81MRliUNHKr+CkxgQJal6P3Ar3q4iftJih3K+/j4o194mQ/Dt/Et+/Qn/DUFk2FB0rTMcQwJLTEAzxtTdmBJeJpipIPDR0u7UMZLNh/raQ8s3FsbY4uYORt2f5YQlCVHbth4dRa9xa+oRbm7eomNACIbWfkLh5Bzud1+qIfdBMZKaZbnf0HEeuH0J5LBJeova8EPxWbYMJPrRHzu5gowkIKl+uIxcy8IiNTA9YEoJVonCjmlr8NEtYShrIVbicdMNSI3pOQR60MFhkHwBjSU2l/z+4wwLxtzq/c2xKw9yrOZ46ZVLwGDFq8rPwp7/P9r6mDKsbn6jIvGOeH71dMZvoc4lCaClw+hKIzLAgMBAAGjdTBzMAwGA1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMCMB0GA1UdDgQWBBS6j30FmL6kZW7rDH8QjRMoWoA/njAfBgNVHSMEGDAWgBT+TQ2nP8gvpkJmk6WQ1L/RmTBjATANBgkqhkiG9w0BAQsFAAOCAgEANW2Y4bgaB9oexEjj6rkGvePtQmXRkF/adVQREY9iZDGTe72ePybVzrfMkZHjse3o7JvXWRIVVztWSzEpv5noIOX7lAioGG3wsFTHotTFR0zrYJHXHBcV2Neq4Kx2Ta/TZwD8QnZHAAxEQ1pYb4fxwN/A60VElAZoz9zYsbrJyVrfuHDL9queQxPFzqis+7W1BiVIcv4rn0DMQ560jTGh4t4rImOSu5gUsUrQaih85XDdOBPxViSNwfVdZJIgbvamudpfEaKsIun/uCjcxpNnzIp0rhyYmDeqVat4GnTV7Sy48e/Uvcq71ZWbBYJF4+yW4pylIU2Sh/Uy2sAz4C2M71FlFB7qsmcnPRsFFHf+r1NyD1lkVI9k2371fTG/Kub9V0rOz4pvKz4Em5b4MUPdDbZOqJ8hQ+atGE3ovFJIovA3NFb0OtnyC4l+kG7dfjqFudOnmDa+Qsya+2YOxBZBIRfuhlXhb6Y6Smsk9R6x0jBmcQTPS5ZmvKaTxQCFc53xMdQNAswjiI2L9rw4BcqQfVmf/vpoN+VusD/XEv2V0Ixm10YybA7BI/tixh9vwj3fdQXVLy3jSYjVBd5WOFPizbQZeD10ElvlLqZZyWrP/Wre7Nmi/gEOnhBXXmo034fFF/vXf0JRpQsd2oDs24+4XwZYb8mbM31j7Nx8YvhR+64=' +set pki certificate CLIENT private key 'MIIJRAIBADANBgkqhkiG9w0BAQEFAASCCS4wggkqAgEAAoICAQDRzSTksHA20as4i9YF2JxyKuz+7xFBb0vHf1y2CdcSKXGE0V07rdgkxkWq+32WYnLu8dMqCuE86x7xlX9aODQuDUhleUV+pMEXa31gZr6SJI0ixrQkRBcoW/jxw6Z7CEu3HzfbnQtL6HKlZcf8TP7H3D+lY2v7hafvU0HJ3iSMWMN+M5Bfk7TlWxN6T+VcVO2QI/Bef6tTjYUzHcxuDpeP9JwamX3WANy1Q3kkjSCTReY5Wil1xR89RCUXpk2A8fn+W3wlXCtkLPH1PYwhQZQE4zLvTua4JOpzC0cBJyWbmdYI9rVkL8+HvcqOclKn9T1ITq593PNTEZYlDRyq/gpMYECWpej9wK96uIn7SYodyvv4+KNfeJkPw7fxLfv0J/w1BZNhQdK0zHEMCS0xAM8bU3ZgSXiaYqSDw0dLu1DGSzYf62kPLNxbG2OLmDkbdn+WEJQlR27YeHUWvcWvqEW5u3qJjQAiG1n5C4eQc7ndfqiH3QTGSmmW539BxHrh9CeSwSXqL2vBD8Vm2DCT60R87uYKMJCCpfriMXMvCIjUwPWBKCVaJwo5pa/DRLWEoayFW4nHTDUiN6TkEetDBYZB8AY0lNpf8/uMMC8bc6v3NsSsPcqzmeOmVS8BgxavKz8Ke/z/a+pgyrG5+oyLxjnh+9XTGb6HOJQmgpcPoSiMywIDAQABAoICACNXi396uWyCpXVBGSyi8LfKw2GupBmBxiI1Mkj4H2LP2G+nVS1Ye7C2NcY311AeBX56/jd23bqFYRERPgLUtPWNB0UQyMQsvNpVISm8JR45Sg0xq+bwEXabB7SyYLkZDKgsehxkuCJxZd625pl53vGMCKyzst0MBt4qCEsZQM7jpQr9ZLS1DSQV05InI1wKcnp1k2hX2WSZ0nZp7qYbjyyQ6DsS4D/MpWFjnGSr4XDttXqz1YghTMHlWNpDCYtPN+3BO4iPnj+h0qCdXZ28jlLEczAc+oDKtzPqEmv/TDaKE6Qu6x+VbkBPmG+mkoX4qfokRwCs19CGheR38PxdDx7AgySv7K8hM8gFC0XEqNdjt86KG+N1Ps5Sru4QMrf8j9XXNPUvt0M8wsPVeWa5ubkV7/h0HIEROOFpEFbzWnhBChPVvFObuuEjl5Jnj3KUEnckQFU07mPP/BpysHo3v/p+VTVoo2UkfVvjamnwQOUt3cVlPVC4FzVgkswJa4f75nGmDv8dafyPrCYciOh0qyhD5Pw/EBJkKtDBYHaoxtAw9Ann4A5rvZAveLNTPESOMo90pJwJbQcZyq9H+UGVnde39I4m5vHB5izZJI24Yd3fjRRkRf+/68VYKrkI5B7oH73Z/cl/xgEdI1hag4MLv1gon8wna4yCX/321YPTrDABAoIBAQDpHtvnvpOaoSjkJHUx4EGJkrp5R/mPfEbzzU2Ov5pNIcufv++2lsoUVCTDwgp4+7GngqYO5vVyW/AS4pSrDx7kdWpFaUtJUUCcCHk/5hYcvvourYtW1NR+XPiI28IqRp1P0L1+P0mUaRgpEcw6nEnc37XEujvTB1M/yF2y6xc+kZGjrZTmJeu0V5kkaGcXlAqUv2k0Lj3tEPQR/qj+kMX5hidROGuybNBESgA5ELY6QVnpcOyNDyniWq+RIUyBOuXp7DpUbmUANFEEP8lwjZX+HqwTpSjTSFdcPrsmorc9FpTXA9ktt1Z0ZxBzUvdcWbUeVsFqL0yICiShE7UxlOPBAoIBAQDmZGQ5roSKKY+VnmjIq2+gx8zsMYeliQm0hnKrFw9MM8U+/XOpXlpNHx2ehrGWp/BbmlmrnQaRcbLPJaRtWSEywbWnG77g+zj0w+4BdsYyTtGGFj4tXVZhPPo/DID3FPLn9cSv8MIVWjzg1G/BZcxtCDBDRBhwhZHCPOfd0K/S7rvRBq7IsNNHMTGswWGRMaF+M/trZw7TsQ0BX+5zZUyO8VNBi/NgTV3yoQ8ynBefRt1dmNa2CKXPT+5R19cBtecFEyhc3yo8ryTtM22JzndzA8agQmNPnWmYGivvcNHNikTQ2qUvvcd7Siny6j0+CmFdT9bl64VPyRJrFCw3jaOLAoIBAQCQ/1OyShRO+myPsql+U0kQQ8Zeh0kPWTJclFboMf7MePfJLj3waMvaZxfS9s9CvvKaCSY2YKtL7Sle5bWozCff27Q05jAgszwnkRGxj/AzAwpjnCft40UkL7majm2vk+pm6aPjcYPXnqKbcOmBjxJWIoNRkLCDKqw6IOs+zQDRNwPKNb5GhFGeA1pKjfGJddg6+u95uEVmPcRBqQ79/5hUAoBUAW7jNNE5mHmZBO8DPwCotUc82bCojNVkxLxsKPE2VWtWdq+1t9SoevBVZItl2zgWpATHndhQlOgdONoWUgRT1J3x1HYewrg1suYOd/GypC17WV4Vw5FS6wopg71BAoIBAQC63vDgTGpauk0pOVyab1tSmNzhM2dn4BhMIcU+eqzAzTkO13sKBGrQJQ3cODoxDbSKSE61QN9D92nmVQziWKnxxmb1zS5sw7g15/nTnCg0Q/P0g3QZTZyzsEb1/slYH9jKRnErl+eEdDXu0sB2qIBAa6Th2ojMM7q/RrF3HD6Qo20ZpQb951bnZsJ48j2WDCCGAdnLCsNe9zuqQsphNOf9BUbXYpGcKgSquPJfxXXvjgYdVcvJyIfc+GNAZQaS750bY6eYdLaIlDMqZk1RunLuikCAWni86dvtMEU0qFi0E5Ovp7jWWWNE4CnYSyAzgy3oBssyoG74AQp8addXk/3zAoIBAQC8/7DglQGMcKnk4zX+7jCuc0p+qMcd5RdnfBKlRhcWYNRPup9jyDefdkXCBTumCHXrIil/rJzP6b1IZZdC4xkheQpLXNUcceAidRWIrTypaXKkmhR0D74uckGiLXB4S84HYmIdw89ZiF0gB0yyZH5mZnqVMojwnGmWqcM2sr2N44bNQMfhD+nCSgQmReYKKfMQCdvYMxRLQfseU0pFEOGnh9jAmpn8qWMWxNDmFR/rVl26BXtRPiNPimfwWKrYNYhESN7A5/hWcrNUhE4PI+Pjd74npimqs5TDSst2Jc6DiahdaZ6JNNzp2PMUXNbfsMCVgZx+qtVNnVxVMiEngPRl' +set pki dh DH parameters 'MIIBCAKCAQEAzPOQWrWaIX2qt4sbV6bRbUnFx4jmeE+WXC8GIvulnC4pIr1nt2Gc/7uNfEPjDZ4X6csD3X6zAWxtSuWeNuml9Yuy+tS8gI7d0FlbQRAFO/9GIlRuVdMcbCtEhg8ja7Y0g3fQjOSQJ9mqFo7sRoXyYQALD+MDEJOxhnV7neCrgDi1pqnN4xZLoR9DLARp0ad30VIvnv0ay55wxFWAKh2iwNRwyeXIEOtUDBkfcLGSNNfK0kQsos/J8Q+7YXmk4cN9tiVX4xR92edVO4z/vhMkjsGKLSDm/E6EMusX+N0UhQ3dv7qDgeSS8vDsqBm8XJonumNZLvFbYt2ARGRZYL6DUwIBAg==' +``` + +Once all the required certificates and keys are installed, the remaining +OpenVPN Server configuration can be carried out. + +```{eval-rst} +.. literalinclude:: _include/ovpn-server.conf + :language: none +``` + +## Client configuration + +One advantage of having the client certificate stored is the ability to create the client configuration. + +```none +vyos@ovpn-server:~$ generate openvpn client-config interface vtun10 ca OVPN-CA certificate CLIENT +``` + +save the output to a file and import it in nearly all openvpn clients. + +```none +client +nobind +remote 198.51.100.254 1194 +remote-cert-tls server +proto udp +dev tun +dev-type tun +persist-key +persist-tun +verb 3 + +# Encryption options + +keysize 256 +comp-lzo no + +<ca> +-----BEGIN CERTIFICATE----- +MIIFnTCCA4WgAwIBAgIUIPFIXvCxYdavCnSPFNjr6lUtlsswDQYJKoZIhvcNAQEL +BQAwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcM +CVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0y +MzA1MTExMjM4MjJaFw0zMzA1MDgxMjM4MjJaMFcxCzAJBgNVBAYTAkdCMRMwEQYD +VQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5 +T1MxEDAOBgNVBAMMB3Z5b3MuaW8wggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAwggIK +AoICAQDg45vAzS6xNqU+Pa7wk1Imt1/az1C22Sbp3wPJLfgOmy0K3TA5qVsx/c/8 +gatsatMkCsekGnK5BPzCDd5eCCLo//B25HFO6fBYRNvHvVyCUx7QEXw4FHFNG88z +CIizx114AGtVwZfGGG9xCc53xjLPUpH6iqTXme41cCFFQlqXwZ7fuySieSdoV8SA +sJTTOsGCEUEcDEnNPn6tX3KWTzNuyFPECy8WCmNgWNyG2nmH+U7WRTX0ehZ5dZyU +5au7TxpRN4a+JtE0gNqcWJ+nh1A543q2pcRoQpPAzHFclgj8wG/EyauQMY/LC4tL +c6moPaNlTwA9HJv8s6xUqpzNptDoUHKOqKuw2JRFnno5SCQ788KkKNgVWBy2o3BG +oewfHFhAdR61CXeLpmuneuhi96GcM031gW8ptXbd4DkCF7H6KRtqeIvwiyG79ttC +8kZf01Sn1fM5fTjGxaE38dAk/RchtHRC6rtFavHJjB2cUcCkhhQofUE6IR2dYJZ1 +cw0Wy5CI3bXHf43BpvDGmuxIlNGirTq8wf5RCWzDJJgmkQpYhUYe8x4faF4gTo00 +uH4ZvAYjQu3JNZGkb50p4kM9Mu5rQAiZJUeMAz/QD+EIV9xXgOk14+BbnHKWbZ7O +u5emewFuE/bjl79oNJklpXdc4soRkCPCTEGK3zDBdmUtCYk1DwIDAQABo2EwXzAP +BgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBhjAdBgNVHSUEFjAUBggrBgEF +BQcDAgYIKwYBBQUHAwEwHQYDVR0OBBYEFP5NDac/yC+mQmaTpZDUv9GZMGMBMA0G +CSqGSIb3DQEBCwUAA4ICAQDEqpF2ibwYFxsF1XDIPS5/Gs0sZTZBuByNm5d2+jTy +O7d5alZUdbvobbwhxZOhWasmFNyPLr4TYmZm5zF+efFsiOxjyRuEoVU+Fe8rZmpR +IF/+6+nYX5r9vMI4QxGjeeyP20OHJ85Kvz182CTsITrM15Vw/kVVjAVzFI5Gm/Qo +lalAoFQza9rAL4kDqaUszjHjPbysvDpGF+NLPjiYDHXcty/BC48bnuzAeEM60SGZ +7EXvf8l0X8YsO7z39w6780A/3rbZvFhCYMKp/+p5xBRDjnX91dM6DJw73RwYQ1KH +bHk9wWUwnL1giL71jzp/y4Oj6SSK2PQv+OnO80J6Zg06WIQx9xYcxr108Xh9FotU +rlG7GYPI3Udf95t6SjuydDhULAVD0lMBxlDe9DHW1k1q1pOXaHZg926tY66xx/ld +a6dcuwJjA2Dx5JI6L0u9ureQmQAtxvnoTCtf+hR1iX/IkskZCKs34SjNiCnBuw/D +NfdOpfaABm7y+tWiXBwnu5l/K8poXcQYQByyZj6YMmpgsbVPr5KNsLWOgRA81M6I +Pof8qxvnFrkazhiQWh1YHSjnaHtA3z5/BdgwHVICuFyrIOlbkKyJOjKcKBsDdMwI +V0tsnpnyli2xEPZKu1tAQFAavXrK/RGYYhOZ3e0aRSV8hlP8i/mf7p0I45cJiBCq +Pg== +-----END CERTIFICATE----- + +</ca> + +<cert> +-----BEGIN CERTIFICATE----- +MIIFsDCCA5igAwIBAgIUSzQgwzGsfJFecGxCwLXVsGCLMkAwDQYJKoZIhvcNAQEL +BQAwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcM +CVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0y +MzA1MTExMjM4MzlaFw0zMzA1MDgxMjM4MzlaMFYxCzAJBgNVBAYTAkdCMRMwEQYD +VQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5 +T1MxDzANBgNVBAMMBmNsaWVudDCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoC +ggIBANHNJOSwcDbRqziL1gXYnHIq7P7vEUFvS8d/XLYJ1xIpcYTRXTut2CTGRar7 +fZZicu7x0yoK4TzrHvGVf1o4NC4NSGV5RX6kwRdrfWBmvpIkjSLGtCREFyhb+PHD +pnsIS7cfN9udC0vocqVlx/xM/sfcP6Vja/uFp+9TQcneJIxYw34zkF+TtOVbE3pP +5VxU7ZAj8F5/q1ONhTMdzG4Ol4/0nBqZfdYA3LVDeSSNIJNF5jlaKXXFHz1EJRem +TYDx+f5bfCVcK2Qs8fU9jCFBlATjMu9O5rgk6nMLRwEnJZuZ1gj2tWQvz4e9yo5y +Uqf1PUhOrn3c81MRliUNHKr+CkxgQJal6P3Ar3q4iftJih3K+/j4o194mQ/Dt/Et ++/Qn/DUFk2FB0rTMcQwJLTEAzxtTdmBJeJpipIPDR0u7UMZLNh/raQ8s3FsbY4uY +ORt2f5YQlCVHbth4dRa9xa+oRbm7eomNACIbWfkLh5Bzud1+qIfdBMZKaZbnf0HE +euH0J5LBJeova8EPxWbYMJPrRHzu5gowkIKl+uIxcy8IiNTA9YEoJVonCjmlr8NE +tYShrIVbicdMNSI3pOQR60MFhkHwBjSU2l/z+4wwLxtzq/c2xKw9yrOZ46ZVLwGD +Fq8rPwp7/P9r6mDKsbn6jIvGOeH71dMZvoc4lCaClw+hKIzLAgMBAAGjdTBzMAwG +A1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMC +MB0GA1UdDgQWBBS6j30FmL6kZW7rDH8QjRMoWoA/njAfBgNVHSMEGDAWgBT+TQ2n +P8gvpkJmk6WQ1L/RmTBjATANBgkqhkiG9w0BAQsFAAOCAgEANW2Y4bgaB9oexEjj +6rkGvePtQmXRkF/adVQREY9iZDGTe72ePybVzrfMkZHjse3o7JvXWRIVVztWSzEp +v5noIOX7lAioGG3wsFTHotTFR0zrYJHXHBcV2Neq4Kx2Ta/TZwD8QnZHAAxEQ1pY +b4fxwN/A60VElAZoz9zYsbrJyVrfuHDL9queQxPFzqis+7W1BiVIcv4rn0DMQ560 +jTGh4t4rImOSu5gUsUrQaih85XDdOBPxViSNwfVdZJIgbvamudpfEaKsIun/uCjc +xpNnzIp0rhyYmDeqVat4GnTV7Sy48e/Uvcq71ZWbBYJF4+yW4pylIU2Sh/Uy2sAz +4C2M71FlFB7qsmcnPRsFFHf+r1NyD1lkVI9k2371fTG/Kub9V0rOz4pvKz4Em5b4 +MUPdDbZOqJ8hQ+atGE3ovFJIovA3NFb0OtnyC4l+kG7dfjqFudOnmDa+Qsya+2YO +xBZBIRfuhlXhb6Y6Smsk9R6x0jBmcQTPS5ZmvKaTxQCFc53xMdQNAswjiI2L9rw4 +BcqQfVmf/vpoN+VusD/XEv2V0Ixm10YybA7BI/tixh9vwj3fdQXVLy3jSYjVBd5W +OFPizbQZeD10ElvlLqZZyWrP/Wre7Nmi/gEOnhBXXmo034fFF/vXf0JRpQsd2oDs +24+4XwZYb8mbM31j7Nx8YvhR+64= +-----END CERTIFICATE----- + +</cert> + +<key> +-----BEGIN PRIVATE KEY----- +MIIJRAIBADANBgkqhkiG9w0BAQEFAASCCS4wggkqAgEAAoICAQDRzSTksHA20as4 +i9YF2JxyKuz+7xFBb0vHf1y2CdcSKXGE0V07rdgkxkWq+32WYnLu8dMqCuE86x7x +lX9aODQuDUhleUV+pMEXa31gZr6SJI0ixrQkRBcoW/jxw6Z7CEu3HzfbnQtL6HKl +Zcf8TP7H3D+lY2v7hafvU0HJ3iSMWMN+M5Bfk7TlWxN6T+VcVO2QI/Bef6tTjYUz +HcxuDpeP9JwamX3WANy1Q3kkjSCTReY5Wil1xR89RCUXpk2A8fn+W3wlXCtkLPH1 +PYwhQZQE4zLvTua4JOpzC0cBJyWbmdYI9rVkL8+HvcqOclKn9T1ITq593PNTEZYl +DRyq/gpMYECWpej9wK96uIn7SYodyvv4+KNfeJkPw7fxLfv0J/w1BZNhQdK0zHEM +CS0xAM8bU3ZgSXiaYqSDw0dLu1DGSzYf62kPLNxbG2OLmDkbdn+WEJQlR27YeHUW +vcWvqEW5u3qJjQAiG1n5C4eQc7ndfqiH3QTGSmmW539BxHrh9CeSwSXqL2vBD8Vm +2DCT60R87uYKMJCCpfriMXMvCIjUwPWBKCVaJwo5pa/DRLWEoayFW4nHTDUiN6Tk +EetDBYZB8AY0lNpf8/uMMC8bc6v3NsSsPcqzmeOmVS8BgxavKz8Ke/z/a+pgyrG5 ++oyLxjnh+9XTGb6HOJQmgpcPoSiMywIDAQABAoICACNXi396uWyCpXVBGSyi8LfK +w2GupBmBxiI1Mkj4H2LP2G+nVS1Ye7C2NcY311AeBX56/jd23bqFYRERPgLUtPWN +B0UQyMQsvNpVISm8JR45Sg0xq+bwEXabB7SyYLkZDKgsehxkuCJxZd625pl53vGM +CKyzst0MBt4qCEsZQM7jpQr9ZLS1DSQV05InI1wKcnp1k2hX2WSZ0nZp7qYbjyyQ +6DsS4D/MpWFjnGSr4XDttXqz1YghTMHlWNpDCYtPN+3BO4iPnj+h0qCdXZ28jlLE +czAc+oDKtzPqEmv/TDaKE6Qu6x+VbkBPmG+mkoX4qfokRwCs19CGheR38PxdDx7A +gySv7K8hM8gFC0XEqNdjt86KG+N1Ps5Sru4QMrf8j9XXNPUvt0M8wsPVeWa5ubkV +7/h0HIEROOFpEFbzWnhBChPVvFObuuEjl5Jnj3KUEnckQFU07mPP/BpysHo3v/p+ +VTVoo2UkfVvjamnwQOUt3cVlPVC4FzVgkswJa4f75nGmDv8dafyPrCYciOh0qyhD +5Pw/EBJkKtDBYHaoxtAw9Ann4A5rvZAveLNTPESOMo90pJwJbQcZyq9H+UGVnde3 +9I4m5vHB5izZJI24Yd3fjRRkRf+/68VYKrkI5B7oH73Z/cl/xgEdI1hag4MLv1go +n8wna4yCX/321YPTrDABAoIBAQDpHtvnvpOaoSjkJHUx4EGJkrp5R/mPfEbzzU2O +v5pNIcufv++2lsoUVCTDwgp4+7GngqYO5vVyW/AS4pSrDx7kdWpFaUtJUUCcCHk/ +5hYcvvourYtW1NR+XPiI28IqRp1P0L1+P0mUaRgpEcw6nEnc37XEujvTB1M/yF2y +6xc+kZGjrZTmJeu0V5kkaGcXlAqUv2k0Lj3tEPQR/qj+kMX5hidROGuybNBESgA5 +ELY6QVnpcOyNDyniWq+RIUyBOuXp7DpUbmUANFEEP8lwjZX+HqwTpSjTSFdcPrsm +orc9FpTXA9ktt1Z0ZxBzUvdcWbUeVsFqL0yICiShE7UxlOPBAoIBAQDmZGQ5roSK +KY+VnmjIq2+gx8zsMYeliQm0hnKrFw9MM8U+/XOpXlpNHx2ehrGWp/BbmlmrnQaR +cbLPJaRtWSEywbWnG77g+zj0w+4BdsYyTtGGFj4tXVZhPPo/DID3FPLn9cSv8MIV +Wjzg1G/BZcxtCDBDRBhwhZHCPOfd0K/S7rvRBq7IsNNHMTGswWGRMaF+M/trZw7T +sQ0BX+5zZUyO8VNBi/NgTV3yoQ8ynBefRt1dmNa2CKXPT+5R19cBtecFEyhc3yo8 +ryTtM22JzndzA8agQmNPnWmYGivvcNHNikTQ2qUvvcd7Siny6j0+CmFdT9bl64VP +yRJrFCw3jaOLAoIBAQCQ/1OyShRO+myPsql+U0kQQ8Zeh0kPWTJclFboMf7MePfJ +Lj3waMvaZxfS9s9CvvKaCSY2YKtL7Sle5bWozCff27Q05jAgszwnkRGxj/AzAwpj +nCft40UkL7majm2vk+pm6aPjcYPXnqKbcOmBjxJWIoNRkLCDKqw6IOs+zQDRNwPK +Nb5GhFGeA1pKjfGJddg6+u95uEVmPcRBqQ79/5hUAoBUAW7jNNE5mHmZBO8DPwCo +tUc82bCojNVkxLxsKPE2VWtWdq+1t9SoevBVZItl2zgWpATHndhQlOgdONoWUgRT +1J3x1HYewrg1suYOd/GypC17WV4Vw5FS6wopg71BAoIBAQC63vDgTGpauk0pOVya +b1tSmNzhM2dn4BhMIcU+eqzAzTkO13sKBGrQJQ3cODoxDbSKSE61QN9D92nmVQzi +WKnxxmb1zS5sw7g15/nTnCg0Q/P0g3QZTZyzsEb1/slYH9jKRnErl+eEdDXu0sB2 +qIBAa6Th2ojMM7q/RrF3HD6Qo20ZpQb951bnZsJ48j2WDCCGAdnLCsNe9zuqQsph +NOf9BUbXYpGcKgSquPJfxXXvjgYdVcvJyIfc+GNAZQaS750bY6eYdLaIlDMqZk1R +unLuikCAWni86dvtMEU0qFi0E5Ovp7jWWWNE4CnYSyAzgy3oBssyoG74AQp8addX +k/3zAoIBAQC8/7DglQGMcKnk4zX+7jCuc0p+qMcd5RdnfBKlRhcWYNRPup9jyDef +dkXCBTumCHXrIil/rJzP6b1IZZdC4xkheQpLXNUcceAidRWIrTypaXKkmhR0D74u +ckGiLXB4S84HYmIdw89ZiF0gB0yyZH5mZnqVMojwnGmWqcM2sr2N44bNQMfhD+nC +SgQmReYKKfMQCdvYMxRLQfseU0pFEOGnh9jAmpn8qWMWxNDmFR/rVl26BXtRPiNP +imfwWKrYNYhESN7A5/hWcrNUhE4PI+Pjd74npimqs5TDSst2Jc6DiahdaZ6JNNzp +2PMUXNbfsMCVgZx+qtVNnVxVMiEngPRl +-----END PRIVATE KEY----- + +</key> +``` + +### Configure VyOS as client + +```none +set interfaces openvpn vtun10 authentication username 'user01' +set interfaces openvpn vtun10 authentication password '$ecret' +set interfaces openvpn vtun10 encryption cipher '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 '198.51.100.254' +set interfaces openvpn vtun10 remote-port '1194' +set interfaces openvpn vtun10 tls ca-certificate 'OVPN-CA' +set interfaces openvpn vtun10 tls certificate 'CLIENT' +``` + +## Monitoring + +If the client is connected successfully you can check the status + +```none +vyos@ovpn-server:~$ show openvpn server +OpenVPN status on vtun10 + +Client CN Remote Host Tunnel IP Local Host TX bytes RX bytes Connected Since +----------- ------------------ ----------- ------------------- ---------- ---------- ------------------- +client 198.51.100.1:55150 10.23.1.6 198.51.100.254:1194 4.7 KB 4.7 KB 2023-05-11 12:47:11 +``` diff --git a/docs/configexamples/autotest/Wireguard/_include/topology.webp b/docs/configexamples/autotest/Wireguard/_include/topology.webp Binary files differnew file mode 100644 index 00000000..3cc5e992 --- /dev/null +++ b/docs/configexamples/autotest/Wireguard/_include/topology.webp diff --git a/docs/configexamples/autotest/Wireguard/md-Wireguard.md b/docs/configexamples/autotest/Wireguard/md-Wireguard.md new file mode 100644 index 00000000..73d354d2 --- /dev/null +++ b/docs/configexamples/autotest/Wireguard/md-Wireguard.md @@ -0,0 +1,113 @@ +# Wireguard + +Testdate: 2023-08-31 + +Version: 1.4-rolling-202308240020 + +This simple structure show how to connect two offices. One remote branch and the +central office. + +## Topology + +The topology have a central and a branch VyOS router and one client, to +test, in each site. + +```{image} _include/topology.png +:alt: Ansible Example topology image +``` + +## Configuration + +Set the local subnet on eth2 and the public ip address eth1 on each site. + +Central + +```{eval-rst} +.. literalinclude:: _include/central.conf + :language: none + :lines: 1-2 +``` + +Branch + +```{eval-rst} +.. literalinclude:: _include/branch.conf + :language: none + :lines: 1-2 + +``` + +Next thing to do, is to create a wireguard keypair on each side. +After this, the public key can be displayed, to save for later. + +```none +vyos@central:~$ generate pki wireguard +Private key: cMNGHtb5dW92ORG3HS8JJlvQF8pmVGt2Ydny8hTBLnY= +Public key: WyfLCTXi31gL+YbYOwoAHCl2RgS+y56cYHEK6pQsTQ8= +``` + +After you have each public key. The wireguard interfaces can be setup. + +Central + +```{eval-rst} +.. literalinclude:: _include/central.conf + :language: none + :lines: 4-12 +``` + +Branch + +```{eval-rst} +.. literalinclude:: _include/branch.conf + :language: none + :lines: 4-12 + +``` + +To reach the network, a route must be set on each VyOS host. +In this structure, a static interface route will fit the requirements. + +Central + +```{eval-rst} +.. literalinclude:: _include/central.conf + :language: none + :lines: 14 +``` + +Branch + +```{eval-rst} +.. literalinclude:: _include/branch.conf + :language: none + :lines: 14 +``` + +## Testing and debugging + +After all is done and commit, let's take a look if the Wireguard interface is +up and running. + +```none +vyos@central:~$ show interfaces wireguard +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +wg01 192.168.0.1/24 u/u VPN-to-Branch +``` + +And ping the Branch PC from your central router to check the response. + +```none +vyos@central:~$ ping 10.0.2.100 count 4 +PING 10.0.2.100 (10.0.2.100) 56(84) bytes of data. +64 bytes from 10.0.2.100: icmp_seq=1 ttl=63 time=0.641 ms +64 bytes from 10.0.2.100: icmp_seq=2 ttl=63 time=0.836 ms +64 bytes from 10.0.2.100: icmp_seq=3 ttl=63 time=0.792 ms +64 bytes from 10.0.2.100: icmp_seq=4 ttl=63 time=1.09 ms + +--- 10.0.2.100 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 3013ms +rtt min/avg/max/mdev = 0.641/0.838/1.086/0.160 ms +``` diff --git a/docs/configexamples/autotest/tunnelbroker/_include/topology.webp b/docs/configexamples/autotest/tunnelbroker/_include/topology.webp Binary files differnew file mode 100644 index 00000000..c3a812ab --- /dev/null +++ b/docs/configexamples/autotest/tunnelbroker/_include/topology.webp diff --git a/docs/configexamples/autotest/tunnelbroker/md-tunnelbroker.md b/docs/configexamples/autotest/tunnelbroker/md-tunnelbroker.md new file mode 100644 index 00000000..37a89b3f --- /dev/null +++ b/docs/configexamples/autotest/tunnelbroker/md-tunnelbroker.md @@ -0,0 +1,199 @@ +(examples-tunnelbroker-ipv6)= + +# Tunnelbroker.net (IPv6) + +Testdate: 2023-08-31 + +Version: 1.4-rolling-202308240020 + +This guide walks through the setup of <https://www.tunnelbroker.net/> for an +IPv6 Tunnel. + +## Prerequisites + +- A public, routable IPv4 address. This does not necessarily need to be static, + but you will need to update the tunnel endpoint when/if your IP address + changes, which can be done with a script and a scheduled task. +- Account at <https://www.tunnelbroker.net/> +- Requested a "Regular Tunnel". You want to choose a location that is closest + to your physical location for the best response time. + +### Topology + +The example topology has 2 VyOS routers. One as The WAN Router and on as a +Client, to test a single LAN setup + +```{image} _include/topology.png +:alt: Tunnelbroker topology image +``` + +### Configuration + +First, we configure the `vyos-wan` interface to get a DHCP address. + +```{eval-rst} +.. literalinclude:: _include/vyos-wan.conf + :language: none + +``` + +Now we are able to setup the tunnel interface. + +```{eval-rst} +.. literalinclude:: _include/vyos-wan_tun0.conf + :language: none + :lines: 1-5 +``` + +Setup the ipv6 default route to the tunnel interface + +```{eval-rst} +.. literalinclude:: _include/vyos-wan_tun0.conf + :language: none + :lines: 7 +``` + +Now you should be able to ping a public IPv6 Address + +```none +vyos@vyos-wan:~$ ping 2001:470:20::2 count 4 +PING 2001:470:20::2(2001:470:20::2) 56 data bytes +64 bytes from 2001:470:20::2: icmp_seq=1 ttl=64 time=39.4 ms +64 bytes from 2001:470:20::2: icmp_seq=2 ttl=64 time=29.9 ms +64 bytes from 2001:470:20::2: icmp_seq=3 ttl=64 time=30.0 ms +64 bytes from 2001:470:20::2: icmp_seq=4 ttl=64 time=29.9 ms + +--- 2001:470:20::2 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 3005ms +rtt min/avg/max/mdev = 29.885/32.293/39.371/4.086 ms +``` + +Assuming the pings are successful, you need to add some DNS servers. +Some options: + +```{eval-rst} +.. literalinclude:: _include/vyos-wan_tun0.conf + :language: none + :lines: 13 +``` + +You should now be able to ping something by IPv6 DNS name: + +```none +vyos@vyos-wan:~$ ping tunnelbroker.net count 4 +PING tunnelbroker.net(tunnelbroker.net (2001:470:0:63::2)) 56 data bytes +64 bytes from tunnelbroker.net (2001:470:0:63::2): icmp_seq=1 ttl=46 time=200 ms +64 bytes from tunnelbroker.net (2001:470:0:63::2): icmp_seq=2 ttl=46 time=176 ms +64 bytes from tunnelbroker.net (2001:470:0:63::2): icmp_seq=3 ttl=46 time=244 ms +64 bytes from tunnelbroker.net (2001:470:0:63::2): icmp_seq=4 ttl=46 time=176 ms + +--- tunnelbroker.net ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 3002ms +rtt min/avg/max/mdev = 175.737/198.653/243.621/27.714 ms +``` + +### LAN Configuration + +At this point, your VyOS install should have full IPv6, but now your LAN devices +need access. + +With Tunnelbroker.net, you have two options: + +- Routed /64. This is the default assignment. In IPv6-land, it's good for a + single "LAN", and is somewhat equivalent to a /24. +- Routed /48. This is something you can request by clicking the "Assign /48" + link in the Tunnelbroker.net tunnel config. It allows you to have up to 65k + +Unlike IPv4, IPv6 is really not designed to be broken up smaller than /64. So +if you ever want to have multiple LANs, VLANs, DMZ, etc, you'll want to ignore +the assigned /64, and request the /48 and use that. + +## Single LAN Setup + +Single LAN setup where eth2 is your LAN interface. Use the Tunnelbroker +Routed /64 prefix: + +```{eval-rst} +.. literalinclude:: _include/vyos-wan_tun0.conf + :language: none + :lines: 9-11 +``` + +Please note, 'autonomous-flag' and 'on-link-flag' are enabled by default, +'valid-lifetime' and 'preferred-lifetime' are set to default values of +30 days and 4 hours respectively. + +And the `client` to receive an IPv6 address with stateless autoconfig. + +```{eval-rst} +.. literalinclude:: _include/client.conf + :language: none +``` + +This accomplishes a few things: + +- Sets your LAN interface's IP address +- Enables router advertisements. This is an IPv6 alternative for DHCP (though + DHCPv6 can still be used). With RAs, Your devices will automatically find the + information they need for routing and DNS. + +Now the Client is able to ping a public IPv6 address + +```none +vyos@client:~$ ping 2001:470:20::2 count 4 +PING 2001:470:20::2(2001:470:20::2) 56 data bytes +64 bytes from 2001:470:20::2: icmp_seq=1 ttl=63 time=30.5 ms +64 bytes from 2001:470:20::2: icmp_seq=2 ttl=63 time=29.6 ms +64 bytes from 2001:470:20::2: icmp_seq=3 ttl=63 time=29.9 ms +64 bytes from 2001:470:20::2: icmp_seq=4 ttl=63 time=29.8 ms + +--- 2001:470:20::2 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 3005ms +rtt min/avg/max/mdev = 29.578/29.959/30.490/0.333 ms +``` + +## Multiple LAN/DMZ Setup + +That's how you can expand the example above. +Use the `Routed /48` information. This allows you to assign a +different /64 to every interface, LAN, or even device. Or you could break your +network into smaller chunks like /56 or /60. + +The format of these addresses: + +- `2001:470:xxxx::/48`: The whole subnet. xxxx should come from Tunnelbroker. +- `2001:470:xxxx:1::/64`: A subnet suitable for a LAN +- `2001:470:xxxx:2::/64`: Another subnet +- `2001:470:xxxx:ffff:/64`: The last usable /64 subnet. + +In the above examples, 1,2,ffff are all chosen by you. You can use 1-ffff +(1-65535). + +So, when your LAN is eth1, your DMZ is eth2, your cameras are on eth3, etc: + +```none +set interfaces ethernet eth1 address '2001:470:xxxx:1::1/64' +set service router-advert interface eth1 name-server '2001:470:20::2' +set service router-advert interface eth1 prefix 2001:470:xxxx:1::/64 + +set interfaces ethernet eth2 address '2001:470:xxxx:2::1/64' +set service router-advert interface eth2 name-server '2001:470:20::2' +set service router-advert interface eth2 prefix 2001:470:xxxx:2::/64 + +set interfaces ethernet eth3 address '2001:470:xxxx:3::1/64' +set service router-advert interface eth3 name-server '2001:470:20::2' +set service router-advert interface eth3 prefix 2001:470:xxxx:3::/64 +``` + +Please note, 'autonomous-flag' and 'on-link-flag' are enabled by default, +'valid-lifetime' and 'preferred-lifetime' are set to default values of +30 days and 4 hours respectively. + +## Firewall + +Finally, don't forget the {ref}`firewall`. The usage is identical, except for +instead of `set firewall name NAME`, you would use `set firewall ipv6-name +NAME`. + +Similarly, to attach the firewall, you would use `set interfaces ethernet eth0 +firewall in ipv6-name` or `et firewall zone LOCAL from WAN firewall ipv6-name`. diff --git a/docs/configexamples/md-azure-vpn-bgp.md b/docs/configexamples/md-azure-vpn-bgp.md new file mode 100644 index 00000000..0b4132d8 --- /dev/null +++ b/docs/configexamples/md-azure-vpn-bgp.md @@ -0,0 +1,134 @@ +--- +lastproofread: '2021-06-28' +--- + +(examples-azure-vpn-bgp)= + +# Route-Based Site-to-Site VPN to Azure (BGP over IKEv2/IPsec) + +This guide shows an example of a route-based IKEv2 site-to-site VPN to +Azure using VTI and BGP for dynamic routing updates. + +For redundant / active-active configurations see +{ref}`examples-azure-vpn-dual-bgp` + +## Prerequisites + +- A pair of Azure VNet Gateways deployed in active-passive + configuration with BGP enabled. +- A local network gateway deployed in Azure representing + the Vyos device, matching the below Vyos settings except for + address space, which only requires the Vyos private IP, in + this example 10.10.0.5/32 +- A connection resource deployed in Azure linking the + Azure VNet gateway and the local network gateway representing + the Vyos device. + +## Example + +```{eval-rst} ++---------------------------------------+---------------------+ +| WAN Interface | eth0 | ++---------------------------------------+---------------------+ +| On-premises address space | 10.10.0.0/16 | ++---------------------------------------+---------------------+ +| Azure address space | 10.0.0.0/16 | ++---------------------------------------+---------------------+ +| Vyos public IP | 198.51.100.3 | ++---------------------------------------+---------------------+ +| Vyos private IP | 10.10.0.5 | ++---------------------------------------+---------------------+ +| Azure VNet Gateway public IP | 203.0.113.2 | ++---------------------------------------+---------------------+ +| Azure VNet Gateway BGP IP | 10.0.0.4 | ++---------------------------------------+---------------------+ +| Pre-shared key | ch00s3-4-s3cur3-psk | ++---------------------------------------+---------------------+ +| Vyos ASN | 64499 | ++---------------------------------------+---------------------+ +| Azure ASN | 65540 | ++---------------------------------------+---------------------+ +``` + +## Vyos configuration + +- Configure the IKE and ESP settings to match a subset + of those supported by Azure: + +```none +set vpn ipsec esp-group AZURE lifetime '3600' +set vpn ipsec esp-group AZURE mode 'tunnel' +set vpn ipsec esp-group AZURE pfs 'dh-group2' +set vpn ipsec esp-group AZURE proposal 1 encryption 'aes256' +set vpn ipsec esp-group AZURE proposal 1 hash 'sha1' + +set vpn ipsec ike-group AZURE dead-peer-detection action 'restart' +set vpn ipsec ike-group AZURE dead-peer-detection interval '15' +set vpn ipsec ike-group AZURE dead-peer-detection timeout '30' +set vpn ipsec ike-group AZURE ikev2-reauth +set vpn ipsec ike-group AZURE key-exchange 'ikev2' +set vpn ipsec ike-group AZURE lifetime '28800' +set vpn ipsec ike-group AZURE proposal 1 dh-group '2' +set vpn ipsec ike-group AZURE proposal 1 encryption 'aes256' +set vpn ipsec ike-group AZURE proposal 1 hash 'sha1' +``` + +- Enable IPsec on eth0 + +```none +set vpn ipsec interface 'eth0' +``` + +- Configure a VTI with a dummy IP address + +```none +set interfaces vti vti1 address '10.10.1.5/32' +set interfaces vti vti1 description 'Azure Tunnel' +``` + +- Clamp the VTI's MSS to 1350 to avoid PMTU blackholes. + +```none +set interfaces vti vti1 ip adjust-mss 1350 +``` + +- Configure the VPN tunnel + +```none +set vpn ipsec authentication psk azure id '198.51.100.3' +set vpn ipsec authentication psk azure id '203.0.113.2' +set vpn ipsec authentication psk azure secret 'ch00s3-4-s3cur3-psk' +set vpn ipsec site-to-site peer azure authentication local-id '198.51.100.3' +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 remote-id '203.0.113.2' +set vpn ipsec site-to-site peer 203.0.113.2 connection-type 'respond' +set vpn ipsec site-to-site peer 203.0.113.2 description 'AZURE PRIMARY TUNNEL' +set vpn ipsec site-to-site peer 203.0.113.2 ike-group 'AZURE' +set vpn ipsec site-to-site peer 203.0.113.2 ikev2-reauth 'inherit' +set vpn ipsec site-to-site peer 203.0.113.2 local-address '10.10.0.5' +set vpn ipsec site-to-site peer azure remote-address '203.0.113.2' +set vpn ipsec site-to-site peer 203.0.113.2 vti bind 'vti1' +set vpn ipsec site-to-site peer 203.0.113.2 vti esp-group 'AZURE' +``` + +- **Important**: Add an interface route to reach Azure's BGP listener + +```none +set protocols static route 10.0.0.4/32 interface vti1 +``` + +- Configure your BGP settings + +```none +set protocols bgp system-as 64499 +set protocols bgp neighbor 10.0.0.4 remote-as '65540' +set protocols bgp neighbor 10.0.0.4 address-family ipv4-unicast soft-reconfiguration 'inbound' +set protocols bgp neighbor 10.0.0.4 timers holdtime '30' +set protocols bgp neighbor 10.0.0.4 timers keepalive '10' +``` + +- **Important**: Disable connected check  + +```none +set protocols bgp neighbor 10.0.0.4 disable-connected-check +``` diff --git a/docs/configexamples/md-azure-vpn-dual-bgp.md b/docs/configexamples/md-azure-vpn-dual-bgp.md new file mode 100644 index 00000000..e81b25f3 --- /dev/null +++ b/docs/configexamples/md-azure-vpn-dual-bgp.md @@ -0,0 +1,160 @@ +--- +lastproofread: '2021-06-28' +--- + +(examples-azure-vpn-dual-bgp)= + +# Route-Based Redundant Site-to-Site VPN to Azure (BGP over IKEv2/IPsec) + +This guide shows an example of a redundant (active-active) route-based IKEv2 +site-to-site VPN to Azure using VTI +and BGP for dynamic routing updates. + +## Prerequisites + +- A pair of Azure VNet Gateways deployed in active-active + configuration with BGP enabled. +- A local network gateway deployed in Azure representing + the Vyos device, matching the below Vyos settings except for + address space, which only requires the Vyos private IP, in + this example 10.10.0.5/32 +- A connection resource deployed in Azure linking the + Azure VNet gateway and the local network gateway representing + the Vyos device. + +## Example + +```{eval-rst} ++---------------------------------------+---------------------+ +| WAN Interface | eth0 | ++---------------------------------------+---------------------+ +| On-premises address space | 10.10.0.0/16 | ++---------------------------------------+---------------------+ +| Azure address space | 10.0.0.0/16 | ++---------------------------------------+---------------------+ +| Vyos public IP | 198.51.100.3 | ++---------------------------------------+---------------------+ +| Vyos private IP | 10.10.0.5 | ++---------------------------------------+---------------------+ +| Azure VNet Gateway 1 public IP | 203.0.113.2 | ++---------------------------------------+---------------------+ +| Azure VNet Gateway 2 public IP | 203.0.113.3 | ++---------------------------------------+---------------------+ +| Azure VNet Gateway BGP IP | 10.0.0.4,10.0.0.5 | ++---------------------------------------+---------------------+ +| Pre-shared key | ch00s3-4-s3cur3-psk | ++---------------------------------------+---------------------+ +| Vyos ASN | 64499 | ++---------------------------------------+---------------------+ +| Azure ASN | 65540 | ++---------------------------------------+---------------------+ +``` + +## Vyos configuration + +- Configure the IKE and ESP settings to match a subset + of those supported by Azure: + +```none +set vpn ipsec esp-group AZURE lifetime '3600' +set vpn ipsec esp-group AZURE mode 'tunnel' +set vpn ipsec esp-group AZURE pfs 'dh-group2' +set vpn ipsec esp-group AZURE proposal 1 encryption 'aes256' +set vpn ipsec esp-group AZURE proposal 1 hash 'sha1' + +set vpn ipsec ike-group AZURE dead-peer-detection action 'restart' +set vpn ipsec ike-group AZURE dead-peer-detection interval '15' +set vpn ipsec ike-group AZURE dead-peer-detection timeout '30' +set vpn ipsec ike-group AZURE ikev2-reauth +set vpn ipsec ike-group AZURE key-exchange 'ikev2' +set vpn ipsec ike-group AZURE lifetime '28800' +set vpn ipsec ike-group AZURE proposal 1 dh-group '2' +set vpn ipsec ike-group AZURE proposal 1 encryption 'aes256' +set vpn ipsec ike-group AZURE proposal 1 hash 'sha1' +``` + +- Enable IPsec on eth0 + +```none +set vpn ipsec interface 'eth0' +``` + +- Configure two VTIs with a dummy IP address each + +```none +set interfaces vti vti1 address '10.10.1.5/32' +set interfaces vti vti1 description 'Azure Primary Tunnel' + +set interfaces vti vti2 address '10.10.1.6/32' +set interfaces vti vti2 description 'Azure Secondary Tunnel' +``` + +- Clamp the VTI's MSS to 1350 to avoid PMTU blackholes. + +```none +set interfaces vti vti1 ip adjust-mss 1350 +set interfaces vti vti2 ip adjust-mss 1350 +``` + +- Configure the VPN tunnels + +```none +set vpn ipsec authentication psk azure id '198.51.100.3' +set vpn ipsec authentication psk azure id '203.0.113.2' +set vpn ipsec authentication psk azure id '203.0.113.3' +set vpn ipsec authentication psk azure secret 'ch00s3-4-s3cur3-psk' + +set vpn ipsec site-to-site peer azure-primary authentication local-id '198.51.100.3' +set vpn ipsec site-to-site peer azure-primary authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer azure-primary authentication remote-id '203.0.113.2' +set vpn ipsec site-to-site peer azure-primary connection-type 'respond' +set vpn ipsec site-to-site peer azure-primary description 'AZURE PRIMARY TUNNEL' +set vpn ipsec site-to-site peer azure-primary ike-group 'AZURE' +set vpn ipsec site-to-site peer azure-primary ikev2-reauth 'inherit' +set vpn ipsec site-to-site peer azure-primary local-address '10.10.0.5' +set vpn ipsec site-to-site peer azure-primary remote-address '203.0.113.2' +set vpn ipsec site-to-site peer azure-primary vti bind 'vti1' +set vpn ipsec site-to-site peer azure-primary vti esp-group 'AZURE' + +set vpn ipsec site-to-site peer azure-secondary authentication local-id '198.51.100.3' +set vpn ipsec site-to-site peer azure-secondary authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer azure-secondary authentication remote-id '203.0.113.3' +set vpn ipsec site-to-site peer azure-secondary connection-type 'respond' +set vpn ipsec site-to-site peer azure-secondary description 'AZURE secondary TUNNEL' +set vpn ipsec site-to-site peer azure-secondary ike-group 'AZURE' +set vpn ipsec site-to-site peer azure-secondary ikev2-reauth 'inherit' +set vpn ipsec site-to-site peer azure-secondary local-address '10.10.0.5' +set vpn ipsec site-to-site peer azure-secondary remote-address '203.0.113.3' +set vpn ipsec site-to-site peer azure-secondary vti bind 'vti2' +set vpn ipsec site-to-site peer azure-secondary vti esp-group 'AZURE' +``` + +- **Important**: Add an interface route to reach both Azure's BGP listeners + +```none +set protocols static route 10.0.0.4/32 interface vti1 +set protocols static route 10.0.0.5/32 interface vti2 +``` + +- Configure your BGP settings + +```none +set protocols bgp system-as 64499 +set protocols bgp neighbor 10.0.0.4 remote-as '65540' +set protocols bgp neighbor 10.0.0.4 address-family ipv4-unicast soft-reconfiguration 'inbound' +set protocols bgp neighbor 10.0.0.4 timers holdtime '30' +set protocols bgp neighbor 10.0.0.4 timers keepalive '10' + +set protocols bgp neighbor 10.0.0.5 remote-as '65540' +set protocols bgp neighbor 10.0.0.5 address-family ipv4-unicast soft-reconfiguration 'inbound' +set protocols bgp neighbor 10.0.0.5 timers holdtime '30' +set protocols bgp neighbor 10.0.0.5 timers keepalive '10' +``` + +- **Important**: Disable connected check, otherwise the routes learned + from Azure will not be imported into the routing table. + +```none +set protocols bgp neighbor 10.0.0.4 disable-connected-check +set protocols bgp neighbor 10.0.0.5 disable-connected-check +``` diff --git a/docs/configexamples/md-bgp-ipv6-unnumbered.md b/docs/configexamples/md-bgp-ipv6-unnumbered.md new file mode 100644 index 00000000..4fa29834 --- /dev/null +++ b/docs/configexamples/md-bgp-ipv6-unnumbered.md @@ -0,0 +1,174 @@ +--- +lastproofread: '2021-06-28' +--- + +(examples-bgp-ipv6-unnumbered)= + +# BGP IPv6 unnumbered with extended nexthop + +General information can be found in the {ref}`routing-bgp` chapter. + +## Configuration + +- Router A: + +```none +set protocols bgp system-as 64496 +set protocols bgp address-family ipv4-unicast redistribute connected +set protocols bgp address-family ipv6-unicast redistribute connected +set protocols bgp neighbor eth1 interface v6only +set protocols bgp neighbor eth1 interface v6only peer-group 'fabric' +set protocols bgp neighbor eth2 interface v6only +set protocols bgp neighbor eth2 interface v6only peer-group 'fabric' +set protocols bgp parameters bestpath as-path multipath-relax +set protocols bgp parameters bestpath compare-routerid +set protocols bgp parameters default no-ipv4-unicast +set protocols bgp parameters router-id '192.168.0.1' +set protocols bgp peer-group fabric address-family ipv4-unicast +set protocols bgp peer-group fabric address-family ipv6-unicast +set protocols bgp peer-group fabric capability extended-nexthop +set protocols bgp peer-group fabric remote-as 'external' +``` + +- Router B: + +```none +set protocols bgp system-as 64499 +set protocols bgp address-family ipv4-unicast redistribute connected +set protocols bgp address-family ipv6-unicast redistribute connected +set protocols bgp neighbor eth1 interface v6only +set protocols bgp neighbor eth1 interface v6only peer-group 'fabric' +set protocols bgp neighbor eth2 interface v6only +set protocols bgp neighbor eth2 interface v6only peer-group 'fabric' +set protocols bgp parameters bestpath as-path multipath-relax +set protocols bgp parameters bestpath compare-routerid +set protocols bgp parameters default no-ipv4-unicast +set protocols bgp parameters router-id '192.168.0.2' +set protocols bgp peer-group fabric address-family ipv4-unicast +set protocols bgp peer-group fabric address-family ipv6-unicast +set protocols bgp peer-group fabric capability extended-nexthop +set protocols bgp peer-group fabric remote-as 'external' +``` + + +## Results + +- Router A: + +```none +vyos@vyos:~$ show interfaces +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +eth0 198.51.100.34/24 u/u +eth1 - u/u +eth2 - u/u +lo 127.0.0.1/8 u/u + 192.168.0.1/32 + ::1/128 +``` + +```none +vyos@vyos:~$ show ip route +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route + +S>* 0.0.0.0/0 [210/0] via 198.51.100.34, eth0, 03:21:53 +C>* 198.51.100.0/24 is directly connected, eth0, 03:21:53 +C>* 192.168.0.1/32 is directly connected, lo, 03:21:56 +B>* 192.168.0.2/32 [20/0] via fe80::a00:27ff:fe3b:7ed2, eth2, 00:05:07 + * via fe80::a00:27ff:fe7b:4000, eth1, 00:05:07 +``` + +```none +vyos@vyos:~$ ping 192.168.0.2 +PING 192.168.0.2 (192.168.0.2) 56(84) bytes of data. +64 bytes from 192.168.0.2: icmp_seq=1 ttl=64 time=0.575 ms +64 bytes from 192.168.0.2: icmp_seq=2 ttl=64 time=0.628 ms +64 bytes from 192.168.0.2: icmp_seq=3 ttl=64 time=0.581 ms +64 bytes from 192.168.0.2: icmp_seq=4 ttl=64 time=0.682 ms +64 bytes from 192.168.0.2: icmp_seq=5 ttl=64 time=0.597 ms + +--- 192.168.0.2 ping statistics --- +5 packets transmitted, 5 received, 0% packet loss, time 4086ms +rtt min/avg/max/mdev = 0.575/0.612/0.682/0.047 ms +``` + +```none +vyos@vyos:~$ show ip bgp summary + +IPv4 Unicast Summary: +BGP router identifier 192.168.0.1, local AS number 64496 vrf-id 0 +BGP table version 4 +RIB entries 5, using 800 bytes of memory +Peers 2, using 41 KiB of memory +Peer groups 1, using 64 bytes of memory + +Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd +eth1 4 64499 13 13 0 0 0 00:05:33 2 +eth2 4 64499 13 14 0 0 0 00:05:29 2 + +Total number of neighbors 2 +``` + +- Router B: + +```none +vyos@vyos:~$ show interfaces +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +eth0 198.51.100.33/24 u/u +eth1 - u/u +eth2 - u/u +lo 127.0.0.1/8 u/u + 192.168.0.2/32 + ::1/128 +``` + +```none +vyos@vyos:~$ show ip route +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route + +S>* 0.0.0.0/0 [210/0] via 198.51.100.33, eth0, 00:44:08 +C>* 198.51.100.0/24 is directly connected, eth0, 00:44:09 +B>* 192.168.0.1/32 [20/0] via fe80::a00:27ff:fe2d:205d, eth1, 00:06:18 + * via fe80::a00:27ff:fe93:e142, eth2, 00:06:18 +C>* 192.168.0.2/32 is directly connected, lo, 00:44:11 +``` + +```none +vyos@vyos:~$ ping 192.168.0.1 +PING 192.168.0.1 (192.168.0.1) 56(84) bytes of data. +64 bytes from 192.168.0.1: icmp_seq=1 ttl=64 time=0.427 ms +64 bytes from 192.168.0.1: icmp_seq=2 ttl=64 time=0.471 ms +64 bytes from 192.168.0.1: icmp_seq=3 ttl=64 time=0.782 ms +64 bytes from 192.168.0.1: icmp_seq=4 ttl=64 time=0.715 ms + +--- 192.168.0.1 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 3051ms +rtt min/avg/max/mdev = 0.427/0.598/0.782/0.155 ms +``` + +```none +vyos@vyos:~$ show ip bgp summary +IPv4 Unicast Summary: +BGP router identifier 192.168.0.2, local AS number 64499 vrf-id 0 +BGP table version 4 +RIB entries 5, using 800 bytes of memory +Peers 2, using 41 KiB of memory +Peer groups 1, using 64 bytes of memory + +Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd +eth1 4 64496 14 14 0 0 0 00:06:40 2 +eth2 4 64496 14 14 0 0 0 00:06:37 2 + +Total number of neighbors 2 +``` diff --git a/docs/configexamples/md-firewall.md b/docs/configexamples/md-firewall.md new file mode 100644 index 00000000..1f6f0b9a --- /dev/null +++ b/docs/configexamples/md-firewall.md @@ -0,0 +1,15 @@ +--- +lastproofread: '2024-06-14' +--- + +# Firewall Examples + +This section contains examples of firewall configurations for various deployments. + +```{eval-rst} +.. toctree:: + :maxdepth: 2 + + fwall-and-vrf + zone-policy +``` diff --git a/docs/configexamples/md-fwall-and-vrf.md b/docs/configexamples/md-fwall-and-vrf.md new file mode 100644 index 00000000..f1be96a2 --- /dev/null +++ b/docs/configexamples/md-fwall-and-vrf.md @@ -0,0 +1,119 @@ +# VRF and firewall example + +## Scenario and requirements + +This example shows how to configure a VyOS router with VRFs and firewall rules. + +Diagram used in this example: + +```{image} /_static/images/firewall-and-vrf-blueprints.png +:align: center +:alt: Network Topology Diagram +:width: 80% +``` + +As exposed in the diagram, there are four VRFs. These VRFs are `MGMT`, +`WAN`, `LAN` and `PROD`, and their requirements are: + +- VRF MGMT: + : - Allow connections to LAN and PROD. + - Deny connections to internet(WAN). + - Allow connections to the router. +- VRF LAN: + : - Allow connections to PROD. + - Allow connections to internet(WAN). +- VRF PROD: + : - Only accepts connections. +- VRF WAN: + : - Allow connection to PROD. + +## Configuration + +First, we need to configure the interfaces and VRFs: + +```none +set interfaces ethernet eth1 address '10.100.100.1/24' +set interfaces ethernet eth1 vrf 'MGMT' +set interfaces ethernet eth2 vif 150 address '10.150.150.1/24' +set interfaces ethernet eth2 vif 150 vrf 'LAN' +set interfaces ethernet eth2 vif 160 address '10.160.160.1/24' +set interfaces ethernet eth2 vif 160 vrf 'LAN' +set interfaces ethernet eth2 vif 3500 address '172.16.20.1/24' +set interfaces ethernet eth2 vif 3500 vrf 'PROD' +set interfaces loopback lo +set interfaces pppoe pppoe0 authentication password 'p4ssw0rd' +set interfaces pppoe pppoe0 authentication username 'vyos' +set interfaces pppoe pppoe0 source-interface 'eth0' +set interfaces pppoe pppoe0 vrf 'WAN' +set vrf bind-to-all +set vrf name LAN protocols static route 0.0.0.0/0 interface pppoe0 vrf 'WAN' +set vrf name LAN protocols static route 10.100.100.0/24 interface eth1 vrf 'MGMT' +set vrf name LAN protocols static route 172.16.20.0/24 interface eth2.3500 vrf 'PROD' +set vrf name LAN table '103' +set vrf name MGMT protocols static route 10.150.150.0/24 interface eth2.150 vrf 'LAN' +set vrf name MGMT protocols static route 10.160.160.0/24 interface eth2.160 vrf 'LAN' +set vrf name MGMT protocols static route 172.16.20.0/24 interface eth2.3500 vrf 'PROD' +set vrf name MGMT table '102' +set vrf name PROD protocols static route 0.0.0.0/0 interface pppoe0 vrf 'WAN' +set vrf name PROD protocols static route 10.100.100.0/24 interface eth1 vrf 'MGMT' +set vrf name PROD protocols static route 10.150.150.0/24 interface eth2.150 vrf 'LAN' +set vrf name PROD protocols static route 10.160.160.0/24 interface eth2.160 vrf 'LAN' +set vrf name PROD table '104' +set vrf name WAN protocols static route 10.150.150.0/24 interface eth2.150 vrf 'LAN' +set vrf name WAN protocols static route 10.160.160.0/24 interface eth2.160 vrf 'LAN' +set vrf name WAN protocols static route 172.16.20.0/24 interface eth2.3500 vrf 'PROD' +set vrf name WAN table '101' +``` + +And before firewall rules are shown, we need to pay attention how to configure +and match interfaces and VRFs. In case where an interface is assigned to a +non-default VRF, if we want to use inbound-interface or outbound-interface in +firewall rules, we need to: + +- For **inbound-interface**: use the interface name with the VRF name, like + `MGMT` or `LAN`. +- For **outbound-interface**: use the interface name, like `eth0`, `vtun0`, + `eth2*` or similar. + +Next, we need to configure the firewall rules. First we will define all rules +for transit traffic between VRFs. + +```none +set firewall ipv4 forward filter default-action 'drop' +set firewall ipv4 forward filter default-log +set firewall ipv4 forward filter rule 10 action 'accept' +set firewall ipv4 forward filter rule 10 description 'MGMT - Allow to LAN and PROD' +set firewall ipv4 forward filter rule 10 inbound-interface name 'MGMT' +set firewall ipv4 forward filter rule 10 outbound-interface name 'eth2*' +set firewall ipv4 forward filter rule 99 action 'drop' +set firewall ipv4 forward filter rule 99 description 'MGMT - Drop all going to mgmt' +set firewall ipv4 forward filter rule 99 outbound-interface name 'eth1' +set firewall ipv4 forward filter rule 120 action 'accept' +set firewall ipv4 forward filter rule 120 description 'LAN - Allow to PROD' +set firewall ipv4 forward filter rule 120 inbound-interface name 'LAN' +set firewall ipv4 forward filter rule 120 outbound-interface name 'eth2.3500' +set firewall ipv4 forward filter rule 130 action 'accept' +set firewall ipv4 forward filter rule 130 description 'LAN - Allow internet' +set firewall ipv4 forward filter rule 130 inbound-interface name 'LAN' +set firewall ipv4 forward filter rule 130 outbound-interface name 'pppoe0' +``` + +Also, we are adding global state policies, in order to allow established and +related traffic, in order not to drop valid responses: + +```none +set firewall global-options state-policy established action 'accept' +set firewall global-options state-policy invalid action 'drop' +set firewall global-options state-policy related action 'accept' +``` + +And finally, we need to allow input connections to the router itself only from +vrf MGMT: + +```none +set firewall ipv4 input filter default-action 'drop' +set firewall ipv4 input filter default-log +set firewall ipv4 input filter rule 10 action 'accept' +set firewall ipv4 input filter rule 10 description 'MGMT - Allow input' +set firewall ipv4 input filter rule 10 inbound-interface name 'MGMT' +``` diff --git a/docs/configexamples/md-ha.md b/docs/configexamples/md-ha.md new file mode 100644 index 00000000..83e3b65e --- /dev/null +++ b/docs/configexamples/md-ha.md @@ -0,0 +1,545 @@ +--- +lastproofread: '2021-06-28' +--- + +(example-high-availability)= + +# High Availability Walkthrough + +This document walks you through a complete HA setup of two VyOS machines. This +design is based on a VM as the primary router and a physical machine as a +backup, using VRRP, BGP, OSPF, and conntrack sharing. + +This document aims to walk you through setting everything up, so +at a point where you can reboot any machine and not lose more than a few +seconds worth of connectivity. + +## Design + +This is based on a real-life production design. One of the complex issues +is ensuring you have redundant data INTO your network. We do this with a pair +of Cisco Nexus switches and using Virtual PortChannels that are spanned across +them. As a bonus, this also allows for complete switch failure without +an outage. How you achieve this yourself is left as an exercise to the reader. +But our setup is documented here. + +### Walkthrough suggestion + +The `commit` command is implied after every section. If you make an error, +`commit` will warn you and you can fix it before getting too far into things. +Please ensure you commit early and commit often. + +If you are following through this document, it is strongly suggested you +complete the entire document, ONLY doing the virtual router1 steps, and then +come back and walk through it AGAIN on the backup hardware router. + +This ensures you don't go too fast or miss a step. However, it will make your +life easier to configure the fixed IP address and default route now on the +hardware router. + +### Example Network + +In this document, we have been allocated 203.0.113.0/24 by our upstream +provider, which we are publishing on VLAN100. + +They want us to establish a BGP session to their routers on 192.0.2.11 and +192.0.2.12 from our routers 192.0.2.21 and 192.0.2.22. They are AS 65550 and +we are AS 65551. + +Our routers are going to have a floating IP address of 203.0.113.1, and use +.2 and .3 as their fixed IPs. + +We are going to use 10.200.201.0/24 for an 'internal' network on VLAN201. + +When traffic is originated from the 10.200.201.0/24 network, it will be +masqueraded to 203.0.113.1 + +For connection between sites, we are running a WireGuard link to two REMOTE +routers and using OSPF over those links to distribute routes. That remote +site is expected to send traffic from anything in 10.201.0.0/16 + +### VLANs + +These are the vlans we will be using: + +- 50: Upstream, using the 192.0.2.0/24 network allocated by them. +- 100: 'Public' network, using our 203.0.113.0/24 network. +- 201: 'Internal' network, using 10.200.201.0/24 + +### Hardware + +- switch1 (Nexus 10gb Switch) +- switch2 (Nexus 10gb Switch) +- compute1 (VMware ESXi 6.5) +- compute2 (VMware ESXi 6.5) +- compute3 (VMware ESXi 6.5) +- router2 (Random 1RU machine with 4 NICs) + +Note that router1 is a VM that runs on one of the compute nodes. + +### Network Cabling + +- From Datacenter - This connects into port 1 on both switches, and is tagged + as VLAN 50 +- Cisco VPC Crossconnect - Ports 39 and 40 bonded between each switch +- Hardware Router - Port 8 of each switch +- compute1 - Port 9 of each switch +- compute2 - Port 10 of each switch +- compute3 - Port 11 of each switch + +This is ignoring the extra Out-of-band management networking, which should be +on totally different switches, and a different feed into the rack, and is out +of scope of this. + +:::{note} +Our implementation uses VMware's Distributed Port Groups, which allows +VMware to use LACP. This is a part of the ENTERPRISE licence, and is not +available on a free licence. If you are implementing this and do not have +access to DPGs, you should not use VMware, and use some other virtualization +platform instead. +::: + +## Basic Setup (via console) + +Create your router1 VM. So it can withstand a VM Host failing or a +network link failing. Using VMware, this is achieved by enabling vSphere DRS, +vSphere Availability, and creating a Distributed Port Group that uses LACP. + +Many other Hypervisors do this, and I'm hoping that this document will be +expanded to document how to do this for others. + +Create an 'All VLANs' network group, that passes all trunked traffic through +to the VM. Attach this network group to router1 as eth0. + +:::{note} +VMware: You must DISABLE SECURITY on this Port group. Make sure that +`Promiscuous Mode`, `MAC address changes` and `Forged transmits` are +enabled. All of these will be done as part of failover. +::: + +### Bonding on Hardware Router + +Create a LACP bond on the hardware router. We are assuming that eth0 and eth1 +are connected to port 8 on both switches, and that those ports are configured +as a Port-Channel. + +```none +set interfaces bonding bond0 description 'Switch Port-Channel' +set interfaces bonding bond0 hash-policy 'layer2' +set interfaces bonding bond0 member interface 'eth0' +set interfaces bonding bond0 member interface 'eth1' +set interfaces bonding bond0 mode '802.3ad' +``` + +### Assign external IP addresses + +VLAN 100 and 201 will have floating IP addresses, but VLAN50 does not, as this +is talking directly to upstream. Create our IP address on vlan50. + +For the hardware router, replace `eth0` with `bond0`. As (almost) every +command is identical, this will not be specified unless different things need +to be performed on different hosts. + +```none +set interfaces ethernet eth0 vif 50 address '192.0.2.21/24' +``` + +In this case, the hardware router has a different IP, so it would be + +```none +set interfaces ethernet bond0 vif 50 address '192.0.2.22/24' +``` + +### Add (temporary) default route + +It is assumed that the routers provided by upstream are capable of acting as a +default router, add that as a static route. + +```none +set protocols static route 0.0.0.0/0 next-hop 192.0.2.11 +commit +save +``` + +### Enable SSH + +Enable SSH so you can now SSH into the routers, rather than using the console. + +```none +set service ssh +commit +save +``` + +At this point, you should be able to SSH into both of them, and will no longer +need access to the console (unless you break something!) + +## VRRP Configuration + +We are setting up VRRP so that it does NOT fail back when a machine returns into +service, and it prioritizes router1 over router2. + +### Internal Network + +This has a floating IP address of 10.200.201.1/24, using virtual router ID 201. +The difference between them is the interface name, hello-source-address, and +peer-address. + +**router1** + +```none +set interfaces ethernet eth0 vif 201 address 10.200.201.2/24 +set high-availability vrrp group int hello-source-address '10.200.201.2' +set high-availability vrrp group int interface 'eth0.201' +set high-availability vrrp group int peer-address '10.200.201.3' +set high-availability vrrp group int no-preempt +set high-availability vrrp group int priority '200' +set high-availability vrrp group int address '10.200.201.1/24' +set high-availability vrrp group int vrid '201' +``` + +**router2** + +```none +set interfaces ethernet bond0 vif 201 address 10.200.201.3/24 +set high-availability vrrp group int hello-source-address '10.200.201.3' +set high-availability vrrp group int interface 'bond0.201' +set high-availability vrrp group int peer-address '10.200.201.2' +set high-availability vrrp group int no-preempt +set high-availability vrrp group int priority '100' +set high-availability vrrp group int address '10.200.201.1/24' +set high-availability vrrp group int vrid '201' +``` + +### Public Network + +This has a floating IP address of 203.0.113.1/24, using virtual router ID 113. +The virtual router ID is just a random number between 1 and 254, and can be set +to whatever you want. Best practices suggest you try to keep them unique +enterprise-wide. + +**router1** + +```none +set interfaces ethernet eth0 vif 100 address 203.0.113.2/24 +set high-availability vrrp group public hello-source-address '203.0.113.2' +set high-availability vrrp group public interface 'eth0.100' +set high-availability vrrp group public peer-address '203.0.113.3' +set high-availability vrrp group public no-preempt +set high-availability vrrp group public priority '200' +set high-availability vrrp group public address '203.0.113.1/24' +set high-availability vrrp group public vrid '113' +``` + +**router2** + +```none +set interfaces ethernet bond0 vif 100 address 203.0.113.3/24 +set high-availability vrrp group public hello-source-address '203.0.113.3' +set high-availability vrrp group public interface 'bond0.100' +set high-availability vrrp group public peer-address '203.0.113.2' +set high-availability vrrp group public no-preempt +set high-availability vrrp group public priority '100' +set high-availability vrrp group public address '203.0.113.1/24' +set high-availability vrrp group public vrid '113' +``` + +### Create VRRP sync-group + +The sync group is used to replicate connection tracking. It needs to be assigned +to a random VRRP group, and we are creating a sync group called `sync` using +the vrrp group `int`. + +```none +set high-availability vrrp sync-group sync member 'int' +``` + +### Testing + +At this point, you should be able to see both IP addresses when you run +`show interfaces`, and `show vrrp` should show both interfaces in MASTER +state (and SLAVE state on router2). + +```none +vyos@router1:~$ show vrrp +Name Interface VRID State Last Transition +-------- ----------- ------ ------- ----------------- +int eth0.201 201 MASTER 100s +public eth0.100 113 MASTER 200s +vyos@router1:~$ +``` + +You should be able to ping to and from all the IPs you have allocated. + +## NAT and conntrack-sync + +Masquerade Traffic originating from 10.200.201.0/24 that is heading out the +public interface. + +:::{note} +We explicitly exclude the primary upstream network so that BGP or +OSPF traffic doesn't accidentally get NAT'ed. +::: + +```none +set nat source rule 10 destination address '!192.0.2.0/24' +set nat source rule 10 outbound-interface 'eth0.50' +set nat source rule 10 source address '10.200.201.0/24' +set nat source rule 10 translation address '203.0.113.1' +``` + +### Configure conntrack-sync and enable helpers + +Conntrack helper modules are enabled by default, but they tend to cause more +problems than they're worth in complex networks. You can disable all of them +at one go. + +```none +delete system conntrack modules +``` + +Now enable replication between nodes. Replace eth0.201 with bond0.201 on the +hardware router. + +```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 vrrp sync-group 'sync' +set service conntrack-sync interface eth0.201 +set service conntrack-sync mcast-group '224.0.0.50' +set service conntrack-sync sync-queue-size '8' +``` + +(ha-contracktesting)= + +### Testing + +The simplest way to test is to look at the connection tracking stats on the +standby hardware router with the command `show conntrack-sync statistics`. +The numbers should be very close to the numbers on the primary router. + +When you have both routers up, you should be able to establish a connection +from a NAT'ed machine out to the internet, reboot the active machine, and that +connection should be preserved, and will not drop out. + +## OSPF Over WireGuard + +Wireguard doesn't have the concept of an up or down link, due to its design. +This complicates AND simplifies using it for network transport, as for reliable +state detection you need to use SOMETHING to detect when the link is down. + +If you use a routing protocol itself, you solve two problems at once. This is +only a basic example, and is provided as a starting point. + +### Configure Wireguard + +There is plenty of instructions and documentation on setting up Wireguard. The +only important thing you need to remember is to only use one WireGuard +interface per OSPF connection. + +We use small /30's from 10.254.60/24 for the point-to-point links. + +**router1** + +Replace the 203.0.113.3 with whatever the other router's IP address is. + +```none +set interfaces wireguard wg01 address '10.254.60.1/30' +set interfaces wireguard wg01 description 'router1-to-offsite1' +set interfaces wireguard wg01 peer OFFSITE1 allowed-ips '0.0.0.0/0' +set interfaces wireguard wg01 peer OFFSITE1 endpoint '203.0.113.3:50001' +set interfaces wireguard wg01 peer OFFSITE1 persistent-keepalive '15' +set interfaces wireguard wg01 peer OFFSITE1 pubkey 'GEFMOWzAyau42/HwdwfXnrfHdIISQF8YHj35rOgSZ0o=' +set interfaces wireguard wg01 port '50001' +set protocols ospf interface wg01 authentication md5 key-id 1 md5-key 'i360KoCwUGZvPq7e' +set protocols ospf interface wg01 cost '11' +set protocols ospf interface wg01 dead-interval '5' +set protocols ospf interface wg01 hello-interval '1' +set protocols ospf interface wg01 network 'point-to-point' +set protocols ospf interface wg01 priority '1' +set protocols ospf interface wg01 retransmit-interval '5' +set protocols ospf interface wg01 transmit-delay '1' +``` + +**offsite1** + +This is connecting back to the STATIC IP of router1, not the floating. + +```none +set interfaces wireguard wg01 address '10.254.60.2/30' +set interfaces wireguard wg01 description 'offsite1-to-router1' +set interfaces wireguard wg01 peer ROUTER1 allowed-ips '0.0.0.0/0' +set interfaces wireguard wg01 peer ROUTER1 endpoint '192.0.2.21:50001' +set interfaces wireguard wg01 peer ROUTER1 persistent-keepalive '15' +set interfaces wireguard wg01 peer ROUTER1 pubkey 'CKwMV3ZaLntMule2Kd3G7UyVBR7zE8/qoZgLb82EE2Q=' +set interfaces wireguard wg01 port '50001' +set protocols ospf interface wg01 authentication md5 key-id 1 md5-key 'i360KoCwUGZvPq7e' +set protocols ospf interface wg01 cost '11' +set protocols ospf interface wg01 dead-interval '5' +set protocols ospf interface wg01 hello-interval '1' +set protocols ospf interface wg01 network 'point-to-point' +set protocols ospf interface wg01 priority '1' +set protocols ospf interface wg01 retransmit-interval '5' +set protocols ospf interface wg01 transmit-delay '1' +``` + +### Test WireGuard + +Make sure you can ping 10.254.60.1 and .2 from both routers. + +### Create Export Filter + +We only want to export the networks we know. Always do a whitelist on your route +filters, both importing and exporting. A good rule of thumb is +**'If you are not the default router for a network, don't advertise +it'**. This means we explicitly do not want to advertise the 192.0.2.0/24 +network (but do want to advertise 10.200.201.0 and 203.0.113.0, which we ARE +the default route for). This filter is applied to `redistribute connected`. +If we WERE to advertise it, the remote machines would see 192.0.2.21 available +via their default route, establish the connection, and then OSPF would say +'192.0.2.0/24 is available via this tunnel', at which point the tunnel would +break, OSPF would drop the routes, and then 192.0.2.0/24 would be reachable via +default again. This is called 'flapping'. + +```none +set policy access-list 150 description 'Outbound OSPF Redistribution' +set policy access-list 150 rule 10 action 'permit' +set policy access-list 150 rule 10 destination any +set policy access-list 150 rule 10 source inverse-mask '0.0.0.255' +set policy access-list 150 rule 10 source network '10.200.201.0' +set policy access-list 150 rule 20 action 'permit' +set policy access-list 150 rule 20 destination any +set policy access-list 150 rule 20 source inverse-mask '0.0.0.255' +set policy access-list 150 rule 20 source network '203.0.113.0' +set policy access-list 150 rule 100 action 'deny' +set policy access-list 150 rule 100 destination any +set policy access-list 150 rule 100 source any +``` + +### Create Import Filter + +We only want to import networks we know. Our OSPF peer should only be +advertising networks in the 10.201.0.0/16 range. Note that this is an INVERSE +MATCH. You deny in access-list 100 to accept the route. + +```none +set policy access-list 100 description 'Inbound OSPF Routes from Peers' +set policy access-list 100 rule 10 action 'deny' +set policy access-list 100 rule 10 destination any +set policy access-list 100 rule 10 source inverse-mask '0.0.255.255' +set policy access-list 100 rule 10 source network '10.201.0.0' +set policy access-list 100 rule 100 action 'permit' +set policy access-list 100 rule 100 destination any +set policy access-list 100 rule 100 source any +set policy route-map PUBOSPF rule 100 action 'deny' +set policy route-map PUBOSPF rule 100 match ip address access-list '100' +set policy route-map PUBOSPF rule 500 action 'permit' +``` + +### Enable OSPF + +Every router **must** have a unique router-id. +The 'reference-bandwidth' is used because when OSPF was originally designed, +the idea of a link faster than 1gbit was unheard of, and it does not scale +correctly. + +```none +set protocols ospf area 0.0.0.0 authentication 'md5' +set protocols ospf area 0.0.0.0 network '10.254.60.0/24' +set protocols ospf auto-cost reference-bandwidth '10000' +set protocols ospf log-adjacency-changes +set protocols ospf parameters abr-type 'cisco' +set protocols ospf parameters router-id '10.254.60.2' +set protocols ospf route-map PUBOSPF +``` + +### Test OSPF + +When you have enabled OSPF on both routers, you should be able to see each +other with the command `show ip ospf neighbour`. The state must be 'Full' +or '2-Way'. If it is not, then there is a network connectivity issue between the +hosts. This is often caused by NAT or MTU issues. You should not see any new +routes (unless this is the second pass) in the output of `show ip route` + +## Advertise connected routes + +As a reminder, only advertise routes that you are the default router for. This +is why we are NOT announcing the 192.0.2.0/24 network, because if that was +announced into OSPF, the other routers would try to connect to that network +over a tunnel that connects to that network! + +```none +set protocols ospf access-list 150 export 'connected' +set protocols ospf redistribute connected +``` + +You should now be able to see the advertised network on the other host. + +### Duplicate configuration + +At this point, you now need to create the X link between all four routers. +Use amdifferent /30 for each link. + +### Priorities + +Set the cost on the secondary links to be 200. This means that they will not +be used unless the primary links are down. + +```none +set protocols ospf interface wg01 cost '10' +set protocols ospf interface wg01 cost '200' +``` + +This will be visible in 'show ip route'. + +## BGP + +BGP is an extremely complex network protocol. An example is provided here. + +:::{note} +Router id's must be unique. +::: + +**router1** + +The `redistribute ospf` command is there purely as an example of how this can +be expanded. In this walkthrough, it will be filtered by BGPOUT rule 10000, as +it is not 203.0.113.0/24. + +```none +set policy prefix-list BGPOUT description 'BGP Export List' +set policy prefix-list BGPOUT rule 10 action 'deny' +set policy prefix-list BGPOUT rule 10 description 'Do not advertise short masks' +set policy prefix-list BGPOUT rule 10 ge '25' +set policy prefix-list BGPOUT rule 10 prefix '0.0.0.0/0' +set policy prefix-list BGPOUT rule 100 action 'permit' +set policy prefix-list BGPOUT rule 100 description 'Our network' +set policy prefix-list BGPOUT rule 100 prefix '203.0.113.0/24' +set policy prefix-list BGPOUT rule 10000 action 'deny' +set policy prefix-list BGPOUT rule 10000 prefix '0.0.0.0/0' + +set policy route-map BGPOUT description 'BGP Export Filter' +set policy route-map BGPOUT rule 10 action 'permit' +set policy route-map BGPOUT rule 10 match ip address prefix-list 'BGPOUT' +set policy route-map BGPOUT rule 10000 action 'deny' +set policy route-map BGPPREPENDOUT description 'BGP Export Filter' +set policy route-map BGPPREPENDOUT rule 10 action 'permit' +set policy route-map BGPPREPENDOUT rule 10 set as-path prepend '65551 65551 65551' +set policy route-map BGPPREPENDOUT rule 10 match ip address prefix-list 'BGPOUT' +set policy route-map BGPPREPENDOUT rule 10000 action 'deny' + +set protocols bgp system-as 65551 +set protocols bgp address-family ipv4-unicast network 192.0.2.0/24 +set protocols bgp address-family ipv4-unicast redistribute connected metric '50' +set protocols bgp address-family ipv4-unicast redistribute ospf metric '50' +set protocols bgp neighbor 192.0.2.11 address-family ipv4-unicast route-map export 'BGPOUT' +set protocols bgp neighbor 192.0.2.11 address-family ipv4-unicast soft-reconfiguration inbound +set protocols bgp neighbor 192.0.2.11 remote-as '65550' +set protocols bgp neighbor 192.0.2.11 update-source '192.0.2.21' +set protocols bgp parameters router-id '192.0.2.21' +``` + +**router2** + +This is identical, but you use the BGPPREPENDOUT route-map to advertise the +route with a longer path. diff --git a/docs/configexamples/md-index.md b/docs/configexamples/md-index.md new file mode 100644 index 00000000..78490de4 --- /dev/null +++ b/docs/configexamples/md-index.md @@ -0,0 +1,59 @@ +(examples)= + +# Configuration Blueprints + +This chapter contains various configuration examples: + +```{eval-rst} +.. toctree:: + :maxdepth: 2 + + firewall + bgp-ipv6-unnumbered + ospf-unnumbered + azure-vpn-bgp + azure-vpn-dual-bgp + ha + wan-load-balancing + pppoe-ipv6-basic + l3vpn-hub-and-spoke + lac-lns + inter-vrf-routing-vrf-lite + qos + segment-routing-isis + nmp + ipsec-cisco-policy-based + ipsec-cisco-route-based + ipsec-pa-route-based + +``` + +# Configuration Blueprints (autotest) + +The next pages contains automatic full tested configuration examples. + +Each lab will build an test from an external script. +The page content will generate, so changes will not take an effect. + +A host `vyos-oobm` will use as a ssh proxy. This host is just +necessary for the Lab test. + +The process will do the following steps: + +1. create the lab on a eve-ng server +2. configure each host in the lab +3. do some defined tests +4. optional do an upgrade to a higher version and do step 3 again. +5. generate the documentation and include files +6. shutdown and destroy the lab, if there is no error + +```{eval-rst} +.. toctree:: + :maxdepth: 1 + + autotest/DHCPRelay_through_GRE/DHCPRelay_through_GRE + autotest/tunnelbroker/tunnelbroker + autotest/L3VPN_EVPN/L3VPN_EVPN + autotest/Wireguard/Wireguard + autotest/OpenVPN_with_LDAP/OpenVPN_with_LDAP +``` diff --git a/docs/configexamples/md-inter-vrf-routing-vrf-lite.md b/docs/configexamples/md-inter-vrf-routing-vrf-lite.md new file mode 100644 index 00000000..50e666a9 --- /dev/null +++ b/docs/configexamples/md-inter-vrf-routing-vrf-lite.md @@ -0,0 +1,798 @@ +# Inter-VRF Routing over VRF Lite + +**Virtual Routing and Forwarding** is a technology that allow multiple instance +of a routing table to exist within a single device. One of the key aspect of +**VRFs** is that do not share the same routes or interfaces, therefore packets +are forwarded between interfaces that belong to the same VRF only. + +Any information related to a VRF is not exchanged between devices -or in the +same device- by default, this is a technique called **VRF-Lite**. + +Keep networks isolated is -in general- a good principle, but there are cases +where you might need that some network can access other in a different VRF. + +The scope of this document is to cover such cases in a dynamic way without the +use of MPLS-LDP. + +General information about L3VPNs can be found in the {ref}`configuration/vrf/index:L3VPN VRFs` chapter. + +## Overview + +Let’s say we have a requirement to have multiple networks. + +- LAN 1 +- LAN 2 +- Management +- Internet + +Both LANs have to be able to route between each other, both will have managed +devices through a dedicated management network and both will need Internet +access yet the LAN2 will need access to some set of outside networks, not all. +The management network will need access to both LANs but cannot have access +to/from the outside. + +This scenario could be a nightmare applying regular routing and might need +filtering in multiple interfaces. + +A simple solution could be using different routing tables, or VRFs +for all the networks so we can keep the routing restrictions. +But for us to route between the different VRFs we would need a cable or a +logical connection between each other: + +- One cable/logical connection between LAN1 and LAN2 +- One cable/logical connection between LAN1 and Internet +- One cable/logical connection between LAN2 and Internet +- One cable/logical connection between LAN1 and Management +- One cable/logical connection between LAN2 and Management + +As we can see this is unpractical. + +To address this scenario we will use to our advantage an extension of the BGP +routing protocol that will help us in the “Export” between VRFs without the +need for MPLS. + +MP-BGP or MultiProtocol BGP introduces two main concepts to solve this +limitation: +\- Route Distinguisher (RD): Is used to distinguish between different VRFs +–called VPNs- inside the BGP Process. The RD is appended to each IPv4 Network +that is advertised into BGP for that VPN making it a unique VPNv4 route. +\- Route Target (RT): This is an extended BGP community append to the VPNv4 route +in the Import/Export process. When a route passes from the VRF routing table +into the BGP process it will add the configured export extended community(ies) +for that VPN. When that route needs to go from BGP into the VRF routing table +will only pass if that given VPN import policy matches any of the appended +community(ies) into that prefix. + +## Topology + +```{image} /_static/images/inter-vrf-routing-vrf-lite.png +:align: center +:alt: Network Topology Diagram +:width: 70% +``` + +### IP Schema + +```{eval-rst} ++----------+------------+----------------+------------------+ +| Device-A | Device-B | IPv4 Network | IPv6 Network | ++----------+------------+----------------+------------------+ +| Core | LAN1 | 10.1.1.0/30 | 2001:db8::/127 | ++----------+------------+----------------+------------------+ +| Core | LAN2 | 172.16.2.0/30 | 2001:db8::2/127 | ++----------+------------+----------------+------------------+ +| Core | Management | 192.168.3.0/30 | 2001:db8::4/127 | ++----------+------------+----------------+------------------+ +| Core | ISP | 10.2.2.0/30 | 2001:db8::6/127 | ++----------+------------+----------------+------------------+ +``` + +### RD & RT Schema + +```{eval-rst} ++------------+-----------+-----------+ +| VRF | RD | RT | ++------------+-----------+-----------+ +| LAN1 | 64496:1 | 64496:1 | ++------------+-----------+-----------+ +| LAN2 | 64496:2 | 64496:2 | ++------------+-----------+-----------+ +| Management | 64496:50 | 64496:50 | ++------------+-----------+-----------+ +| Internet | 64496:100 | 64496:100 | ++------------+-----------+-----------+ +``` + +## Configurations + +:::{note} +We use a static route configuration in between the Core and each +LAN and Management router, and BGP between the Core router and the ISP router +but any dynamic routing protocol can be used. +::: + +### Remote Networks + +The following template configuration can be used in each remote router based +in our topology. + +```none +# Interface Configuration +set interface eth eth<N> address <IP ADDRESS/CIDR> + +# Static default route back to Core +set procotols static route 0.0.0.0/0 next-hop <CORE IP ADDRESS> +``` + +### Core Router + +#### Step 1: VRF and Configurations to remote networks + +- Configuration + +Set the VRF name and Table ID, set interface address and bind it to the VRF. +Last add the static route to the remote network. + +```none +# VRF name and table ID (MANDATORY) +set vrf name <VRF> table <ID> + +# Interface Configuration +set interface eth eth<N> address <IP ADDRESS/CIDR> + +# Assign interface to VRF +set interface eth eth<N> vrf <VRF> + +# Static route to remote Network +set vrf name <VRF> protocols static route <NETWORK/CIDR> next-hop <REMOTE IP ADDRESS> +``` + +- Verification + +Checking the routing table of the VRF should reveal both static and connected +entries active. A PING test between the Core and remote router is a way to +validate connectivity within the VRF. + +```none +# show ip route vrf <VRF> +# show ipv6 route vrf <VRF> + +vyos@Core:~$ show ip route vrf LAN1 +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +VRF LAN1: +S>* 10.0.0.0/24 [1/0] via 10.1.1.2, eth0, weight 1, 00:05:41 +C>* 10.1.1.0/30 is directly connected, eth0, 00:05:44 + +vyos@Core:~$ show ipv6 route vrf LAN1 +Codes: K - kernel route, C - connected, S - static, R - RIPng, + O - OSPFv3, I - IS-IS, B - BGP, N - NHRP, T - Table, + v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +VRF LAN1: +C>* 2001:db8::/127 is directly connected, eth0, 00:18:43 +S>* 2001:db8:0:1::/64 [1/0] via 2001:db8::1, eth0, weight 1, 00:16:03 +C>* fe80::/64 is directly connected, eth0, 00:18:43 + +# ping <DESTINATION> vrf <VRF> + +vyos@Core:~$ ping 10.1.1.2 vrf LAN1 +PING 10.1.1.2 (10.1.1.2) 56(84) bytes of data. +64 bytes from 10.1.1.2: icmp_seq=1 ttl=64 time=1.52 ms +64 bytes from 10.1.1.2: icmp_seq=2 ttl=64 time=0.830 ms +^C +--- 10.1.1.2 ping statistics --- +2 packets transmitted, 2 received, 0% packet loss, time 1002ms +rtt min/avg/max/mdev = 0.830/1.174/1.518/0.344 ms +vyos@Core:~$ ping 10.0.0.1 vrf LAN1 +PING 10.0.0.1 (10.0.0.1) 56(84) bytes of data. +64 bytes from 10.0.0.1: icmp_seq=1 ttl=64 time=0.785 ms +64 bytes from 10.0.0.1: icmp_seq=2 ttl=64 time=0.948 ms +^C +--- 10.0.0.1 ping statistics --- +2 packets transmitted, 2 received, 0% packet loss, time 1002ms +rtt min/avg/max/mdev = 0.785/0.866/0.948/0.081 ms + +vyos@Core:~$ ping 2001:db8:0:1::1 vrf LAN1 +PING 2001:db8:0:1::1(2001:db8:0:1::1) 56 data bytes +64 bytes from 2001:db8:0:1::1: icmp_seq=1 ttl=64 time=3.04 ms +64 bytes from 2001:db8:0:1::1: icmp_seq=2 ttl=64 time=1.04 ms +64 bytes from 2001:db8:0:1::1: icmp_seq=3 ttl=64 time=0.925 ms +^C +--- 2001:db8:0:1::1 ping statistics --- +3 packets transmitted, 3 received, 0% packet loss, time 2004ms +rtt min/avg/max/mdev = 0.925/1.665/3.035/0.969 ms +``` + +#### Step 2: BGP Configuration for VRF-Lite + +- Configuration + +Setting BGP global local-as as well inside the VRF. Redistribute static routes +to inject configured networks into the BGP process but still inside the VRF. + +```none +# set BGP global local-as +set protocols bgp system-as <ASN> + +# set BGP VRF local-as and redistribution +set vrf name <VRF> protocols bgp system-as <ASN> +set vrf name <VRF> protocols bgp address-family <AF IPv4/IPv6> redistribute static +``` + +- Verification + +Check the BGP VRF table and verify if the static routes are injected showing +the correct next-hop information. + +```none +# show ip bgp vrf <VRF> +# show bgp vrf <VRF> ipv6 + +vyos@Core:~$ show ip bgp vrf LAN1 +BGP table version is 3, local router ID is 10.1.1.1, vrf id 8 +Default local pref 100, local AS 64496 +Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, + i internal, r RIB-failure, S Stale, R Removed +Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self +Origin codes: i - IGP, e - EGP, ? - incomplete +RPKI validation codes: V valid, I invalid, N Not found + + Network Next Hop Metric LocPrf Weight Path +*> 10.0.0.0/24 10.1.1.2 0 32768 ? + +vyos@Core# run show bgp vrf LAN1 ipv6 +BGP table version is 13, local router ID is 10.1.1.1, vrf id 8 +Default local pref 100, local AS 64496 +Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, + i internal, r RIB-failure, S Stale, R Removed +Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self +Origin codes: i - IGP, e - EGP, ? - incomplete +RPKI validation codes: V valid, I invalid, N Not found + + Network Next Hop Metric LocPrf Weight Path +*> 2001:db8:0:1::/64 + 2001:db8::1 0 32768 ? +``` + +#### Step 3: VPN Configuration + +- Configuration + +Within the VRF we set the Route-Distinguisher (RD) and Route-Targets (RT), then +we enable the export/import VPN. + +```none +# set Route-distinguisher +set vrf name <VRF> protocols bgp address-family <AF IPv4/IPv6> rd vpn export '<RD>' + +# set route-target for import/export +# Note: RT are a list that can be more than one community between apostrophe +# and separated by blank space. Ex: '<RT:1> <RT:2> <RT:3>' +set vrf name <VRF> protocols bgp address-family <AF IPv4/IPv6> route-target vpn export '<RT:Export>' +set vrf name <VRF> protocols bgp address-family <AF IPv4/IPv6> route-target vpn import '<RT:Import>' + +# Enable VPN export/import under this VRF +set vrf name <VRF> protocols bgp address-family <AF IPv4/IPv6> export vpn +set vrf name <VRF> protocols bgp address-family <AF IPv4/IPv6> import vpn +``` + +A key point to understand is that if we need two VRFs to communicate between +each other EXPORT rt from VRF1 has to be in the IMPORT rt list from VRF2. But +this is only in ONE direction, to complete the communication the EXPORT rt from +VRF2 has to be in the IMPORT rt list from VRF1. + +There are some cases where this is not needed -for example, in some +DDoS appliance- but most inter-vrf routing designs use the above configurations. + +- Verification + +After configured all the VRFs involved in this topology we take a deeper look +at both BGP and Routing table for the VRF LAN1 + +```none +# show ip bgp vrf <VRF> +# show bgp vrf <VRF> ipv6 + +vyos@Core# run show ip bgp vrf LAN1 +BGP table version is 53, local router ID is 10.1.1.1, vrf id 8 +Default local pref 100, local AS 64496 +Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, + i internal, r RIB-failure, S Stale, R Removed +Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self +Origin codes: i - IGP, e - EGP, ? - incomplete +RPKI validation codes: V valid, I invalid, N Not found + + Network Next Hop Metric LocPrf Weight Path +*> 0.0.0.0/0 10.2.2.2@7< 0 64497 i +*> 10.0.0.0/24 10.1.1.2 0 32768 ? +*> 10.2.2.0/30 10.2.2.2@7< 0 0 64497 ? +*> 192.0.2.0/24 10.2.2.2@7< 0 0 64497 ? +*> 192.168.0.0/24 192.168.3.2@11< 0 32768 ? +*> 198.51.100.0/24 10.2.2.2@7< 0 0 64497 ? +*> 203.0.113.0/24 10.2.2.2@7< 0 0 64497 ? + +vyos@Core# run show bgp vrf LAN1 ipv6 +BGP table version is 13, local router ID is 10.1.1.1, vrf id 8 +Default local pref 100, local AS 64496 +Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, + i internal, r RIB-failure, S Stale, R Removed +Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self +Origin codes: i - IGP, e - EGP, ? - incomplete +RPKI validation codes: V valid, I invalid, N Not found + +Network Next Hop Metric LocPrf Weight Path +*> ::/0 fe80::5200:ff:fe02:3@7< + 0 64497 i +*> 2001:db8::6/127 fe80::5200:ff:fe02:3@7< + 0 0 64497 ? +*> 2001:db8:0:1::/64 + 2001:db8::1 0 32768 ? +*> 2001:db8:0:3::/64 + 2001:db8::5@11< 0 32768 ? +*> 2001:db8:1::/48 fe80::5200:ff:fe02:3@7< + 0 0 64497 ? +*> 2001:db8:2::/48 fe80::5200:ff:fe02:3@7< + 0 0 64497 ? +*> 2001:db8:3::/48 fe80::5200:ff:fe02:3@7< + 0 0 64497 ? + + +# show ip route vrf <VRF> +# show ipv6 route vrf <VRF> + +vyos@Core:~$ show ip route vrf LAN1 +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +VRF LAN1: +B>* 0.0.0.0/0 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:00:38 +S>* 10.0.0.0/24 [1/0] via 10.1.1.2, eth0, weight 1, 00:29:57 +C>* 10.1.1.0/30 is directly connected, eth0, 00:29:59 +B 10.2.2.0/30 [20/0] via 10.2.2.2 (vrf Internet) inactive, weight 1, 00:00:38 +B>* 172.16.0.0/24 [20/0] via 172.16.2.2, eth1 (vrf LAN2), weight 1, 00:00:38 +B>* 192.0.2.0/24 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:00:38 +B>* 198.51.100.0/24 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:00:38 +B>* 203.0.113.0/24 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:00:38 + +vyos@Core# run show ipv6 route vrf LAN1 +Codes: K - kernel route, C - connected, S - static, R - RIPng, + O - OSPFv3, I - IS-IS, B - BGP, N - NHRP, T - Table, + v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +VRF LAN1: +B>* ::/0 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:07:50 +C>* 2001:db8::/127 is directly connected, eth0, 05:33:43 +B>* 2001:db8::6/127 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:07:50 +S>* 2001:db8:0:1::/64 [1/0] via 2001:db8::1, eth0, weight 1, 05:31:03 +B>* 2001:db8:0:3::/64 [20/0] via 2001:db8::5, eth2 (vrf Management), weight 1, 00:07:50 +B>* 2001:db8:1::/48 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:07:50 +B>* 2001:db8:2::/48 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:07:50 +B>* 2001:db8:3::/48 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:07:50 +C>* fe80::/64 is directly connected, eth0, 05:33:43 +``` + +As we can see in the BGP table any imported route has been injected with a "@" +followed by the VPN id; In the routing table of the VRF, if the route was +installed, we can see -between round brackets- the exported VRF table. + +#### Step 4: End to End verification + +Now we perform some end-to-end testing + +- From Management to LAN1/LAN2 + +```none +vyos@Management:~$ ping 10.0.0.1 source-address 192.168.0.1 +PING 10.0.0.1 (10.0.0.1) from 192.168.0.1 : 56(84) bytes of data. +64 bytes from 10.0.0.1: icmp_seq=1 ttl=63 time=1.93 ms +64 bytes from 10.0.0.1: icmp_seq=2 ttl=63 time=2.12 ms +64 bytes from 10.0.0.1: icmp_seq=3 ttl=63 time=2.12 ms +^C +--- 10.0.0.1 ping statistics --- +3 packets transmitted, 3 received, 0% packet loss, time 2005ms +rtt min/avg/max/mdev = 1.931/2.056/2.123/0.088 ms +vyos@Management:~$ ping 172.16.0.1 source-address 192.168.0.1 +PING 172.16.0.1 (172.16.0.1) from 192.168.0.1 : 56(84) bytes of data. +64 bytes from 172.16.0.1: icmp_seq=1 ttl=63 time=1.62 ms +64 bytes from 172.16.0.1: icmp_seq=2 ttl=63 time=1.75 ms +^C +--- 172.16.0.1 ping statistics --- +2 packets transmitted, 2 received, 0% packet loss, time 1001ms +rtt min/avg/max/mdev = 1.621/1.686/1.752/0.065 ms +vyos@Management:~$ ping 2001:db8:0:1::1 source-address 2001:db8:0:3::1 +PING 2001:db8:0:1::1(2001:db8:0:1::1) from 2001:db8:0:3::1 : 56 data bytes +64 bytes from 2001:db8:0:1::1: icmp_seq=1 ttl=63 time=2.44 ms +64 bytes from 2001:db8:0:1::1: icmp_seq=2 ttl=63 time=2.40 ms +64 bytes from 2001:db8:0:1::1: icmp_seq=3 ttl=63 time=2.41 ms +^C +--- 2001:db8:0:1::1 ping statistics --- +3 packets transmitted, 3 received, 0% packet loss, time 2003ms +rtt min/avg/max/mdev = 2.399/2.418/2.442/0.017 ms +vyos@Management:~$ ping 2001:db8:0:2::1 source-address 2001:db8:0:3::1 +PING 2001:db8:0:2::1(2001:db8:0:2::1) from 2001:db8:0:3::1 : 56 data bytes +64 bytes from 2001:db8:0:2::1: icmp_seq=1 ttl=63 time=1.66 ms +64 bytes from 2001:db8:0:2::1: icmp_seq=2 ttl=63 time=1.99 ms +64 bytes from 2001:db8:0:2::1: icmp_seq=3 ttl=63 time=1.88 ms +64 bytes from 2001:db8:0:2::1: icmp_seq=4 ttl=63 time=2.32 ms +^C +--- 2001:db8:0:2::1 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 3005ms +rtt min/avg/max/mdev = 1.660/1.960/2.315/0.236 ms +``` + +- From Management to Outside (fails as intended) + +```none +vyos@Management:~$ show ip route +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +S>* 0.0.0.0/0 [1/0] via 192.168.3.1, eth2, weight 1, 00:01:58 +C>* 192.168.0.0/24 is directly connected, dum0, 00:02:05 +C>* 192.168.3.0/30 is directly connected, eth2, 00:02:03 +vyos@Management:~$ ping 192.0.2.1 +PING 192.0.2.1 (192.0.2.1) 56(84) bytes of data. +From 192.168.3.1 icmp_seq=1 Destination Net Unreachable +From 192.168.3.1 icmp_seq=2 Destination Net Unreachable +^C +--- 192.0.2.1 ping statistics --- +2 packets transmitted, 0 received, +2 errors, 100% packet loss, time 1002ms + +vyos@Management:~$ ping 195.51.100.1 +PING 195.51.100.1 (195.51.100.1) 56(84) bytes of data. +From 192.168.3.1 icmp_seq=1 Destination Net Unreachable +From 192.168.3.1 icmp_seq=2 Destination Net Unreachable +From 192.168.3.1 icmp_seq=3 Destination Net Unreachable +^C +--- 195.51.100.1 ping statistics --- +3 packets transmitted, 0 received, +3 errors, 100% packet loss, time 2003ms + +vyos@Management:~$ ping 2001:db8:1::1 +PING 2001:db8:1::1(2001:db8:1::1) 56 data bytes +From 2001:db8::4 icmp_seq=1 Destination unreachable: No route +From 2001:db8::4 icmp_seq=2 Destination unreachable: No route +^C +--- 2001:db8:1::1 ping statistics --- +2 packets transmitted, 0 received, +2 errors, 100% packet loss, time 1002ms + +vyos@Management:~$ ping 2001:db8:2::1 +PING 2001:db8:2::1(2001:db8:2::1) 56 data bytes +From 2001:db8::4 icmp_seq=1 Destination unreachable: No route +From 2001:db8::4 icmp_seq=2 Destination unreachable: No route +^C +--- 2001:db8:2::1 ping statistics --- +2 packets transmitted, 0 received, +2 errors, 100% packet loss, time 1002ms +``` + +- LAN1 to Outside + +```none +vyos@LAN1:~$ ping 192.0.2.1 source-address 10.0.0.1 +PING 192.0.2.1 (192.0.2.1) from 10.0.0.1 : 56(84) bytes of data. +64 bytes from 192.0.2.1: icmp_seq=1 ttl=63 time=1.47 ms +64 bytes from 192.0.2.1: icmp_seq=2 ttl=63 time=1.41 ms +64 bytes from 192.0.2.1: icmp_seq=3 ttl=63 time=1.80 ms +^C +--- 192.0.2.1 ping statistics --- +3 packets transmitted, 3 received, 0% packet loss, time 2004ms +rtt min/avg/max/mdev = 1.414/1.563/1.803/0.171 ms +vyos@LAN1:~$ ping 198.51.100.1 source-address 10.0.0.1 +PING 198.51.100.1 (198.51.100.1) from 10.0.0.1 : 56(84) bytes of data. +64 bytes from 198.51.100.1: icmp_seq=1 ttl=63 time=1.71 ms +64 bytes from 198.51.100.1: icmp_seq=2 ttl=63 time=1.83 ms +^C +--- 198.51.100.1 ping statistics --- +2 packets transmitted, 2 received, 0% packet loss, time 1002ms +rtt min/avg/max/mdev = 1.705/1.766/1.828/0.061 ms +vyos@LAN1:~$ ping 203.0.113.1 source-address 10.0.0.1 +PING 203.0.113.1 (203.0.113.1) from 10.0.0.1 : 56(84) bytes of data. +64 bytes from 203.0.113.1: icmp_seq=1 ttl=63 time=1.25 ms +64 bytes from 203.0.113.1: icmp_seq=2 ttl=63 time=1.88 ms +^C +--- 203.0.113.1 ping statistics --- +2 packets transmitted, 2 received, 0% packet loss, time 1003ms +rtt min/avg/max/mdev = 1.249/1.566/1.884/0.317 ms +vyos@LAN1:~$ ping 2001:db8:1::1 source-address 2001:db8:0:1::1 +PING 2001:db8:1::1(2001:db8:1::1) from 2001:db8:0:1::1 : 56 data bytes +64 bytes from 2001:db8:1::1: icmp_seq=1 ttl=63 time=2.35 ms +64 bytes from 2001:db8:1::1: icmp_seq=2 ttl=63 time=2.29 ms +64 bytes from 2001:db8:1::1: icmp_seq=3 ttl=63 time=2.22 ms +^C +--- 2001:db8:1::1 ping statistics --- +3 packets transmitted, 3 received, 0% packet loss, time 2004ms +rtt min/avg/max/mdev = 2.215/2.285/2.352/0.055 ms +vyos@LAN1:~$ ping 2001:db8:2::1 source-address 2001:db8:0:1::1 +PING 2001:db8:2::1(2001:db8:2::1) from 2001:db8:0:1::1 : 56 data bytes +64 bytes from 2001:db8:2::1: icmp_seq=1 ttl=63 time=1.37 ms +64 bytes from 2001:db8:2::1: icmp_seq=2 ttl=63 time=2.68 ms +64 bytes from 2001:db8:2::1: icmp_seq=3 ttl=63 time=2.00 ms +^C +--- 2001:db8:2::1 ping statistics --- +3 packets transmitted, 3 received, 0% packet loss, time 2003ms +rtt min/avg/max/mdev = 1.367/2.015/2.679/0.535 ms +``` + +:::{note} +we are using "source-address" option cause we are not redistributing +connected interfaces into BGP on the Core router hence there is no comeback +route and ping will fail. +::: + +- LAN1 to LAN2 + +```none +vyos@LAN1:~$ ping 172.16.0.1 source-address 10.0.0.1 +PING 172.16.0.1 (172.16.0.1) from 10.0.0.1 : 56(84) bytes of data. +64 bytes from 172.16.0.1: icmp_seq=1 ttl=63 time=3.00 ms +64 bytes from 172.16.0.1: icmp_seq=2 ttl=63 time=2.20 ms +^C +--- 172.16.0.1 ping statistics --- +2 packets transmitted, 2 received, 0% packet loss, time 1002ms +rtt min/avg/max/mdev = 2.199/2.600/3.001/0.401 ms +vyos@LAN1:~$ ping 2001:db8:0:2::1 source 2001:db8:0:1::1 +PING 2001:db8:0:2::1(2001:db8:0:2::1) from 2001:db8:0:1::1 : 56 data bytes +64 bytes from 2001:db8:0:2::1: icmp_seq=1 ttl=63 time=4.82 ms +64 bytes from 2001:db8:0:2::1: icmp_seq=2 ttl=63 time=1.95 ms +64 bytes from 2001:db8:0:2::1: icmp_seq=3 ttl=63 time=1.98 ms +^C +--- 2001:db8:0:2::1 ping statistics --- +3 packets transmitted, 3 received, 0% packet loss, time 2003ms +rtt min/avg/max/mdev = 1.949/2.915/4.815/1.343 ms +``` + +## Conclusions + +Inter-VRF routing is a well-known solution to address complex routing scenarios +that enable -in a dynamic way- to leak routes between VRFs. Is recommended to +take special consideration while designing route-targets and its application as +it can minimize future interventions while creating a new VRF will automatically +take the desired effect in its propagation. + +## Appendix-A + +### Full configuration from all devices + +- Core + +```none +set interfaces ethernet eth0 address '10.1.1.1/30' +set interfaces ethernet eth0 address '2001:db8::/127' +set interfaces ethernet eth0 vrf 'LAN1' +set interfaces ethernet eth1 address '172.16.2.1/30' +set interfaces ethernet eth1 address '2001:db8::2/127' +set interfaces ethernet eth1 vrf 'LAN2' +set interfaces ethernet eth2 address '192.168.3.1/30' +set interfaces ethernet eth2 address '2001:db8::4/127' +set interfaces ethernet eth2 vrf 'Management' +set interfaces ethernet eth3 address '10.2.2.1/30' +set interfaces ethernet eth3 address '2001:db8::6/127' +set interfaces ethernet eth3 vrf 'Internet' +set protocols bgp address-family ipv4-unicast +set protocols bgp system-as '64496' +set vrf name Internet protocols bgp address-family ipv4-unicast export vpn +set vrf name Internet protocols bgp address-family ipv4-unicast import vpn +set vrf name Internet protocols bgp address-family ipv4-unicast rd vpn export '64496:100' +set vrf name Internet protocols bgp address-family ipv4-unicast route-target vpn export '64496:100' +set vrf name Internet protocols bgp address-family ipv4-unicast route-target vpn import '64496:1 64496:2' +set vrf name Internet protocols bgp address-family ipv6-unicast export vpn +set vrf name Internet protocols bgp address-family ipv6-unicast import vpn +set vrf name Internet protocols bgp address-family ipv6-unicast rd vpn export '64496:100' +set vrf name Internet protocols bgp address-family ipv6-unicast route-target vpn export '64496:100' +set vrf name Internet protocols bgp address-family ipv6-unicast route-target vpn import '64496:1 64496:2' +set vrf name Internet protocols bgp system-as '64496' +set vrf name Internet protocols bgp neighbor 10.2.2.2 address-family ipv4-unicast +set vrf name Internet protocols bgp neighbor 10.2.2.2 remote-as '64497' +set vrf name Internet protocols bgp neighbor 2001:db8::7 address-family ipv6-unicast +set vrf name Internet protocols bgp neighbor 2001:db8::7 remote-as '64497' +set vrf name Internet table '104' +set vrf name LAN1 protocols bgp address-family ipv4-unicast export vpn +set vrf name LAN1 protocols bgp address-family ipv4-unicast import vpn +set vrf name LAN1 protocols bgp address-family ipv4-unicast rd vpn export '64496:1' +set vrf name LAN1 protocols bgp address-family ipv4-unicast redistribute static +set vrf name LAN1 protocols bgp address-family ipv4-unicast route-target vpn export '64496:1' +set vrf name LAN1 protocols bgp address-family ipv4-unicast route-target vpn import '64496:100 64496:50 64496:2' +set vrf name LAN1 protocols bgp address-family ipv6-unicast export vpn +set vrf name LAN1 protocols bgp address-family ipv6-unicast import vpn +set vrf name LAN1 protocols bgp address-family ipv6-unicast rd vpn export '64496:1' +set vrf name LAN1 protocols bgp address-family ipv6-unicast redistribute static +set vrf name LAN1 protocols bgp address-family ipv6-unicast route-target vpn export '64496:1' +set vrf name LAN1 protocols bgp address-family ipv6-unicast route-target vpn import '64496:100 64496:50 64496:2' +set vrf name LAN1 protocols bgp system-as '64496' +set vrf name LAN1 protocols static route 10.0.0.0/24 next-hop 10.1.1.2 +set vrf name LAN1 protocols static route6 2001:db8:0:1::/64 next-hop 2001:db8::1 +set vrf name LAN1 table '101' +set vrf name LAN2 protocols bgp address-family ipv4-unicast export vpn +set vrf name LAN2 protocols bgp address-family ipv4-unicast import vpn +set vrf name LAN2 protocols bgp address-family ipv4-unicast rd vpn export '64496:2' +set vrf name LAN2 protocols bgp address-family ipv4-unicast redistribute static +set vrf name LAN2 protocols bgp address-family ipv4-unicast route-target vpn export '64496:2' +set vrf name LAN2 protocols bgp address-family ipv4-unicast route-target vpn import '64496:100 64496:50 64496:1' +set vrf name LAN2 protocols bgp address-family ipv6-unicast export vpn +set vrf name LAN2 protocols bgp address-family ipv6-unicast import vpn +set vrf name LAN2 protocols bgp address-family ipv6-unicast rd vpn export '64496:2' +set vrf name LAN2 protocols bgp address-family ipv6-unicast redistribute static +set vrf name LAN2 protocols bgp address-family ipv6-unicast route-target vpn export '64496:2' +set vrf name LAN2 protocols bgp address-family ipv6-unicast route-target vpn import '64496:100 64496:50 64496:1' +set vrf name LAN2 protocols bgp system-as '64496' +set vrf name LAN2 protocols static route 172.16.0.0/24 next-hop 172.16.2.2 +set vrf name LAN2 protocols static route6 2001:db8:0:2::/64 next-hop 2001:db8::3 +set vrf name LAN2 table '102' +set vrf name Management protocols bgp address-family ipv4-unicast export vpn +set vrf name Management protocols bgp address-family ipv4-unicast import vpn +set vrf name Management protocols bgp address-family ipv4-unicast rd vpn export '64496:50' +set vrf name Management protocols bgp address-family ipv4-unicast redistribute static +set vrf name Management protocols bgp address-family ipv4-unicast route-target vpn export '64496:50' +set vrf name Management protocols bgp address-family ipv4-unicast route-target vpn import '64496:1 64496:2' +set vrf name Management protocols bgp address-family ipv6-unicast export vpn +set vrf name Management protocols bgp address-family ipv6-unicast import vpn +set vrf name Management protocols bgp address-family ipv6-unicast rd vpn export '64496:50' +set vrf name Management protocols bgp address-family ipv6-unicast redistribute static +set vrf name Management protocols bgp address-family ipv6-unicast route-target vpn export '64496:50' +set vrf name Management protocols bgp address-family ipv6-unicast route-target vpn import '64496:1 64496:2' +set vrf name Management protocols bgp system-as '64496' +set vrf name Management protocols static route 192.168.0.0/24 next-hop 192.168.3.2 +set vrf name Management protocols static route6 2001:db8:0:3::/64 next-hop 2001:db8::5 +set vrf name Management table '103' +``` + +- LAN1 + +```none +set interfaces dummy dum0 address '10.0.0.1/24' +set interfaces dummy dum0 address '2001:db8:0:1::1/64' +set interfaces ethernet eth0 address '10.1.1.2/30' +set interfaces ethernet eth0 address '2001:db8::1/127' +set protocols static route 0.0.0.0/0 next-hop 10.1.1.1 +set protocols static route6 ::/0 next-hop 2001:db8::* +``` + +- LAN2 + +```none +set interfaces dummy dum0 address '172.16.0.1/24' +set interfaces dummy dum0 address '2001:db8:0:2::1/64' +set interfaces ethernet eth0 hw-id '50:00:00:03:00:00' +set interfaces ethernet eth1 address '172.16.2.2/30' +set interfaces ethernet eth1 address '2001:db8::3/127' +set protocols static route 0.0.0.0/0 next-hop 172.16.2.1 +set protocols static route6 ::/0 next-hop 2001:db8::2 +``` + +- Management + +```none +set interfaces dummy dum0 address '192.168.0.1/24' +set interfaces dummy dum0 address '2001:db8:0:3::1/64' +set interfaces ethernet eth2 address '192.168.3.2/30' +set interfaces ethernet eth2 address '2001:db8::5/127' +set protocols static route 0.0.0.0/0 next-hop 192.168.3.1 +set protocols static route6 ::/0 next-hop 2001:db8::4 +``` + +- ISP + +```none +set interfaces dummy dum0 address '192.0.2.1/24' +set interfaces dummy dum0 address '2001:db8:1::1/48' +set interfaces dummy dum1 address '198.51.100.1/24' +set interfaces dummy dum1 address '2001:db8:2::1/48' +set interfaces dummy dum2 address '203.0.113.1/24' +set interfaces dummy dum2 address '2001:db8:3::1/48' +set interfaces ethernet eth3 address '10.2.2.2/30' +set interfaces ethernet eth3 address '2001:db8::7/127' +set protocols bgp address-family ipv4-unicast redistribute connected +set protocols bgp address-family ipv6-unicast redistribute connected +set protocols bgp system-as '64497' +set protocols bgp neighbor 10.2.2.1 address-family ipv4-unicast default-originate +set protocols bgp neighbor 10.2.2.1 remote-as '64496' +set protocols bgp neighbor 2001:db8::6 address-family ipv6-unicast default-originate +set protocols bgp neighbor 2001:db8::6 remote-as '64496' +set protocols static route 0.0.0.0/0 next-hop 10.2.2.1 +set protocols static route6 ::/0 next-hop 2001:db8::6 +``` + +## Appendix-B + +### Route-Filtering + +When importing routes using MP-BGP it is possible to filter a subset of them +before are injected in the BGP table. One of the most common case is to use a +route-map with an prefix-list. + +- Configuration + +We create a prefix-list first and add all the routes we need to. + +```none +# set both ipv4 and ipv6 policies + +set policy prefix-list LAN2-Internet rule 1 action 'permit' +set policy prefix-list LAN2-Internet rule 1 le '24' +set policy prefix-list LAN2-Internet rule 1 prefix '198.51.0.0/16' +set policy prefix-list LAN2-Internet rule 2 action 'permit' +set policy prefix-list LAN2-Internet rule 2 prefix '192.0.2.0/24' +set policy prefix-list LAN2-Internet rule 3 action 'permit' +set policy prefix-list LAN2-Internet rule 3 prefix '192.168.0.0/24' +set policy prefix-list LAN2-Internet rule 4 action 'permit' +set policy prefix-list LAN2-Internet rule 4 prefix '10.0.0.0/24' + +set policy prefix-list6 LAN2-Internet-v6 rule 1 action 'permit' +set policy prefix-list6 LAN2-Internet-v6 rule 1 prefix '2001:db8:1::/48' +set policy prefix-list6 LAN2-Internet-v6 rule 2 action 'permit' +set policy prefix-list6 LAN2-Internet-v6 rule 2 prefix '2001:db8:2::/48' +set policy prefix-list6 LAN2-Internet-v6 rule 3 action 'permit' +set policy prefix-list6 LAN2-Internet-v6 rule 3 prefix '2001:db8:0:3::/64' +set policy prefix-list6 LAN2-Internet-v6 rule 4 action 'permit' +set policy prefix-list6 LAN2-Internet-v6 rule 4 prefix '2001:db8:0:1::/64' +``` + +Then add a route-map and reference to above prefix. Consider that the actions +taken inside the prefix will MATCH the routes that will be affected by the +actions inside the rules of the route-map. + +```none +set policy route-map LAN2-Internet rule 1 action 'permit' +set policy route-map LAN2-Internet rule 1 match ip address prefix-list 'LAN2-Internet' + +set policy route-map LAN2-Internet-v6 rule 1 action 'permit' +set policy route-map LAN2-Internet-v6 rule 1 match ipv6 address prefix-list 'LAN2-Internet-v6' +``` + +We are using a "white list" approach by allowing only what is necessary. In case +that need to implement a "black list" approach then you will need to change the +action in the route-map for a deny BUT you need to add a rule that permits the +rest due to the implicit deny in the route-map. + +Then we need to attach the policy to the BGP process. This needs to be under +the import statement in the vrf we need to filter. + +```none +set vrf name LAN2 protocols bgp address-family ipv4-unicast route-map vpn import 'LAN2-Internet' +set vrf name LAN2 protocols bgp address-family ipv6-unicast route-map vpn import 'LAN2-Internet-v6' +``` + +- Verification + +```none +# show ip route vrf LAN2 + +B>* 10.0.0.0/24 [20/0] via 10.1.1.2, eth0 (vrf LAN1), weight 1, 00:45:28 +S>* 172.16.0.0/24 [1/0] via 172.16.2.2, eth1, weight 1, 00:45:32 +C>* 172.16.2.0/30 is directly connected, eth1, 00:45:39 +B>* 192.0.2.0/24 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:45:24 +B>* 192.168.0.0/24 [20/0] via 192.168.3.2, eth2 (vrf Managment), weight 1, 00:45:27 +B>* 198.51.100.0/24 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:45:24 + +# show ipv6 route vrf LAN2 + +C>* 2001:db8::2/127 is directly connected, eth1, 00:46:26 +B>* 2001:db8:0:1::/64 [20/0] via 2001:db8::1, eth0 (vrf LAN1), weight 1, 00:46:17 +S>* 2001:db8:0:2::/64 [1/0] via 2001:db8::3, eth1, weight 1, 00:46:21 +B>* 2001:db8:0:3::/64 [20/0] via 2001:db8::5, eth2 (vrf Managment), weight 1, 00:46:16 +B>* 2001:db8:1::/48 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:46:13 +B>* 2001:db8:2::/48 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:46:13 +C>* fe80::/64 is directly connected, eth1, 00:46:27 +``` + +As we can see even if both VRF LAN1 and LAN2 has the same import RTs we are able +to select which routes are effectively imported and installed. diff --git a/docs/configexamples/md-ipsec-cisco-policy-based.md b/docs/configexamples/md-ipsec-cisco-policy-based.md new file mode 100644 index 00000000..2a12a252 --- /dev/null +++ b/docs/configexamples/md-ipsec-cisco-policy-based.md @@ -0,0 +1,357 @@ +--- +lastproofread: '2025-06-26' +--- + +(examples-ipsec-cisco-policy-based)= + +# Policy-based Site-to-Site VPN IPsec between VyOS and Cisco + +This document is to describe a basic setup using policy-based +site-to-site VPN IPsec. In this example we use VyOS 1.5 and +Cisco IOS. Cisco initiates IPsec connection only if interesting +traffic present. For stable work we recommend configuring an +initiator role on VyOS side. + +## Network Topology + +```{image} /_static/images/cisco-vpn-ipsec.png +:align: center +:alt: Network Topology Diagram +``` + +## Prerequirements + +**VyOS:** + +```{eval-rst} ++---------+----------------+ +| WAN IP | 10.0.1.2/30 | ++---------+----------------+ +| LAN1 IP | 192.168.0.1/24 | ++---------+----------------+ +| LAN2 IP | 192.168.1.1/24 | ++---------+----------------+ +``` + +**Cisco:** + +```{eval-rst} ++---------+-----------------+ +| WAN IP | 10.0.2.2/30 | ++---------+-----------------+ +| LAN1 IP | 192.168.10.1/24 | ++---------+-----------------+ +| LAN2 IP | 192.168.11.1/24 | ++---------+-----------------+ +``` + +**IKE parameters:** + +```{eval-rst} ++-------------------+---------+ +| Encryption | AES-256 | ++-------------------+---------+ +| HASH | SHA-1 | ++-------------------+---------+ +| Diff-Helman Group | 14 | ++-------------------+---------+ +| Life-Time | 28800 | ++-------------------+---------+ +| IKE Version | 2 | ++-------------------+---------+ +``` + +**IPsec parameters:** + +```{eval-rst} ++------------+---------+ +| Encryption | AES-256 | ++------------+---------+ +| HASH | SHA-256 | ++------------+---------+ +| Life-Time | 3600 | ++------------+---------+ +| PFS | disable | ++------------+---------+ +``` + +**Traffic Selectors** + +: 192.168.0.0/24 \<==> 192.168.10.0/24 + + 192.168.1.0/24 \<==> 192.168.11.0/24 + +**Hosts configuration** + +```{eval-rst} ++--------+--------------+ +| PC1 IP | 192.168.0.2 | ++--------+--------------+ +| PC2 IP | 192.168.1.2 | ++--------+--------------+ +| PC3 IP | 192.168.10.2 | ++--------+--------------+ +| PC4 IP | 192.168.11.2 | ++--------+--------------+ +``` + +## Configuration + +:::{note} +Pfs is disabled in Cisco by default. +::: + +### VyOS + +```none +set interfaces ethernet eth0 address '10.0.1.2/30' +set interfaces ethernet eth1 address '192.168.0.1/24' +set interfaces ethernet eth2 address '192.168.1.1/24' +set protocols static route 0.0.0.0/0 next-hop 10.0.1.1 +set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' +set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' +set vpn ipsec authentication psk AUTH-PSK secret 'dGVzdA==' +set vpn ipsec authentication psk AUTH-PSK secret-type 'base64' +set vpn ipsec esp-group ESP-GROUP lifetime '3600' +set vpn ipsec esp-group ESP-GROUP pfs 'disable' +set vpn ipsec esp-group ESP-GROUP proposal 10 encryption 'aes256' +set vpn ipsec esp-group ESP-GROUP proposal 10 hash 'sha256' +set vpn ipsec ike-group IKE-GROUP close-action 'start' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'restart' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '10' +set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev2' +set vpn ipsec ike-group IKE-GROUP lifetime '28800' +set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' +set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256' +set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' +set vpn ipsec site-to-site peer CISCO authentication local-id '10.0.1.2' +set vpn ipsec site-to-site peer CISCO authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer CISCO authentication remote-id '10.0.2.2' +set vpn ipsec site-to-site peer CISCO connection-type 'initiate' +set vpn ipsec site-to-site peer CISCO default-esp-group 'ESP-GROUP' +set vpn ipsec site-to-site peer CISCO ike-group 'IKE-GROUP' +set vpn ipsec site-to-site peer CISCO local-address '10.0.1.2' +set vpn ipsec site-to-site peer CISCO remote-address '10.0.2.2' +set vpn ipsec site-to-site peer CISCO tunnel 1 local prefix '192.168.0.0/24' +set vpn ipsec site-to-site peer CISCO tunnel 1 remote prefix '192.168.10.0/24' +set vpn ipsec site-to-site peer CISCO tunnel 2 local prefix '192.168.1.0/24' +set vpn ipsec site-to-site peer CISCO tunnel 2 remote prefix '192.168.11.0/24' +``` + +### Cisco + +```none +crypto ikev2 proposal aes-cbc-256-proposal + encryption aes-cbc-256 + integrity sha1 + group 14 +! +crypto ikev2 policy policy1 + match address local 10.0.2.2 + proposal aes-cbc-256-proposal +! +crypto ikev2 keyring keys + peer VyOS + address 10.0.1.2 + pre-shared-key local test + pre-shared-key remote test +! +crypto ikev2 profile IKEv2-profile + match identity remote address 10.0.1.2 255.255.255.255 + authentication remote pre-share + authentication local pre-share + keyring local keys + lifetime 28800 +! +crypto ipsec transform-set TS esp-aes 256 esp-sha256-hmac + mode tunnel +! +crypto map IPSEC-map 10 ipsec-isakmp + set peer 10.0.1.2 + set security-association lifetime seconds 3600 + set transform-set TS + set ikev2-profile IKEv2-profile + match address cryptoacl +! +interface GigabitEthernet0/0 + ip address 10.0.2.2 255.255.255.252 + crypto map IPSEC-map +! +interface GigabitEthernet0/1 + ip address 192.168.10.1 255.255.255.0 +! +interface GigabitEthernet0/2 + ip address 192.168.11.1 255.255.255.0 +! +ip route 0.0.0.0 0.0.0.0 10.0.2.1 +! +ip access-list extended cryptoacl + permit ip 192.168.10.0 0.0.0.255 192.168.0.0 0.0.0.255 + permit ip 192.168.11.0 0.0.0.255 192.168.1.0 0.0.0.255 +``` + +## Monitoring + +### Monitoring on VyOS side + +IKE SAs: + +```none +vyos@vyos:~$ show vpn ike sa +Peer ID / IP Local ID / IP +------------ ------------- +10.0.2.2 10.0.2.2 10.0.1.2 10.0.1.2 + + State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time + ----- ------ ------- ---- --------- ----- ------ ------ + up IKEv2 AES_CBC_256 HMAC_SHA1_96 MODP_2048 no 304 26528 +``` + +IPsec SAs: + +```none +vyos@vyos:~$ show vpn ipsec sa +Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal +-------------- ------- -------- -------------- ---------------- ---------------- ----------- ----------------------------- +CISCO-tunnel-1 up 6m6s 0B/0B 0/0 10.0.2.2 10.0.2.2 AES_CBC_256/HMAC_SHA2_256_128 +CISCO-tunnel-2 up 6m6s 0B/0B 0/0 10.0.2.2 10.0.2.2 AES_CBC_256/HMAC_SHA2_256_128 +``` + +### Monitoring on Cisco side + +IKE SAs: + +```none +Cisco#show crypto ikev2 sa + IPv4 Crypto IKEv2 SA + +Tunnel-id Local Remote fvrf/ivrf Status +1 10.0.2.2/4500 10.0.1.2/4500 none/none READY + Encr: AES-CBC, keysize: 256, PRF: SHA1, Hash: SHA96, DH Grp:14, Auth sign: PSK, Auth verify: PSK + Life/Active Time: 28800/471 sec + + IPv6 Crypto IKEv2 SA +``` + +IPsec SAs: + +```none + Cisco#show crypto ipsec sa + +interface: GigabitEthernet0/0 + Crypto map tag: IPSEC-map, local addr 10.0.2.2 + + protected vrf: (none) + local ident (addr/mask/prot/port): (192.168.11.0/255.255.255.0/0/0) + remote ident (addr/mask/prot/port): (192.168.1.0/255.255.255.0/0/0) + current_peer 10.0.1.2 port 4500 + PERMIT, flags={origin_is_acl,} + #pkts encaps: 0, #pkts encrypt: 0, #pkts digest: 0 + #pkts decaps: 0, #pkts decrypt: 0, #pkts verify: 0 + #pkts compressed: 0, #pkts decompressed: 0 + #pkts not compressed: 0, #pkts compr. failed: 0 + #pkts not decompressed: 0, #pkts decompress failed: 0 + #send errors 0, #recv errors 0 + + local crypto endpt.: 10.0.2.2, remote crypto endpt.: 10.0.1.2 + plaintext mtu 1438, path mtu 1500, ip mtu 1500, ip mtu idb GigabitEthernet0/0 + current outbound spi: 0xC81F83DA(3357508570) + PFS (Y/N): N, DH group: none + + inbound esp sas: + spi: 0x8C63C51E(2355348766) + transform: esp-256-aes esp-sha256-hmac , + in use settings ={Tunnel, } + conn id: 23, flow_id: SW:23, sibling_flags 80000040, crypto map: IPSEC-map + sa timing: remaining key lifetime (k/sec): (4231729/3585) + IV size: 16 bytes + replay detection support: Y + Status: ACTIVE(ACTIVE) + + inbound ah sas: + + inbound pcp sas: + + outbound esp sas: + spi: 0xC81F83DA(3357508570) + transform: esp-256-aes esp-sha256-hmac , + in use settings ={Tunnel, } + conn id: 24, flow_id: SW:24, sibling_flags 80000040, crypto map: IPSEC-map + sa timing: remaining key lifetime (k/sec): (4231729/3585) + IV size: 16 bytes + replay detection support: Y + Status: ACTIVE(ACTIVE) + + outbound ah sas: + + outbound pcp sas: + + protected vrf: (none) + local ident (addr/mask/prot/port): (192.168.10.0/255.255.255.0/0/0) + remote ident (addr/mask/prot/port): (192.168.0.0/255.255.255.0/0/0) + current_peer 10.0.1.2 port 4500 + PERMIT, flags={origin_is_acl,} + #pkts encaps: 0, #pkts encrypt: 0, #pkts digest: 0 + #pkts decaps: 0, #pkts decrypt: 0, #pkts verify: 0 + #pkts compressed: 0, #pkts decompressed: 0 + #pkts not compressed: 0, #pkts compr. failed: 0 + #pkts not decompressed: 0, #pkts decompress failed: 0 + #send errors 0, #recv errors 0 + + local crypto endpt.: 10.0.2.2, remote crypto endpt.: 10.0.1.2 + plaintext mtu 1438, path mtu 1500, ip mtu 1500, ip mtu idb GigabitEthernet0/0 + current outbound spi: 0xC40C7A20(3289152032) + PFS (Y/N): N, DH group: none + + inbound esp sas: + spi: 0x2948B6CB(692631243) + transform: esp-256-aes esp-sha256-hmac , + in use settings ={Tunnel, } + conn id: 21, flow_id: SW:21, sibling_flags 80000040, crypto map: IPSEC-map + sa timing: remaining key lifetime (k/sec): (4194891/3581) + IV size: 16 bytes + replay detection support: Y + Status: ACTIVE(ACTIVE) + + inbound ah sas: + + inbound pcp sas: + + outbound esp sas: + spi: 0xC40C7A20(3289152032) + transform: esp-256-aes esp-sha256-hmac , + in use settings ={Tunnel, } + conn id: 22, flow_id: SW:22, sibling_flags 80000040, crypto map: IPSEC-map + sa timing: remaining key lifetime (k/sec): (4194891/3581) + IV size: 16 bytes + replay detection support: Y + Status: ACTIVE(ACTIVE) + + outbound ah sas: + + outbound pcp sas: +``` + +### Checking Connectivity + +ICMP packets from PC1 to PC3. + +```none +PC1> ping 192.168.10.2 + +84 bytes from 192.168.10.2 icmp_seq=1 ttl=62 time=8.479 ms +84 bytes from 192.168.10.2 icmp_seq=2 ttl=62 time=3.344 ms +84 bytes from 192.168.10.2 icmp_seq=3 ttl=62 time=3.139 ms +84 bytes from 192.168.10.2 icmp_seq=4 ttl=62 time=3.176 ms +84 bytes from 192.168.10.2 icmp_seq=5 ttl=62 time=3.978 ms +``` + +ICMP packets from PC2 to PC4. + +```none +PC2> ping 192.168.11.2 + +84 bytes from 192.168.11.2 icmp_seq=1 ttl=62 time=9.687 ms +84 bytes from 192.168.11.2 icmp_seq=2 ttl=62 time=3.286 ms +84 bytes from 192.168.11.2 icmp_seq=3 ttl=62 time=2.972 ms +``` diff --git a/docs/configexamples/md-ipsec-cisco-route-based.md b/docs/configexamples/md-ipsec-cisco-route-based.md new file mode 100644 index 00000000..abd4fb3e --- /dev/null +++ b/docs/configexamples/md-ipsec-cisco-route-based.md @@ -0,0 +1,402 @@ +--- +lastproofread: '2025-06-26' +--- + +(examples-ipsec-cisco-route-based)= + +# Route-based Site-to-Site VPN IPsec between VyOS and Cisco + +This document is to describe a basic setup using route-based +site-to-site VPN IPsec. In this example we use VyOS 1.5 and +Cisco IOS. Cisco initiates IPsec connection only if interesting +traffic present. For stable work we recommend configuring an +initiator role on VyOS side. OSPF is selected as routing protocol +inside the tunnel. + +## Network Topology + +```{image} /_static/images/cisco-vpn-ipsec.png +:align: center +:alt: Network Topology Diagram +``` + +## Prerequirements + +**VyOS:** + +```{eval-rst} ++---------+----------------+ +| WAN IP | 10.0.1.2/30 | ++---------+----------------+ +| LAN1 IP | 192.168.0.1/24 | ++---------+----------------+ +| LAN2 IP | 192.168.1.1/24 | ++---------+----------------+ +``` + +**Cisco:** + +```{eval-rst} ++---------+-----------------+ +| WAN IP | 10.0.2.2/30 | ++---------+-----------------+ +| LAN1 IP | 192.168.10.1/24 | ++---------+-----------------+ +| LAN2 IP | 192.168.11.1/24 | ++---------+-----------------+ +``` + +**IKE parameters:** + +```{eval-rst} ++-------------------+---------+ +| Encryption | AES-128 | ++-------------------+---------+ +| HASH | SHA-1 | ++-------------------+---------+ +| Diff-Helman Group | 14 | ++-------------------+---------+ +| Life-Time | 28800 | ++-------------------+---------+ +| IKE Version | 1 | ++-------------------+---------+ +``` + +**IPsec parameters:** + +```{eval-rst} ++------------+---------+ +| Encryption | AES-256 | ++------------+---------+ +| HASH | SHA-256 | ++------------+---------+ +| Life-Time | 3600 | ++------------+---------+ +| PFS | disable | ++------------+---------+ +``` + +**Hosts configuration** + +```{eval-rst} ++--------+--------------+ +| PC1 IP | 192.168.0.2 | ++--------+--------------+ +| PC2 IP | 192.168.1.2 | ++--------+--------------+ +| PC3 IP | 192.168.10.2 | ++--------+--------------+ +| PC4 IP | 192.168.11.2 | ++--------+--------------+ +``` + +## Configuration + +:::{note} +Pfs is disabled in Cisco by default. +::: + +### VyOS + +```none +set interfaces ethernet eth0 address '10.0.1.2/30' +set interfaces ethernet eth1 address '192.168.0.1/24' +set interfaces ethernet eth2 address '192.168.1.1/24' +set interfaces vti vti1 address '10.100.100.1/30' +set interfaces vti vti1 mtu '1438' +set protocols ospf area 0 network '10.100.100.0/30' +set protocols ospf area 0 network '192.168.0.0/24' +set protocols ospf area 0 network '192.168.1.0/24' +set protocols ospf interface eth1 passive +set protocols ospf interface eth2 passive +set protocols ospf interface vti1 network 'point-to-point' +set protocols ospf parameters router-id '2.2.2.2' +set protocols static route 0.0.0.0/0 next-hop 10.0.1.1 +set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' +set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' +set vpn ipsec authentication psk AUTH-PSK secret 'dGVzdA==' +set vpn ipsec authentication psk AUTH-PSK secret-type 'base64' +set vpn ipsec esp-group ESP-GROUP lifetime '3600' +set vpn ipsec esp-group ESP-GROUP pfs 'disable' +set vpn ipsec esp-group ESP-GROUP proposal 10 encryption 'aes256' +set vpn ipsec esp-group ESP-GROUP proposal 10 hash 'sha256' +set vpn ipsec ike-group IKE-GROUP close-action 'start' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'restart' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '10' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection timeout '30' +set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev1' +set vpn ipsec ike-group IKE-GROUP lifetime '28800' +set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' +set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes128' +set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' +set vpn ipsec options disable-route-autoinstall +set vpn ipsec site-to-site peer CISCO authentication local-id '10.0.1.2' +set vpn ipsec site-to-site peer CISCO authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer CISCO authentication remote-id '10.0.2.2' +set vpn ipsec site-to-site peer CISCO connection-type 'initiate' +set vpn ipsec site-to-site peer CISCO default-esp-group 'ESP-GROUP' +set vpn ipsec site-to-site peer CISCO ike-group 'IKE-GROUP' +set vpn ipsec site-to-site peer CISCO local-address '10.0.1.2' +set vpn ipsec site-to-site peer CISCO remote-address '10.0.2.2' +set vpn ipsec site-to-site peer CISCO vti bind 'vti1' +``` + +### Cisco + +```none +crypto isakmp policy 10 + encr aes + authentication pre-share + group 14 + lifetime 28800 +crypto isakmp key test address 10.0.1.2 +! +! +crypto ipsec transform-set TS esp-aes 256 esp-sha256-hmac + mode transport +! +crypto ipsec profile IPsec-profile + set transform-set TS +! +! +! +! +! +! +! +interface Loopback0 + ip address 1.1.1.1 255.255.255.255 +! +interface Tunnel10 + ip address 10.100.100.2 255.255.255.252 + ip ospf network point-to-point + tunnel source GigabitEthernet0/0 + tunnel mode ipsec ipv4 + tunnel destination 10.0.1.2 + tunnel protection ipsec profile IPsec-profile +! +interface GigabitEthernet0/0 + ip address 10.0.2.2 255.255.255.252 + duplex auto + speed auto + media-type rj45 +! +interface GigabitEthernet0/1 + ip address 192.168.10.1 255.255.255.0 + duplex auto + speed auto + media-type rj45 +! +interface GigabitEthernet0/2 + ip address 192.168.11.1 255.255.255.0 + duplex auto + speed auto + media-type rj45 +! +router ospf 1 + router-id 1.1.1.1 + passive-interface GigabitEthernet0/1 + passive-interface GigabitEthernet0/2 + network 10.100.100.0 0.0.0.3 area 0 + network 192.168.10.0 0.0.0.255 area 0 + network 192.168.11.0 0.0.0.255 area 0 +! +ip route 0.0.0.0 0.0.0.0 10.0.2.1 +``` + +## Monitoring + +### Monitoring on VyOS side + +IKE SAs: + +```none +vyos@vyos:~$ show vpn ike sa +Peer ID / IP Local ID / IP +------------ ------------- +10.0.2.2 10.0.2.2 10.0.1.2 10.0.1.2 + + State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time + ----- ------ ------- ---- --------- ----- ------ ------ + up IKEv1 AES_CBC_128 HMAC_SHA1_96 MODP_2048 no 8175 18439 +``` + +IPsec SAs: + +```none +vyos@vyos:~$ show vpn ipsec sa +Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal +------------ ------- -------- -------------- ---------------- ---------------- ----------- ----------------------------- +CISCO-vti up 34m59s 17K/14K 224/213 10.0.2.2 10.0.2.2 AES_CBC_256/HMAC_SHA2_256_128 +``` + +OSPF Neighbor Status: + +```none +vyos@vyos:~$ show ip ospf neighbor + +Neighbor ID Pri State Up Time Dead Time Address Interface RXmtL RqstL DBsmL +1.1.1.1 1 Full/- 1h29m37s 39.317s 10.100.100.2 vti1:10.100.100.1 0 0 0 +``` + +Routing Table: + +```none +vyos@vyos:~$ show ip route +Codes: K - kernel route, C - connected, L - local, S - static, + R - RIP, O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, t - Table-Direct, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + + +S>* 0.0.0.0/0 [1/0] via 10.0.1.1, eth0, weight 1, 00:07:54 +C>* 10.0.1.0/30 is directly connected, eth0, weight 1, 00:07:59 +L>* 10.0.1.2/32 is directly connected, eth0, weight 1, 00:07:59 +O 10.100.100.0/30 [110/1] is directly connected, vti1, weight 1, 00:07:50 +C>* 10.100.100.0/30 is directly connected, vti1, weight 1, 00:07:50 +L>* 10.100.100.1/32 is directly connected, vti1, weight 1, 00:07:50 +O 192.168.0.0/24 [110/1] is directly connected, eth1, weight 1, 00:07:54 +C>* 192.168.0.0/24 is directly connected, eth1, weight 1, 00:07:59 +L>* 192.168.0.1/32 is directly connected, eth1, weight 1, 00:07:59 +O 192.168.1.0/24 [110/1] is directly connected, eth2, weight 1, 00:07:54 +C>* 192.168.1.0/24 is directly connected, eth2, weight 1, 00:07:59 +L>* 192.168.1.1/32 is directly connected, eth2, weight 1, 00:07:59 +O>* 192.168.10.0/24 [110/2] via 10.100.100.2, vti1, weight 1, 00:07:34 +O>* 192.168.11.0/24 [110/2] via 10.100.100.2, vti1, weight 1, 00:07:34 +``` + +### Monitoring on Cisco side + +IKE SAs: + +```none +Cisco#show crypto isakmp sa +IPv4 Crypto ISAKMP SA +dst src state conn-id status +10.0.1.2 10.0.2.2 QM_IDLE 1002 ACTIVE + +IPv6 Crypto ISAKMP SA +``` + +IPsec SAs: + +```none +Cisco#show crypto ipsec sa + +interface: Tunnel10 + Crypto map tag: Tunnel10-head-0, local addr 10.0.2.2 + + protected vrf: (none) + local ident (addr/mask/prot/port): (0.0.0.0/0.0.0.0/0/0) + remote ident (addr/mask/prot/port): (0.0.0.0/0.0.0.0/0/0) + current_peer 10.0.1.2 port 500 + PERMIT, flags={origin_is_acl,} + #pkts encaps: 1295, #pkts encrypt: 1295, #pkts digest: 1295 + #pkts decaps: 1238, #pkts decrypt: 1238, #pkts verify: 1238 + #pkts compressed: 0, #pkts decompressed: 0 + #pkts not compressed: 0, #pkts compr. failed: 0 + #pkts not decompressed: 0, #pkts decompress failed: 0 + #send errors 0, #recv errors 0 + + local crypto endpt.: 10.0.2.2, remote crypto endpt.: 10.0.1.2 + plaintext mtu 1438, path mtu 1500, ip mtu 1500, ip mtu idb GigabitEthernet0/0 + current outbound spi: 0xC3E9B307(3286872839) + PFS (Y/N): N, DH group: none + + inbound esp sas: + spi: 0x2740C328(658555688) + transform: esp-256-aes esp-sha256-hmac , + in use settings ={Tunnel, } + conn id: 7, flow_id: SW:7, sibling_flags 80000040, crypto map: Tunnel10-head-0 + sa timing: remaining key lifetime (k/sec): (4173824/1401) + IV size: 16 bytes + replay detection support: Y + Status: ACTIVE(ACTIVE) + + inbound ah sas: + + inbound pcp sas: + + outbound esp sas: + spi: 0xC3E9B307(3286872839) + transform: esp-256-aes esp-sha256-hmac , + in use settings ={Tunnel, } + conn id: 8, flow_id: SW:8, sibling_flags 80000040, crypto map: Tunnel10-head-0 + sa timing: remaining key lifetime (k/sec): (4173819/1401) + IV size: 16 bytes + replay detection support: Y + Status: ACTIVE(ACTIVE) + + outbound ah sas: + + outbound pcp sas: +``` + +OSPF Neighbor Status: + +```none +Cisco# show ip ospf neighbor + +Neighbor ID Pri State Dead Time Address Interface +2.2.2.2 0 FULL/ - 00:00:35 10.100.100.1 Tunnel10 +``` + +Routing Table: + +```none +Cisco#show ip route +Codes: L - local, C - connected, S - static, R - RIP, M - mobile, B - BGP + D - EIGRP, EX - EIGRP external, O - OSPF, IA - OSPF inter area + N1 - OSPF NSSA external type 1, N2 - OSPF NSSA external type 2 + E1 - OSPF external type 1, E2 - OSPF external type 2 + i - IS-IS, su - IS-IS summary, L1 - IS-IS level-1, L2 - IS-IS level-2 + ia - IS-IS inter area, * - candidate default, U - per-user static route + o - ODR, P - periodic downloaded static route, H - NHRP, l - LISP + a - application route + + - replicated route, % - next hop override, p - overrides from PfR + +Gateway of last resort is 10.0.2.1 to network 0.0.0.0 + +S* 0.0.0.0/0 [1/0] via 10.0.2.1 + 1.0.0.0/32 is subnetted, 1 subnets +C 1.1.1.1 is directly connected, Loopback0 + 10.0.0.0/8 is variably subnetted, 4 subnets, 2 masks +C 10.0.2.0/30 is directly connected, GigabitEthernet0/0 +L 10.0.2.2/32 is directly connected, GigabitEthernet0/0 +C 10.100.100.0/30 is directly connected, Tunnel10 +L 10.100.100.2/32 is directly connected, Tunnel10 +O 192.168.0.0/24 [110/1001] via 10.100.100.1, 00:09:36, Tunnel10 +O 192.168.1.0/24 [110/1001] via 10.100.100.1, 00:09:36, Tunnel10 + 192.168.10.0/24 is variably subnetted, 2 subnets, 2 masks +C 192.168.10.0/24 is directly connected, GigabitEthernet0/1 +L 192.168.10.1/32 is directly connected, GigabitEthernet0/1 + 192.168.11.0/24 is variably subnetted, 2 subnets, 2 masks +C 192.168.11.0/24 is directly connected, GigabitEthernet0/2 +L 192.168.11.1/32 is directly connected, GigabitEthernet0/2 +``` + +### Checking Connectivity + +ICMP packets from PC1 to PC3. + +```none +PC1> ping 192.168.10.2 + +84 bytes from 192.168.10.2 icmp_seq=1 ttl=62 time=8.479 ms +84 bytes from 192.168.10.2 icmp_seq=2 ttl=62 time=3.344 ms +84 bytes from 192.168.10.2 icmp_seq=3 ttl=62 time=3.139 ms +84 bytes from 192.168.10.2 icmp_seq=4 ttl=62 time=3.176 ms +84 bytes from 192.168.10.2 icmp_seq=5 ttl=62 time=3.978 ms +``` + +ICMP packets from PC2 to PC4. + +```none +PC2> ping 192.168.11.2 + +84 bytes from 192.168.11.2 icmp_seq=1 ttl=62 time=9.687 ms +84 bytes from 192.168.11.2 icmp_seq=2 ttl=62 time=3.286 ms +84 bytes from 192.168.11.2 icmp_seq=3 ttl=62 time=2.972 ms +``` diff --git a/docs/configexamples/md-ipsec-pa-route-based.md b/docs/configexamples/md-ipsec-pa-route-based.md new file mode 100644 index 00000000..ce21a9d3 --- /dev/null +++ b/docs/configexamples/md-ipsec-pa-route-based.md @@ -0,0 +1,420 @@ +--- +lastproofread: '2025-06-26' +--- + +(examples-ipsec-pa-route-based)= + +# Route-based Site-to-Site VPN IPsec between VyOS and Palo Alto + +This document is to describe a basic setup using route-based +site-to-site VPN IPsec. In this example we use VyOS 1.5 and +PA 11.0.0. OSPF is selected as routing protocol inside the +tunnel. + +Since this example focuses on IPsec configuration it does not +include firewall configuration. + +## Network Topology + +```{image} /_static/images/ipsec-vyos-pa.png +:align: center +:alt: Network Topology Diagram +``` + +## Prerequirements + +**VyOS:** + +```{eval-rst} ++---------+----------------+ +| WAN IP | 10.0.1.2/30 | ++---------+----------------+ +| LAN1 IP | 192.168.0.1/24 | ++---------+----------------+ +| LAN2 IP | 192.168.1.1/24 | ++---------+----------------+ +``` + +**Cisco:** + +```{eval-rst} ++---------+-----------------+ +| WAN IP | 10.0.2.2/30 | ++---------+-----------------+ +| LAN1 IP | 192.168.10.1/24 | ++---------+-----------------+ +| LAN2 IP | 192.168.11.1/24 | ++---------+-----------------+ +``` + +**IKE parameters:** + +```{eval-rst} ++-------------------+---------+ +| Encryption | AES-128 | ++-------------------+---------+ +| HASH | SHA-1 | ++-------------------+---------+ +| Diff-Helman Group | 14 | ++-------------------+---------+ +| Life-Time | 28800 | ++-------------------+---------+ +| IKE Version | 1 | ++-------------------+---------+ +``` + +**IPsec parameters:** + +```{eval-rst} ++------------+---------+ +| Encryption | AES-256 | ++------------+---------+ +| HASH | SHA-256 | ++------------+---------+ +| Life-Time | 3600 | ++------------+---------+ +| PFS | disable | ++------------+---------+ +``` + +**Hosts configuration** + +```{eval-rst} ++--------+--------------+ +| PC1 IP | 192.168.0.2 | ++--------+--------------+ +| PC2 IP | 192.168.1.2 | ++--------+--------------+ +| PC3 IP | 192.168.10.2 | ++--------+--------------+ +| PC4 IP | 192.168.11.2 | ++--------+--------------+ +``` + +## Configuration + +### VyOS + +```none +set interfaces ethernet eth0 address '10.0.1.2/30' +set interfaces ethernet eth1 address '192.168.0.1/24' +set interfaces ethernet eth2 address '192.168.1.1/24' +set interfaces vti vti1 address '10.100.100.1/30' +set interfaces vti vti1 mtu '1438' +set protocols ospf area 0 network '10.100.100.0/30' +set protocols ospf area 0 network '192.168.0.0/24' +set protocols ospf area 0 network '192.168.1.0/24' +set protocols ospf interface eth1 passive +set protocols ospf interface eth2 passive +set protocols ospf interface vti1 network 'point-to-point' +set protocols ospf parameters router-id '2.2.2.2' +set protocols static route 0.0.0.0/0 next-hop 10.0.1.1 +set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' +set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' +set vpn ipsec authentication psk AUTH-PSK secret 'dGVzdA==' +set vpn ipsec authentication psk AUTH-PSK secret-type 'base64' +set vpn ipsec esp-group ESP-GROUP lifetime '3600' +set vpn ipsec esp-group ESP-GROUP pfs 'disable' +set vpn ipsec esp-group ESP-GROUP proposal 10 encryption 'aes256' +set vpn ipsec esp-group ESP-GROUP proposal 10 hash 'sha256' +set vpn ipsec ike-group IKE-GROUP close-action 'start' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'restart' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '10' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection timeout '30' +set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev1' +set vpn ipsec ike-group IKE-GROUP lifetime '28800' +set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' +set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes128' +set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' +set vpn ipsec options disable-route-autoinstall +set vpn ipsec site-to-site peer CISCO authentication local-id '10.0.1.2' +set vpn ipsec site-to-site peer CISCO authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer CISCO authentication remote-id '10.0.2.2' +set vpn ipsec site-to-site peer CISCO connection-type 'initiate' +set vpn ipsec site-to-site peer CISCO default-esp-group 'ESP-GROUP' +set vpn ipsec site-to-site peer CISCO ike-group 'IKE-GROUP' +set vpn ipsec site-to-site peer CISCO local-address '10.0.1.2' +set vpn ipsec site-to-site peer CISCO remote-address '10.0.2.2' +set vpn ipsec site-to-site peer CISCO vti bind 'vti1' +``` + +### Palo Alto + +GUI Configuration: + +: Network -> Network Profiles -> IKE Crypto + + ```{image} /_static/images/PA-IKE-group.png + :align: center + ``` + + Network -> Network Profiles -> IKE Gateways + + ```{image} /_static/images/PA-IKE-GW-1.png + :align: center + ``` + + ```{image} /_static/images/PA-IKE-GW-2.png + :align: center + ``` + + Network -> Network Profiles -> IPSec Crypto + + ```{image} /_static/images/PA-ESP-group.png + :align: center + ``` + + Network -> Interfaces + + ```{image} /_static/images/PA-tunnel-1.png + :align: center + ``` + + ```{image} /_static/images/PA-tunnel-2.png + :align: center + ``` + + ```{image} /_static/images/PA-tunnel-3.png + :align: center + ``` + + Network -> IPSec Tunnels + + ```{image} /_static/images/PA-IPsec-tunnel.png + :align: center + ``` + +CLI configuration with OSPF: + +```none +set network interface ethernet ethernet1/1 layer3 ip 10.0.2.2/30 +set network interface ethernet ethernet1/1 layer3 interface-management-profile Allow +set network interface ethernet ethernet1/2 layer3 ip 192.168.10.1/24 +set network interface ethernet ethernet1/1 layer3 interface-management-profile Allow +set network interface ethernet ethernet1/3 layer3 ip 192.168.11.1/24 +set network interface ethernet ethernet1/1 layer3 interface-management-profile Allow +set network interface tunnel units tunnel.1 ip 10.100.100.2/30 +set network interface tunnel units tunnel.1 interface-management-profile Allow +set network interface tunnel units tunnel.1 mtu 1438 +set network profiles interface-management-profile Allow ping yes +set network ike crypto-profiles ike-crypto-profiles IKE-GROUP hash sha1 +set network ike crypto-profiles ike-crypto-profiles IKE-GROUP dh-group group14 +set network ike crypto-profiles ike-crypto-profiles IKE-GROUP encryption aes-128-cbc +set network ike crypto-profiles ike-crypto-profiles IKE-GROUP lifetime seconds 28800 +set network ike crypto-profiles ipsec-crypto-profiles ESP-GROUP esp authentication sha256 +set network ike crypto-profiles ipsec-crypto-profiles ESP-GROUP esp encryption aes-256-cbc +set network ike crypto-profiles ipsec-crypto-profiles ESP-GROUP lifetime seconds 3600 +set network ike crypto-profiles ipsec-crypto-profiles ESP-GROUP dh-group no-pfs +set network ike gateway VyOS authentication pre-shared-key key test +set network ike gateway VyOS protocol ikev1 dpd enable yes +set network ike gateway VyOS protocol ikev1 exchange-mode main +set network ike gateway VyOS protocol ikev1 ike-crypto-profile IKE-GROUP +set network ike gateway VyOS protocol ikev2 dpd enable yes +set network ike gateway VyOS protocol version ikev1 +set network ike gateway VyOS protocol-common nat-traversal enable yes +set network ike gateway VyOS protocol-common fragmentation enable no +set network ike gateway VyOS protocol-common passive-mode yes +set network ike gateway VyOS local-address interface ethernet1/1 +set network ike gateway VyOS peer-address ip 10.0.1.2 +set network ike gateway VyOS local-id id 10.0.2.2 +set network ike gateway VyOS local-id type ipaddr +set network ike gateway VyOS peer-id id 10.0.1.2 +set network ike gateway VyOS peer-id type ipaddr +set network tunnel ipsec VyOS-tunnel auto-key ike-gateway VyOS +set network tunnel ipsec VyOS-tunnel auto-key ipsec-crypto-profile ESP-GROUP +set network tunnel ipsec VyOS-tunnel tunnel-monitor enable no +set network tunnel ipsec VyOS-tunnel tunnel-interface tunnel.1 +set network tunnel ipsec VyOS-tunnel anti-replay no +set network virtual-router default protocol ospf enable yes +set network virtual-router default protocol ospf area 0.0.0.0 type normal +set network virtual-router default protocol ospf area 0.0.0.0 interface tunnel.1 enable yes +set network virtual-router default protocol ospf area 0.0.0.0 interface tunnel.1 passive no +set network virtual-router default protocol ospf area 0.0.0.0 interface tunnel.1 link-type p2p +set network virtual-router default protocol ospf area 0.0.0.0 interface ethernet1/2 enable yes +set network virtual-router default protocol ospf area 0.0.0.0 interface ethernet1/2 passive yes +set network virtual-router default protocol ospf area 0.0.0.0 interface ethernet1/2 link-type broadcast +set network virtual-router default protocol ospf area 0.0.0.0 interface ethernet1/3 enable yes +set network virtual-router default protocol ospf area 0.0.0.0 interface ethernet1/3 passive yes +set network virtual-router default protocol ospf area 0.0.0.0 interface ethernet1/3 link-type broadcast +set network virtual-router default protocol ospf router-id 1.1.1.1 +set network virtual-router default interface [ ethernet1/1 ethernet1/2 ethernet1/3 tunnel.1 ] +``` + +## Monitoring + +### Monitoring on VyOS side + +IKE SAs: + +```none +vyos@vyos:~$ show vpn ike sa +Peer ID / IP Local ID / IP +------------ ------------- +10.0.2.2 10.0.2.2 10.0.1.2 10.0.1.2 + + State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time + ----- ------ ------- ---- --------- ----- ------ ------ + up IKEv1 AES_CBC_128 HMAC_SHA1_96 MODP_2048 no 1372 25802 +``` + +IPsec SAs: + +```none +vyos@vyos:~$ show vpn ipsec sa +Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal +------------ ------- -------- -------------- ---------------- ---------------- ----------- ----------------------------- +PA-vti up 23m27s 9K/10K 149/151 10.0.2.2 10.0.2.2 AES_CBC_256/HMAC_SHA2_256_128 +``` + +OSPF Neighbor Status: + +```none +vyos@vyos:~$ show ip ospf neighbor + +Neighbor ID Pri State Up Time Dead Time Address Interface RXmtL RqstL DBsmL +1.1.1.1 1 Full/- 23m56s 37.948s 10.100.100.2 vti1:10.100.100.1 0 0 0 +``` + +Routing Table: + +```none +vyos@vyos:~$ show ip route +Codes: K - kernel route, C - connected, L - local, S - static, + R - RIP, O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, t - Table-Direct, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +S>* 0.0.0.0/0 [1/0] via 10.0.1.1, eth0, weight 1, 00:27:30 +C>* 10.0.1.0/30 is directly connected, eth0, weight 1, 00:27:34 +L>* 10.0.1.2/32 is directly connected, eth0, weight 1, 00:27:34 +O 10.100.100.0/30 [110/1] is directly connected, vti1, weight 1, 00:24:34 +C>* 10.100.100.0/30 is directly connected, vti1, weight 1, 00:24:34 +L>* 10.100.100.1/32 is directly connected, vti1, weight 1, 00:24:34 +O 192.168.0.0/24 [110/1] is directly connected, eth1, weight 1, 00:27:29 +C>* 192.168.0.0/24 is directly connected, eth1, weight 1, 00:27:34 +L>* 192.168.0.1/32 is directly connected, eth1, weight 1, 00:27:34 +O 192.168.1.0/24 [110/1] is directly connected, eth2, weight 1, 00:27:29 +C>* 192.168.1.0/24 is directly connected, eth2, weight 1, 00:27:34 +L>* 192.168.1.1/32 is directly connected, eth2, weight 1, 00:27:34 +O>* 192.168.10.0/24 [110/11] via 10.100.100.2, vti1, weight 1, 00:24:19 +O>* 192.168.11.0/24 [110/11] via 10.100.100.2, vti1, weight 1, 00:24:19 +``` + +### Monitoring on Cisco side + +IKE SAs: + +```none +admin@PA-VM> show vpn ike-sa + +IKEv1 phase-1 SAs +GwID/client IP Peer-Address Gateway Name Role Mode Algorithm Established Expiration V ST Xt Phase2 +-------------- ------------ ------------ ---- ---- --------- ----------- ---------- - -- -- ------ +1 10.0.1.2 VyOS Resp Main PSK/DH14/A128/SHA1 Jul.31 01:35:00 Jul.31 09:35:00 v1 13 1 1 + +Show IKEv1 IKE SA: Total 1 gateways found. 1 ike sa found. + + +IKEv1 phase-2 SAs +Gateway Name TnID Tunnel GwID/IP Role Algorithm SPI(in) SPI(out) MsgID ST Xt +------------ ---- ------ ------- ---- --------- ------- -------- ----- -- -- +VyOS 1 VyOS-tunnel 1 Resp ESP/ /tunl/SHA2 8827A3D9 C204F4FA BD202829 9 1 + +Show IKEv1 phase2 SA: Total 1 gateways found. 1 ike sa found. + + +There is no IKEv2 SA found. +``` + +IPsec SAs: + +```none +admin@PA-VM> show vpn ipsec-sa + +GwID/client IP TnID Peer-Address Tunnel(Gateway) Algorithm SPI(in) SPI(out) life(Sec/KB) remain-time(Sec) +-------------- ---- ------------ --------------- --------- ------- -------- ------------ ---------------- +1 1 10.0.1.2 VyOS-tunnel(VyOS) ESP/A256/SHA256 8827A3D9 C204F4FA 3600/Unlimited 2733 + +Show IPSec SA: Total 1 tunnels found. 1 ipsec sa found. +``` + +OSPF Neighbor Status: + +```none +admin@PA-VM> show routing protocol ospf neighbor + + Options: 0x80:reserved, O:Opaq-LSA capability, DC:demand circuits, EA:Ext-Attr LSA capability, + N/P:NSSA option, MC:multicase, E:AS external LSA capability, T:TOS capability + ========== + virtual router: default + neighbor address: 10.100.100.1 + local address binding: 0.0.0.0 + type: dynamic + status: full + neighbor router ID: 2.2.2.2 + area id: 0.0.0.0 + neighbor priority: 1 + lifetime remain: 32 + messages pending: 0 + LSA request pending: 0 + options: 0x02: E + hello suppressed: no + restart helper status: not helping + restart helper time remaining: 0 + restart helper exit reason: none +``` + +Routing Table: + +```none +admin@PA-VM> show routing route + +flags: A:active, ?:loose, C:connect, H:host, S:static, ~:internal, R:rip, O:ospf, B:bgp, + Oi:ospf intra-area, Oo:ospf inter-area, O1:ospf ext-type-1, O2:ospf ext-type-2, E:ecmp, M:multicast + + +VIRTUAL ROUTER: default (id 1) + ========== +destination nexthop metric flags age interface next-AS +0.0.0.0/0 10.0.2.1 10 A S ethernet1/1 +10.0.2.0/30 10.0.2.2 0 A C ethernet1/1 +10.0.2.2/32 0.0.0.0 0 A H +10.100.100.0/30 0.0.0.0 10 Oi 1273 tunnel.1 +10.100.100.0/30 10.100.100.2 0 A C tunnel.1 +10.100.100.2/32 0.0.0.0 0 A H +192.168.0.0/24 10.100.100.1 11 A Oi 1253 tunnel.1 +192.168.1.0/24 10.100.100.1 11 A Oi 1253 tunnel.1 +192.168.10.0/24 0.0.0.0 10 Oi 1273 ethernet1/2 +192.168.10.0/24 192.168.10.1 0 A C ethernet1/2 +192.168.10.1/32 0.0.0.0 0 A H +192.168.11.0/24 0.0.0.0 10 Oi 1273 ethernet1/3 +192.168.11.0/24 192.168.11.1 0 A C ethernet1/3 +192.168.11.1/32 0.0.0.0 0 A H +total routes shown: 14 +``` + +### Checking Connectivity + +ICMP packets from PC1 to PC3. + +```none +PC1> ping 192.168.10.2 + +84 bytes from 192.168.10.2 icmp_seq=1 ttl=62 time=8.479 ms +84 bytes from 192.168.10.2 icmp_seq=2 ttl=62 time=3.344 ms +84 bytes from 192.168.10.2 icmp_seq=3 ttl=62 time=3.139 ms +84 bytes from 192.168.10.2 icmp_seq=4 ttl=62 time=3.176 ms +84 bytes from 192.168.10.2 icmp_seq=5 ttl=62 time=3.978 ms +``` + +ICMP packets from PC2 to PC4. + +```none +PC2> ping 192.168.11.2 + +84 bytes from 192.168.11.2 icmp_seq=1 ttl=62 time=9.687 ms +84 bytes from 192.168.11.2 icmp_seq=2 ttl=62 time=3.286 ms +84 bytes from 192.168.11.2 icmp_seq=3 ttl=62 time=2.972 ms +``` diff --git a/docs/configexamples/md-l3vpn-hub-and-spoke.md b/docs/configexamples/md-l3vpn-hub-and-spoke.md new file mode 100644 index 00000000..bdd62ada --- /dev/null +++ b/docs/configexamples/md-l3vpn-hub-and-spoke.md @@ -0,0 +1,1094 @@ +# L3VPN for Hub-and-Spoke connectivity with VyOS + +IP/MPLS technology is widely used by various service providers and large +enterprises in order to achieve better network scalability, manageability +and flexibility. It also provides the possibility to deliver different +services for the customers in a seamless manner. +Layer 3 VPN (L3VPN) is a type of VPN mode that is built and delivered +through OSI layer 3 networking technologies. Often the border gateway +protocol (BGP) is used to send and receive VPN-related data that is +responsible for the control plane. L3VPN utilizes virtual routing and +forwarding (VRF) techniques to receive and deliver user data as well as +separate data planes of the end-users. It is built using a combination of +IP- and MPLS-based information. Generally, L3VPNs are used to send data +on back-end VPN infrastructures, such as for VPN connections between data +centres, HQs and branches. + +An L3VPN consists of multiple access links, multiple VPN routing and +forwarding (VRF) tables, and multiple MPLS paths or multiple P2MP LSPs. +An L3VPN can be configured to connect two or more customer sites. +In hub-and-spoke MPLS L3VPN environments, the spoke routers need to have +unique Route Distinguishers (RDs). In order to use the hub site as a +transit point for connectivity in such an environment, the spoke sites +export their routes to the hub. Spokes can talk to hubs, but never have +direct paths to other spokes. All traffic between spokes is controlled +and delivered over the hub site. + +To deploy a Layer3 VPN with MPLS on VyOS, we should meet a couple +requirements in order to properly implement the solution. +We'll use the following nodes in our LAB environment: + +- 2 x Route reflectors (VyOS-RRx) +- 4 x Provider routers (VyOS-Px) +- 3 x Provider Edge (VyOs-PEx) +- 3 x Customer Edge (VyOS-CEx) + +The following software was used in the creation of this document: + +- Operating system: VyOS +- Version: 1.4-rolling-202110310317 +- Image name: vyos-1.4-rolling-202110310317-amd64.iso + +**NOTE:** VyOS Router (tested with VyOS 1.4-rolling-202110310317) +– The configurations below are specifically for VyOS 1.4.x. + +General information can be found in the {ref}`configuration/vrf/index:L3VPN VRFs` chapter. + +## Topology + +```{image} /_static/images/L3VPN_hub_and_spoke.png +:align: center +:alt: Network Topology Diagram +:width: 80% +``` + +## How does it work? + +As we know the main assumption of L3VPN “Hub and Spoke” is, that the traffic +between spokes have to pass via hub, in our scenario VyOS-PE2 is the Hub PE +and the VyOS-CE1-HUB is the central customer office device that is responsible +for controlling access between all spokes and announcing its network prefixes +(10.0.0.100/32). VyOS-PE2 has the main VRF (its name is BLUE_HUB), its +own Route-Distinguisher(RD) and route-target import/export lists. +Multiprotocol-BGP(MP-BGP) delivers L3VPN related control-plane information to +the nodes across network where PEs Spokes import the route-target 60535:1030 +(this is export route-target of vrf BLUE_HUB) and export its own route-target +60535:1011(this is vrf BLUE_SPOKE export route-target). Therefore, the +Customer edge nodes can only learn the network prefixes of the HUB site +[10.0.0.100/32]. For this example VyOS-CE1 has network prefixes +[10.0.0.80/32] / VyOS-CE2 has network prefixes [10.0.0.90/32]. +Route-Reflector devices VyOS-RR1 and VyOS-RR2 are used to simplify network +routes exchange and minimize iBGP peerings between devices. + +L3VPN configuration parameters table: + +```{eval-rst} ++----------+-------+------------+-----------------+-------------+-------------+ +| Node | Role | VRF | RD | RT import | RT export | ++----------+-------+------------+-----------------+-------------+-------------+ +| VyOS-PE2 | Hub | BLUE_HUB | 10.80.80.1:1011 | 65035:1011 | 65035:1030 | +| | | | | 65035:1030 | | ++----------+-------+------------+-----------------+-------------+-------------+ +| VyOS-PE1 | Spoke | BLUE_SPOKE | 10.50.50.1:1011 | 65035:1030 | 65035:1011 | ++----------+-------+------------+-----------------+-------------+-------------+ +| VyOS-PE3 | Spoke | BLUE_SPOKE | 10.60.60.1:1011 | 65035:1030 | 65035:1011 | ++----------+-------+------------+-----------------+-------------+-------------+ +``` + +## Configuration + +### Step-1: Configuring IGP and enabling MPLS LDP + +At the first step we need to configure the IP/MPLS backbone network using OSPF +as IGP protocol and LDP as label-switching protocol for the base connectivity +between **P** (rovider), **P** (rovider) **E** (dge) and **R** (oute) **R** +(eflector) nodes: + +- VyOS-P1: + +```none +# interfaces +set interfaces dummy dum10 address '10.0.0.3/32' +set interfaces ethernet eth0 address '172.16.30.1/24' +set interfaces ethernet eth1 address '172.16.40.1/24' +set interfaces ethernet eth2 address '172.16.90.1/24' +set interfaces ethernet eth3 address '172.16.10.1/24' +set interfaces ethernet eth5 address '172.16.100.1/24' + +# protocols ospf+ldp +set protocols mpls interface 'eth1' +set protocols mpls interface 'eth2' +set protocols mpls interface 'eth3' +set protocols mpls interface 'eth5' +set protocols mpls interface 'eth0' +set protocols mpls ldp discovery transport-ipv4-address '10.0.0.3' +set protocols mpls ldp interface 'eth0' +set protocols mpls ldp interface 'eth1' +set protocols mpls ldp interface 'eth2' +set protocols mpls ldp interface 'eth3' +set protocols mpls ldp interface 'eth5' +set protocols mpls ldp router-id '10.0.0.3' +set protocols ospf area 0 network '0.0.0.0/0' +set protocols ospf parameters abr-type 'cisco' +set protocols ospf parameters router-id '10.0.0.3 +``` + +- VyOS-P2: + +```none +# interfaces +set interfaces dummy dum10 address '10.0.0.4/32' +set interfaces ethernet eth0 address '172.16.30.2/24' +set interfaces ethernet eth1 address '172.16.20.1/24' +set interfaces ethernet eth2 address '172.16.120.1/24' +set interfaces ethernet eth3 address '172.16.60.1/24' + +# protocols ospf+ldp +set protocols mpls interface 'eth1' +set protocols mpls interface 'eth2' +set protocols mpls interface 'eth3' +set protocols mpls interface 'eth0' +set protocols mpls ldp discovery transport-ipv4-address '10.0.0.4' +set protocols mpls ldp interface 'eth0' +set protocols mpls ldp interface 'eth1' +set protocols mpls ldp interface 'eth2' +set protocols mpls ldp interface 'eth3' +set protocols mpls ldp router-id '10.0.0.4' +set protocols ospf area 0 network '0.0.0.0/0' +set protocols ospf parameters abr-type 'cisco' +set protocols ospf parameters router-id '10.0.0.4' +``` + +- VyOS-P3: + +```none +# interfaces +set interfaces dummy dum10 address '10.0.0.5/32' +set interfaces ethernet eth0 address '172.16.110.1/24' +set interfaces ethernet eth1 address '172.16.40.2/24' +set interfaces ethernet eth2 address '172.16.50.1/24' +set interfaces ethernet eth3 address '172.16.70.1/24' + +# protocols ospf + ldp +set protocols mpls interface 'eth1' +set protocols mpls interface 'eth2' +set protocols mpls interface 'eth3' +set protocols mpls interface 'eth0' +set protocols mpls ldp discovery transport-ipv4-address '10.0.0.5' +set protocols mpls ldp interface 'eth0' +set protocols mpls ldp interface 'eth1' +set protocols mpls ldp interface 'eth2' +set protocols mpls ldp interface 'eth3' +set protocols mpls ldp router-id '10.0.0.5' +set protocols ospf area 0 network '0.0.0.0/0' +set protocols ospf parameters abr-type 'cisco' +set protocols ospf parameters router-id '10.0.0.5' +``` + +- VyOS-P4: + +```none +# interfaces +set interfaces dummy dum10 address '10.0.0.6/32' +set interfaces ethernet eth0 address '172.16.80.2/24' +set interfaces ethernet eth1 address '172.16.130.1/24' +set interfaces ethernet eth2 address '172.16.50.2/24' +set interfaces ethernet eth3 address '172.16.60.2/24' +set interfaces ethernet eth5 address '172.16.140.1/24' + + +# protocols ospf + ldp +set protocols mpls interface 'eth1' +set protocols mpls interface 'eth2' +set protocols mpls interface 'eth3' +set protocols mpls interface 'eth0' +set protocols mpls interface 'eth5' +set protocols mpls ldp discovery transport-ipv4-address '10.0.0.6' +set protocols mpls ldp interface 'eth0' +set protocols mpls ldp interface 'eth1' +set protocols mpls ldp interface 'eth2' +set protocols mpls ldp interface 'eth3' +set protocols mpls ldp interface 'eth5' +set protocols mpls ldp router-id '10.0.0.6' +set protocols ospf area 0 network '0.0.0.0/0' +set protocols ospf parameters abr-type 'cisco' +set protocols ospf parameters router-id '10.0.0.6' +``` + +- VyOS-PE1: + +```none +# interfaces +set interfaces dummy dum10 address '10.0.0.7/32' +set interfaces ethernet eth0 address '172.16.90.2/24' + +# protocols ospf + ldp +set protocols mpls interface 'eth0' +set protocols mpls ldp discovery transport-ipv4-address '10.0.0.7' +set protocols mpls ldp interface 'eth0' +set protocols mpls ldp router-id '10.0.0.7' +set protocols ospf area 0 network '0.0.0.0/0' +set protocols ospf parameters abr-type 'cisco' +set protocols ospf parameters router-id '10.0.0.7' +``` + +- VyOS-PE2: + +```none +# interfaces +set interfaces dummy dum10 address '10.0.0.8/32' +set interfaces ethernet eth0 address '172.16.110.2/24' +set interfaces ethernet eth1 address '172.16.100.2/24' +set interfaces ethernet eth2 address '172.16.80.1/24' + +# protocols ospf + ldp +set protocols mpls interface 'eth0' +set protocols mpls interface 'eth1' +set protocols mpls ldp discovery transport-ipv4-address '10.0.0.8' +set protocols mpls ldp interface 'eth0' +set protocols mpls ldp interface 'eth1' +set protocols mpls ldp router-id '10.0.0.8' +set protocols ospf area 0 network '0.0.0.0/0' +set protocols ospf parameters abr-type 'cisco' +set protocols ospf parameters router-id '10.0.0.8' +``` + +- VyOS-PE3: + +```none +# interfaces +set interfaces dummy dum10 address '10.0.0.10/32' +set interfaces ethernet eth0 address '172.16.140.2/24' + +# protocols ospf + ldp +set protocols mpls interface 'eth0' +set protocols mpls ldp discovery transport-ipv4-address '10.0.0.10' +set protocols mpls ldp interface 'eth0' +set protocols mpls ldp router-id '10.0.0.10' +set protocols ospf area 0 network '0.0.0.0/0' +set protocols ospf parameters abr-type 'cisco' +set protocols ospf parameters router-id '10.0.0.10' +``` + +- VyOS-RR1: + +```none +# interfaces +set interfaces ethernet eth1 address '172.16.20.2/24' +set interfaces ethernet eth2 address '172.16.10.2/24' +set interfaces dummy dum10 address '10.0.0.1/32' + +# protocols ospf + ldp +set protocols mpls interface 'eth1' +set protocols mpls interface 'eth2' +set protocols mpls ldp discovery transport-ipv4-address '10.0.0.1' +set protocols mpls ldp interface 'eth1' +set protocols mpls ldp interface 'eth2' +set protocols mpls ldp router-id '10.0.0.1' +set protocols ospf area 0 network '0.0.0.0/0' +set protocols ospf parameters abr-type 'cisco' +set protocols ospf parameters router-id '10.0.0.1' +``` + +- VyOS-RR2: + +```none +# interfaces +set interfaces ethernet eth0 address '172.16.80.1/24' +set interfaces ethernet eth1 address '172.16.70.2/24' +set interfaces dummy dum10 address '10.0.0.2/32' + +# protocols ospf + ldp +set protocols mpls interface 'eth0' +set protocols mpls interface 'eth1' +set protocols mpls ldp discovery transport-ipv4-address '10.0.0.2' +set protocols mpls ldp interface 'eth1' +set protocols mpls ldp interface 'eth0' +set protocols mpls ldp router-id '10.0.0.2' +set protocols ospf area 0 network '0.0.0.0/0' +set protocols ospf parameters abr-type 'cisco' +set protocols ospf parameters router-id '10.0.0.2' +``` + +### Step-2: Configuring iBGP for L3VPN control-plane + +At this step we are going to enable iBGP protocol on MPLS nodes and +Route Reflectors (two routers for redundancy) that will deliver IPv4 +VPN (L3VPN) routes between them: + +- VyOS-RR1: + +```none +set protocols bgp system-as '65001' +set protocols bgp neighbor 10.0.0.7 address-family ipv4-vpn route-reflector-client +set protocols bgp neighbor 10.0.0.7 peer-group 'RR_VPNv4' +set protocols bgp neighbor 10.0.0.8 address-family ipv4-vpn route-reflector-client +set protocols bgp neighbor 10.0.0.8 peer-group 'RR_VPNv4' +set protocols bgp neighbor 10.0.0.10 address-family ipv4-vpn route-reflector-client +set protocols bgp neighbor 10.0.0.10 peer-group 'RR_VPNv4' +set protocols bgp parameters cluster-id '10.0.0.1' +set protocols bgp parameters log-neighbor-changes +set protocols bgp parameters router-id '10.0.0.1' +set protocols bgp peer-group RR_VPNv4 remote-as '65001' +set protocols bgp peer-group RR_VPNv4 update-source 'dum10' +``` + +- VyOS-RR2: + +```none +set protocols bgp system-as '65001' +set protocols bgp neighbor 10.0.0.7 address-family ipv4-vpn route-reflector-client +set protocols bgp neighbor 10.0.0.7 peer-group 'RR_VPNv4' +set protocols bgp neighbor 10.0.0.8 address-family ipv4-vpn route-reflector-client +set protocols bgp neighbor 10.0.0.8 peer-group 'RR_VPNv4' +set protocols bgp neighbor 10.0.0.10 address-family ipv4-vpn route-reflector-client +set protocols bgp neighbor 10.0.0.10 peer-group 'RR_VPNv4' +set protocols bgp parameters cluster-id '10.0.0.1' +set protocols bgp parameters log-neighbor-changes +set protocols bgp parameters router-id '10.0.0.2' +set protocols bgp peer-group RR_VPNv4 remote-as '65001' +set protocols bgp peer-group RR_VPNv4 update-source 'dum10' +``` + +- VyOS-PE1: + +```none +set protocols bgp system-as '65001' +set protocols bgp neighbor 10.0.0.1 address-family ipv4-vpn nexthop-self +set protocols bgp neighbor 10.0.0.1 peer-group 'RR_VPNv4' +set protocols bgp neighbor 10.0.0.2 address-family ipv4-vpn nexthop-self +set protocols bgp neighbor 10.0.0.2 peer-group 'RR_VPNv4' +set protocols bgp parameters log-neighbor-changes +set protocols bgp parameters router-id '10.0.0.7' +set protocols bgp peer-group RR_VPNv4 remote-as '65001' +set protocols bgp peer-group RR_VPNv4 update-source 'dum10' +``` + +- VyOS-PE2: + +```none +set protocols bgp system-as '65001' +set protocols bgp neighbor 10.0.0.1 address-family ipv4-vpn nexthop-self +set protocols bgp neighbor 10.0.0.1 peer-group 'RR_VPNv4' +set protocols bgp neighbor 10.0.0.2 address-family ipv4-vpn nexthop-self +set protocols bgp neighbor 10.0.0.2 peer-group 'RR_VPNv4' +set protocols bgp parameters log-neighbor-changes +set protocols bgp parameters router-id '10.0.0.8' +set protocols bgp peer-group RR_VPNv4 remote-as '65001' +set protocols bgp peer-group RR_VPNv4 update-source 'dum10' +``` + +- VyOS-PE3: + +```none +set protocols bgp system-as '65001' +set protocols bgp neighbor 10.0.0.1 address-family ipv4-vpn nexthop-self +set protocols bgp neighbor 10.0.0.1 peer-group 'RR_VPNv4' +set protocols bgp neighbor 10.0.0.2 address-family ipv4-vpn nexthop-self +set protocols bgp neighbor 10.0.0.2 peer-group 'RR_VPNv4' +set protocols bgp parameters log-neighbor-changes +set protocols bgp parameters router-id '10.0.0.10' +set protocols bgp peer-group RR_VPNv4 remote-as '65001' +set protocols bgp peer-group RR_VPNv4 update-source 'dum10' +``` + +### Step-3: Configuring L3VPN VRFs on PE nodes + +This section provides configuration steps for setting up VRFs on our +PE nodes including CE facing interfaces, BGP, rd and route-target +import/export based on the pre-defined parameters. + +- VyOS-PE1: + +```none +# VRF settings +set vrf name BLUE_SPOKE table '200' +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast export vpn +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast import vpn +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast label vpn export 'auto' +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast network 10.50.50.0/24 +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast rd vpn export '10.50.50.1:1011' +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast redistribute connected +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast route-target vpn export '65035:1011' +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast route-target vpn import '65035:1030' +set vrf name BLUE_SPOKE protocols bgp system-as '65001' +set vrf name BLUE_SPOKE protocols bgp neighbor 10.50.50.2 address-family ipv4-unicast as-override +set vrf name BLUE_SPOKE protocols bgp neighbor 10.50.50.2 remote-as '65035' + +# interfaces +set interfaces ethernet eth3 address '10.50.50.1/24' +set interfaces ethernet eth3 vrf 'BLUE_SPOKE' +``` + +- VyOS-PE2: + +```none +# VRF settings +set vrf name BLUE_HUB table '400' +set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast export vpn +set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast import vpn +set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast label vpn export 'auto' +set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast network 10.80.80.0/24 +set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast rd vpn export '10.80.80.1:1011' +set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast redistribute connected +set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast route-target vpn export '65035:1030' +set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast route-target vpn import '65035:1011 65050:2011 65035:1030' +set vrf name BLUE_HUB protocols bgp system-as '65001' +set vrf name BLUE_HUB protocols bgp neighbor 10.80.80.2 address-family ipv4-unicast as-override +set vrf name BLUE_HUB protocols bgp neighbor 10.80.80.2 remote-as '65035' + +# interfaces +set interfaces ethernet eth3 address '10.80.80.1/24' +set interfaces ethernet eth3 vrf 'BLUE_HUB' +``` + +- VyOS-PE3: + +```none +# VRF settings +set vrf name BLUE_SPOKE table '200' +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast export vpn +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast import vpn +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast label vpn export 'auto' +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast network 10.60.60.0/24 +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast rd vpn export '10.60.60.1:1011' +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast redistribute connected +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast route-target vpn export '65035:1011' +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast route-target vpn import '65035:1030' +set vrf name BLUE_SPOKE protocols bgp system-as '65001' +set vrf name BLUE_SPOKE protocols bgp neighbor 10.60.60.2 address-family ipv4-unicast as-override +set vrf name BLUE_SPOKE protocols bgp neighbor 10.60.60.2 remote-as '65035' + +# interfaces +set interfaces ethernet eth3 address '10.60.60.1/24' +set interfaces ethernet eth3 vrf 'BLUE_SPOKE' +``` + +### Step-4: Configuring CE nodes + +Dynamic routing used between CE and PE nodes and eBGP peering +established for the route exchanging between them. All routes +received by PEs are then exported to L3VPN and delivered from +Spoke sites to Hub and vise-versa based on previously +configured L3VPN parameters. + +- VyOS-CE1-SPOKE: + +```none +# interfaces +set interfaces dummy dum20 address '10.0.0.80/32' +set interfaces ethernet eth0 address '10.50.50.2/24' + +# BGP for peering with PE +set protocols bgp system-as 65035 +set protocols bgp address-family ipv4-unicast network 10.0.0.80/32 +set protocols bgp neighbor 10.50.50.1 ebgp-multihop '2' +set protocols bgp neighbor 10.50.50.1 remote-as '65001' +set protocols bgp neighbor 10.50.50.1 update-source 'eth0' +set protocols bgp parameters log-neighbor-changes +set protocols bgp parameters router-id '10.50.50.2' +``` + +- VyOS-CE1-HUB: + +```none +# interfaces +set interfaces dummy dum20 address '10.0.0.100/32' +set interfaces ethernet eth0 address '10.80.80.2/24' + +# BGP for peering with PE +set protocols bgp system-as 65035 +set protocols bgp address-family ipv4-unicast network 10.0.0.100/32 +set protocols bgp address-family ipv4-unicast redistribute connected +set protocols bgp neighbor 10.80.80.1 ebgp-multihop '2' +set protocols bgp neighbor 10.80.80.1 remote-as '65001' +set protocols bgp neighbor 10.80.80.1 update-source 'eth0' +set protocols bgp parameters log-neighbor-changes +set protocols bgp parameters router-id '10.80.80.2' +``` + +- VyOS-CE2-SPOKE: + +```none +# interfaces +set interfaces dummy dum20 address '10.0.0.90/32' +set interfaces ethernet eth0 address '10.60.60.2/24' + +# BGP for peering with PE +set protocols bgp system-as 65035 +set protocols bgp address-family ipv4-unicast network 10.0.0.90/32 +set protocols bgp neighbor 10.60.60.1 ebgp-multihop '2' +set protocols bgp neighbor 10.60.60.1 remote-as '65001' +set protocols bgp neighbor 10.60.60.1 update-source 'eth0' +set protocols bgp parameters log-neighbor-changes +set protocols bgp parameters router-id '10.60.60.2' +``` + +### Step-5: Verification + +This section describes verification commands for MPLS/BGP/LDP +protocols and L3VPN related routes as well as diagnosis and +reachability checks between CE nodes. + +Let’s check IPv4 routing and MPLS information on provider nodes +(same procedure for all P nodes): + +- “show ip ospf neighbor” for checking ospf relationship + +```none +vyos@VyOS-P1:~$ show ip ospf neighbor + +Neighbor ID Pri State Dead Time Address Interface RXmtL RqstL DBsmL +10.0.0.4 1 Full/Backup 34.718s 172.16.30.2 eth0:172.16.30.1 0 0 0 +10.0.0.5 1 Full/Backup 35.132s 172.16.40.2 eth1:172.16.40.1 0 0 0 +10.0.0.7 1 Full/Backup 34.764s 172.16.90.2 eth2:172.16.90.1 0 0 0 +10.0.0.1 1 Full/Backup 35.642s 172.16.10.2 eth3:172.16.10.1 0 0 0 +10.0.0.8 1 Full/Backup 35.484s 172.16.100.2 eth5:172.16.100.1 0 0 0 +``` + +- “show mpls ldp neighbor “ for checking ldp neighbors + +```none +vyos@VyOS-P1:~$ show mpls ldp neighbor +AF ID State Remote Address Uptime +ipv4 10.0.0.1 OPERATIONAL 10.0.0.1 07w5d06h +ipv4 10.0.0.4 OPERATIONAL 10.0.0.4 09w3d00h +ipv4 10.0.0.5 OPERATIONAL 10.0.0.5 09w2d23h +ipv4 10.0.0.7 OPERATIONAL 10.0.0.7 03w0d01h +ipv4 10.0.0.8 OPERATIONAL 10.0.0.8 01w3d02h +``` + +- “show mpls ldp binding” for checking mpls label assignment + +```none +vyos@VyOS-P1:~$ show mpls ldp discovery +AF Destination Nexthop Local Label Remote Label In Use +ipv4 10.0.0.1/32 10.0.0.1 23 imp-null yes +ipv4 10.0.0.1/32 10.0.0.4 23 20 no +ipv4 10.0.0.1/32 10.0.0.5 23 17 no +ipv4 10.0.0.1/32 10.0.0.7 23 16 no +ipv4 10.0.0.1/32 10.0.0.8 23 16 no +ipv4 10.0.0.2/32 10.0.0.1 20 16 no +ipv4 10.0.0.2/32 10.0.0.4 20 22 no +ipv4 10.0.0.2/32 10.0.0.5 20 24 yes +ipv4 10.0.0.2/32 10.0.0.7 20 17 no +ipv4 10.0.0.2/32 10.0.0.8 20 17 no +ipv4 10.0.0.3/32 10.0.0.1 imp-null 17 no +ipv4 10.0.0.3/32 10.0.0.4 imp-null 16 no +ipv4 10.0.0.3/32 10.0.0.5 imp-null 18 no +ipv4 10.0.0.3/32 10.0.0.7 imp-null 18 no +ipv4 10.0.0.3/32 10.0.0.8 imp-null 18 no +ipv4 10.0.0.4/32 10.0.0.1 16 18 no +ipv4 10.0.0.4/32 10.0.0.4 16 imp-null yes +ipv4 10.0.0.4/32 10.0.0.5 16 19 no +ipv4 10.0.0.4/32 10.0.0.7 16 19 no +ipv4 10.0.0.4/32 10.0.0.8 16 19 no +ipv4 10.0.0.5/32 10.0.0.1 21 19 no +ipv4 10.0.0.5/32 10.0.0.4 21 17 no +ipv4 10.0.0.5/32 10.0.0.5 21 imp-null yes +ipv4 10.0.0.5/32 10.0.0.7 21 20 no +ipv4 10.0.0.5/32 10.0.0.8 21 20 no +ipv4 10.0.0.6/32 10.0.0.1 17 20 no +ipv4 10.0.0.6/32 10.0.0.4 17 23 yes +ipv4 10.0.0.6/32 10.0.0.5 17 21 yes +ipv4 10.0.0.6/32 10.0.0.7 17 21 no +ipv4 10.0.0.6/32 10.0.0.8 17 21 no +ipv4 10.0.0.7/32 10.0.0.1 22 21 no +ipv4 10.0.0.7/32 10.0.0.4 22 18 no +ipv4 10.0.0.7/32 10.0.0.5 22 20 no +ipv4 10.0.0.7/32 10.0.0.7 22 imp-null yes +ipv4 10.0.0.7/32 10.0.0.8 22 22 no +ipv4 10.0.0.8/32 10.0.0.1 24 22 no +ipv4 10.0.0.8/32 10.0.0.4 24 19 no +ipv4 10.0.0.8/32 10.0.0.5 24 16 no +ipv4 10.0.0.8/32 10.0.0.7 24 22 no +ipv4 10.0.0.8/32 10.0.0.8 24 imp-null yes +ipv4 10.0.0.9/32 10.0.0.1 18 23 no +ipv4 10.0.0.9/32 10.0.0.4 18 21 yes +ipv4 10.0.0.9/32 10.0.0.5 18 22 no +ipv4 10.0.0.9/32 10.0.0.7 18 23 no +ipv4 10.0.0.9/32 10.0.0.8 18 23 no +ipv4 10.0.0.10/32 10.0.0.1 19 24 no +ipv4 10.0.0.10/32 10.0.0.4 19 24 yes +ipv4 10.0.0.10/32 10.0.0.5 19 23 yes +ipv4 10.0.0.10/32 10.0.0.7 19 24 no +ipv4 10.0.0.10/32 10.0.0.8 19 24 no +``` + +Now we’re checking iBGP status and routes from route-reflector +nodes to other devices: + +- “show bgp ipv4 vpn summary” for checking BGP VPNv4 neighbors: + +```none +vyos@VyOS-RR1:~$ show bgp ipv4 vpn summary +BGP router identifier 10.0.0.1, local AS number 65001 vrf-id 0 +BGP table version 0 +RIB entries 9, using 1728 bytes of memory +Peers 4, using 85 KiB of memory +Peer groups 1, using 64 bytes of memory + +Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd PfxSnt +10.0.0.7 4 65001 7719 7733 0 0 0 5d07h56m 2 10 +10.0.0.8 4 65001 7715 7724 0 0 0 5d08h28m 4 10 +10.0.0.9 4 65001 7713 7724 0 0 0 5d08h28m 2 10 +10.0.0.10 4 65001 7713 7724 0 0 0 5d08h28m 2 10 + +Total number of neighbors 4 +``` + +- “show bgp ipv4 vpn” for checking all VPNv4 prefixes information: + +```none +vyos@VyOS-RR1:~$ show bgp ipv4 vpn +BGP table version is 2, local router ID is 10.0.0.1, vrf id 0 +Default local pref 100, local AS 65001 +Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, + i internal, r RIB-failure, S Stale, R Removed +Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self +Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path +Route Distinguisher: 10.50.50.1:1011 +*>i10.50.50.0/24 10.0.0.7 0 100 0 i + UN=10.0.0.7 EC{65035:1011} label=80 type=bgp, subtype=0 +*>i80.80.80.80/32 10.0.0.7 0 100 0 65035 i + UN=10.0.0.7 EC{65035:1011} label=80 type=bgp, subtype=0 +Route Distinguisher: 10.60.60.1:1011 +*>i10.60.60.0/24 10.0.0.10 0 100 0 i + UN=10.0.0.10 EC{65035:1011} label=80 type=bgp, subtype=0 +*>i90.90.90.90/32 10.0.0.10 0 100 0 65035 i + UN=10.0.0.10 EC{65035:1011} label=80 type=bgp, subtype=0 +Route Distinguisher: 10.80.80.1:1011 +*>i10.80.80.0/24 10.0.0.8 0 100 0 i + UN=10.0.0.8 EC{65035:1030} label=80 type=bgp, subtype=0 +*>i100.100.100.100/32 + 10.0.0.8 0 100 0 65035 i + UN=10.0.0.8 EC{65035:1030} label=80 type=bgp, subtype=0 +Route Distinguisher: 172.16.80.1:2011 +*>i10.110.110.0/24 10.0.0.8 0 100 0 65050 i + UN=10.0.0.8 EC{65050:2011} label=81 type=bgp, subtype=0 +*>i172.16.80.0/24 10.0.0.8 0 100 0 i + UN=10.0.0.8 EC{65050:2011} label=81 type=bgp, subtype=0 +Route Distinguisher: 172.16.100.1:2011 +*>i10.210.210.0/24 10.0.0.9 0 100 0 65050 i + UN=10.0.0.9 EC{65050:2011} label=80 type=bgp, subtype=0 +*>i172.16.100.0/24 10.0.0.9 0 100 0 i + UN=10.0.0.9 EC{65050:2011} label=80 type=bgp, subtype=0 +``` + +- “show bgp ipv4 vpn x.x.x.x/x” for checking best path selected + for specific VPNv4 destination + +```none +vyos@VyOS-RR1:~$ show bgp ipv4 vpn 10.0.0.100/32 +BGP routing table entry for 10.80.80.1:1011:10.0.0.100/32 +not allocated +Paths: (1 available, best #1) + Advertised to non peer-group peers: + 10.0.0.7 10.0.0.8 10.0.0.9 10.0.0.10 + 65035, (Received from a RR-client) + 10.0.0.8 from 10.0.0.8 (10.0.0.8) + Origin incomplete, metric 0, localpref 100, valid, internal, best (First path received) + Extended Community: RT:65035:1030 + Remote label: 80 + Last update: Tue Oct 19 13:45:32 202 +``` + +Also we can verify how PE devices receives VPNv4 networks from the RRs +and installing them to the specific customer VRFs: + +- “show bgp ipv4 vpn summary” for checking iBGP neighbors against + route-reflector devices: + +```none +vyos@VyOS-PE1:~$ show bgp ipv4 vpn summary +BGP router identifier 10.0.0.7, local AS number 65001 vrf-id 0 +BGP table version 0 +RIB entries 9, using 1728 bytes of memory +Peers 2, using 43 KiB of memory +Peer groups 1, using 64 bytes of memory + +Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd PfxSnt +10.0.0.1 4 65001 8812 8794 0 0 0 01:18:42 8 2 +10.0.0.2 4 65001 8800 8792 0 0 0 6d02h27m 8 2 +``` + +- “show bgp vrf all” for checking all the prefix learning on BGP + : within VRFs: + +```none +vyos@VyOS-PE1:~$ show bgp vrf all + +Instance default: +No BGP prefixes displayed, 0 exist + +Instance BLUE_SPOKE: +BGP table version is 8, local router ID is 10.50.50.1, vrf id 6 +Default local pref 100, local AS 65001 +Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, + i internal, r RIB-failure, S Stale, R Removed +Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self +Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path +* 10.50.50.0/24 0.0.0.0 0 32768 ? +*> 0.0.0.0 0 32768 i +*> 10.80.80.0/24 10.0.0.8@0< 0 100 0 i +* 10.0.0.8@0< 0 100 0 i +*> 10.0.0.80/32 10.50.50.2 0 0 65035 i +*> 10.0.0.100/32 + 10.0.0.8@0< 0 100 0 65035 ? +* 10.0.0.8@0< 0 100 0 65035 ? +``` + +- “show bgp vrf BLUE_SPOKE summary” for checking EBGP neighbor + : information between PE and CE: + +```none +vyos@VyOS-PE1:~$ show bgp vrf BLUE_SPOKE summary + + +IPv4 Unicast Summary: +BGP router identifier 10.50.50.1, local AS number 65001 vrf-id 6 +BGP table version 8 +RIB entries 7, using 1344 bytes of memory +Peers 1, using 21 KiB of memory + +Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd PfxSnt +10.50.50.2 4 65035 9019 9023 0 0 0 6d06h12m 1 4 + +Total number of neighbors 1 +``` + +- “show ip route vrf BLUE_SPOKE” for viewing the RIB in our Spoke PE. + : Using this command we are also able to check the transport and + customer label (inner/outer) for Hub network prefix (10.0.0.100/32): + +```none +vyos@VyOS-PE1:~$ show ip route vrf BLUE_SPOKE + +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + +VRF BLUE_SPOKE: +K>* 0.0.0.0/0 [255/8192] unreachable (ICMP unreachable), 03w0d23h +C>* 10.50.50.0/24 is directly connected, eth3, 03w0d23h +B> 10.80.80.0/24 [200/0] via 10.0.0.8 (vrf default) (recursive), label 80, weight 1, 04:22:00 + * via 172.16.90.1, eth0 (vrf default), label 24/80, weight 1, 04:22:00 +B>* 10.0.0.80/32 [20/0] via 10.50.50.2, eth3, weight 1, 6d05h30m +B> 10.0.0.100/32 [200/0] via 10.0.0.8 (vrf default) (recursive), label 80, weight 1, 04:22:00 + * via 172.16.90.1, eth0 (vrf default), label 24/80, weight 1, 04:22:00 +``` + +- “show bgp ipv4 vpn x.x.x.x/32” for checking the best-path to the + : specific VPNv4 destination including extended community and + remotelabel information. This procedure is the same on all Spoke nodes: + +```none +vyos@VyOS-PE1:~$ show bgp ipv4 vpn 10.0.0.100/32 +BGP routing table entry for 10.80.80.1:1011:10.0.0.100/32 +not allocated +Paths: (2 available, best #1) + Not advertised to any peer + 65035 + 10.0.0.8 from 10.0.0.1 (10.0.0.8) + Origin incomplete, metric 0, localpref 100, valid, internal, best (Neighbor IP) + Extended Community: RT:65035:1030 + Originator: 10.0.0.8, Cluster list: 10.0.0.1 + Remote label: 80 + Last update: Tue Oct 19 13:45:26 2021 + 65035 + 10.0.0.8 from 10.0.0.2 (10.0.0.8) + Origin incomplete, metric 0, localpref 100, valid, internal + Extended Community: RT:65035:1030 + Originator: 10.0.0.8, Cluster list: 10.0.0.1 + Remote label: 80 + Last update: Wed Oct 13 12:39:34 202 +``` + +Now, let’s check routing information on out Hub PE: + +- “show bgp ipv4 vpn summary” for checking iBGP neighbors again + : VyOS-RR1/RR2 + +```none +vyos@VyOS-PE2:~$ show bgp ipv4 vpn summary +BGP router identifier 10.0.0.8, local AS number 65001 vrf-id 0 +BGP table version 0 +RIB entries 9, using 1728 bytes of memory +Peers 2, using 43 KiB of memory +Peer groups 1, using 64 bytes of memory + +Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd PfxSnt +10.0.0.1 4 65001 15982 15949 0 0 0 05:41:28 6 4 +10.0.0.2 4 65001 9060 9054 0 0 0 6d06h47m 6 4 + +Total number of neighbors +``` + +- “show bgp vrf all” for checking all the prefixes learning on BGP + +```none +vyos@VyOS-PE2:~$ show bgp vrf all + +Instance default: +No BGP prefixes displayed, 0 exist + +Instance BLUE_HUB: +BGP table version is 50, local router ID is 10.80.80.1, vrf id 8 +Default local pref 100, local AS 65001 +Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, + i internal, r RIB-failure, S Stale, R Removed +Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self +Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path +*> 10.50.50.0/24 10.0.0.7@0< 0 100 0 i +* 10.0.0.7@0< 0 100 0 i +*> 10.60.60.0/24 10.0.0.10@0< 0 100 0 i +* 10.0.0.10@0< 0 100 0 i +* 10.80.80.0/24 10.80.80.2 0 0 65035 ? +* 0.0.0.0 0 32768 i +*> 0.0.0.0 0 32768 ? +*> 10.110.110.0/24 172.16.80.2@9< 0 0 65050 i +*> 10.210.210.0/24 10.0.0.9@0< 0 100 0 65050 i +* 10.0.0.9@0< 0 100 0 65050 i +*> 10.0.0.80/32 10.0.0.7@0< 0 100 0 65035 i +* 10.0.0.7@0< 0 100 0 65035 i +*> 10.0.0.90/32 10.0.0.10@0< 0 100 0 65035 i +* 10.0.0.10@0< 0 100 0 65035 i +*> 10.0.0.100/32 + 10.80.80.2 0 0 65035 ? +*> 172.16.80.0/24 0.0.0.0@9< 0 32768 ? + 0.0.0.0@9< 0 32768 i +*> 172.16.100.0/24 10.0.0.9@0< 0 100 0 i +* 10.0.0.9@0< 0 100 0 i +``` + +- “show bgp vrf BLUE_HUB summary” for checking EBGP neighbor + : CE Hub device + +```none +vyos@VyOS-PE2:~$ show bgp vrf BLUE_HUB summary + +IPv4 Unicast Summary: +BGP router identifier 10.80.80.1, local AS number 65001 vrf-id 8 +BGP table version 50 +RIB entries 19, using 3648 bytes of memory +Peers 1, using 21 KiB of memory + +Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd PfxSnt +10.80.80.2 4 65035 15954 15972 0 0 0 01w4d01h 2 10 +``` + +- “show ip route vrf BLUE_HUB” to view the RIB in our Hub PE. + : With this command we are able to check the transport and + customer label (inner/outer) for network spokes prefixes + 10.0.0.80/32 - 10.0.0.90/32 + +```none +vyos@VyOS-PE2:~$ show ip route vrf BLUE_HUB +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup +VRF BLUE_HUB: +K>* 0.0.0.0/0 [255/8192] unreachable (ICMP unreachable), 01w4d01h +B> 10.50.50.0/24 [200/0] via 10.0.0.7 (vrf default) (recursive), label 144, weight 1, 05:53:15 + * via 172.16.100.1, eth1 (vrf default), label 22/144, weight 1, 05:53:15 +B> 10.60.60.0/24 [200/0] via 10.0.0.10 (vrf default) (recursive), label 144, weight 1, 05:53:15 + * via 172.16.110.1, eth0 (vrf default), label 23/144, weight 1, 05:53:15 +C>* 10.80.80.0/24 is directly connected, eth3, 01w4d01h +B>* 10.110.110.0/24 [200/0] via 172.16.80.2, eth2 (vrf GREEN), weight 1, 01w4d01h +B> 10.210.210.0/24 [200/0] via 10.0.0.9 (vrf default) (recursive), label 144, weight 1, 05:53:15 + * via 172.16.100.1, eth1 (vrf default), label 18/144, weight 1, 05:53:15 + * via 172.16.110.1, eth0 (vrf default), label 22/144, weight 1, 05:53:15 +B> 10.0.0.80/32 [200/0] via 10.0.0.7 (vrf default) (recursive), label 144, weight 1, 05:53:15 + * via 172.16.100.1, eth1 (vrf default), label 22/144, weight 1, 05:53:15 +B> 10.0.0.90/32 [200/0] via 10.0.0.10 (vrf default) (recursive), label 144, weight 1, 05:53:15 + * via 172.16.110.1, eth0 (vrf default), label 23/144, weight 1, 05:53:15 +B>* 10.0.0.100/32 [20/0] via 10.80.80.2, eth3, weight 1, 01w4d01h +B>* 172.16.80.0/24 [200/0] is directly connected, eth2 (vrf GREEN), weight 1, 01w4d01h +B> 172.16.100.0/24 [200/0] via 10.0.0.9 (vrf default) (recursive), label 144, weight 1, 05:53:15 + * via 172.16.100.1, eth1 (vrf default), label 18/144, weight 1, 05:53:15 + * via 172.16.110.1, eth0 (vrf default), label 22/144, weight 1, 05:53:15 +``` + +- “show bgp ipv4 vpn x.x.x.x/32” for checking best-path, + : extended community and remote label of specific destination + +```none +vyos@VyOS-PE2:~$ show bgp ipv4 vpn 10.0.0.80/32 +BGP routing table entry for 10.50.50.1:1011:10.0.0.80/32 +not allocated +Paths: (2 available, best #1) + Not advertised to any peer + 65035 + 10.0.0.7 from 10.0.0.1 (10.0.0.7) + Origin IGP, metric 0, localpref 100, valid, internal, best (Neighbor IP) + Extended Community: RT:65035:1011 + Originator: 10.0.0.7, Cluster list: 10.0.0.1 + Remote label: 144 + Last update: Tue Oct 19 13:45:30 2021 + 65035 + 10.0.0.7 from 10.0.0.2 (10.0.0.7) + Origin IGP, metric 0, localpref 100, valid, internal + Extended Community: RT:65035:1011 + Originator: 10.0.0.7, Cluster list: 10.0.0.1 + Remote label: 144 + Last update: Wed Oct 13 12:39:37 2021 + +vyos@VyOS-PE2:~$ show bgp ipv4 vpn 10.0.0.90/32 +BGP routing table entry for 10.60.60.1:1011:10.0.0.90/32 +not allocated +Paths: (2 available, best #1) + Not advertised to any peer + 65035 + 10.0.0.10 from 10.0.0.1 (10.0.0.10) + Origin IGP, metric 0, localpref 100, valid, internal, best (Neighbor IP) + Extended Community: RT:65035:1011 + Originator: 10.0.0.10, Cluster list: 10.0.0.1 + Remote label: 144 + Last update: Tue Oct 19 13:45:30 2021 + 65035 + 10.0.0.10 from 10.0.0.2 (10.0.0.10) + Origin IGP, metric 0, localpref 100, valid, internal + Extended Community: RT:65035:1011 + Originator: 10.0.0.10, Cluster list: 10.0.0.1 + Remote label: 144 + Last update: Wed Oct 13 12:45:44 2021 +``` + +Finally, let’s check the reachability between CEs: + +- VyOS-CE1-SPOKE -----> VyOS-CE-HUB + +```none +# check rib +vyos@VyOS-CE1-SPOKE:~$ show ip route +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + +B 10.50.50.0/24 [20/0] via 10.50.50.1 inactive, weight 1, 6d07h53m +C>* 10.50.50.0/24 is directly connected, eth0, 09w0d00h +B>* 10.80.80.0/24 [20/0] via 10.50.50.1, eth0, weight 1, 6d07h53m +C>* 10.0.0.80/32 is directly connected, dum20, 09w0d00h +B>* 10.0.0.100/32 [20/0] via 10.50.50.1, eth0, weight 1, 6d07h53m + +# check icmp +vyos@VyOS-CE1-SPOKE:~$ ping 10.0.0.100 interface 10.0.0.80 +PING 10.0.0.100 (10.0.0.100) from 10.0.0.80 : 56(84) bytes of data. +64 bytes from 10.0.0.100: icmp_seq=1 ttl=62 time=6.52 ms +64 bytes from 10.0.0.100: icmp_seq=2 ttl=62 time=4.13 ms +64 bytes from 10.0.0.100: icmp_seq=3 ttl=62 time=4.04 ms +64 bytes from 10.0.0.100: icmp_seq=4 ttl=62 time=4.03 ms +^C +--- 10.0.0.100 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 8ms +rtt min/avg/max/mdev = 4.030/4.680/6.518/1.064 ms + +# check network path +vyos@VyOS-CE1-SPOKE:~$ traceroute 10.0.0.100 +traceroute to 10.0.0.100 (10.0.0.100), 30 hops max, 60 byte packets + 1 10.50.50.1 (10.50.50.1) 1.041 ms 1.252 ms 1.835 ms + 2 * * * + 3 10.0.0.100 (10.0.0.100) 9.225 ms 9.159 ms 9.121 m +``` + +- VyOS-CE-HUB -------> VyOS-CE1-SPOKE +- VyOS-CE-HUB -------> VyOS-CE2-SPOKE + +```none +# check rib +vyos@VyOS-CE-HUB:~$ show ip route +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + +B>* 10.50.50.0/24 [20/0] via 10.80.80.1, eth0, weight 1, 6d08h04m +B>* 10.60.60.0/24 [20/0] via 10.80.80.1, eth0, weight 1, 6d08h35m +C>* 10.80.80.0/24 is directly connected, eth0, 01w6d07h +B>* 10.110.110.0/24 [20/0] via 10.80.80.1, eth0, weight 1, 01w4d02h +B>* 10.210.210.0/24 [20/0] via 10.80.80.1, eth0, weight 1, 6d08h35m +B>* 10.0.0.80/32 [20/0] via 10.80.80.1, eth0, weight 1, 6d08h04m +B>* 10.0.0.90/32 [20/0] via 10.80.80.1, eth0, weight 1, 6d08h35m +C>* 10.0.0.100/32 is directly connected, dum20, 01w6d07h +B>* 172.16.80.0/24 [20/0] via 10.80.80.1, eth0, weight 1, 01w4d02h +B>* 172.16.100.0/24 [20/0] via 10.80.80.1, eth0, weight 1, 6d08h35m + +# check icmp +vyos@VyOS-CE-HUB:~$ ping 10.0.0.80 interface 10.0.0.100 c 4 +PING 10.0.0.80 (10.0.0.80) from 10.0.0.100 : 56(84) bytes of data. +64 bytes from 10.0.0.80: icmp_seq=1 ttl=62 time=3.31 ms +64 bytes from 10.0.0.80: icmp_seq=2 ttl=62 time=4.23 ms +64 bytes from 10.0.0.80: icmp_seq=3 ttl=62 time=3.89 ms +64 bytes from 10.0.0.80: icmp_seq=4 ttl=62 time=3.22 ms + +--- 10.0.0.80 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 9ms +rtt min/avg/max/mdev = 3.218/3.661/4.226/0.421 ms + +vyos@VyOS-CE-HUB:~$ ping 10.0.0.90 interface 10.0.0.100 c 4 +PING 10.0.0.90 (10.0.0.90) from 10.0.0.100 : 56(84) bytes of data. +64 bytes from 10.0.0.90: icmp_seq=1 ttl=62 time=7.46 ms +64 bytes from 10.0.0.90: icmp_seq=2 ttl=62 time=4.43 ms +64 bytes from 10.0.0.90: icmp_seq=3 ttl=62 time=4.60 ms +^C +--- 10.0.0.90 ping statistics --- +3 packets transmitted, 3 received, 0% packet loss, time 6ms +rtt min/avg/max/mdev = 4.430/5.498/7.463/1.391 ms + +# check network path +vyos@VyOS-CE-HUB:~$ traceroute 10.0.0.80 +traceroute to 10.0.0.80 (10.0.0.80), 30 hops max, 60 byte packets + 1 10.80.80.1 (10.80.80.1) 1.563 ms 1.341 ms 1.075 ms + 2 * * * + 3 10.0.0.80 (10.0.0.80) 8.125 ms 8.019 ms 7.781 ms + +vyos@VyOS-CE-HUB:~$ traceroute 10.0.0.90 +traceroute to 10.0.0.90 (10.0.0.90), 30 hops max, 60 byte packets + 1 10.80.80.1 (10.80.80.1) 1.305 ms 1.137 ms 1.097 ms + 2 * * * + 3 * * * + 4 10.0.0.90 (10.0.0.90) 9.358 ms 9.325 ms 9.292 ms +``` + +- VyOS-CE2-SPOKE -------> VyOS-CE-HUB + +```none +# check rib +vyos@rt-ce2-SPOKE:~$ show ip route +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + +B 10.60.60.0/24 [20/0] via 10.60.60.1 inactive, weight 1, 02w6d00h +C>* 10.60.60.0/24 is directly connected, eth0, 02w6d00h +B>* 10.80.80.0/24 [20/0] via 10.60.60.1, eth0, weight 1, 6d08h46m +C>* 10.0.0.90/32 is directly connected, dum20, 02w6d00h +B>* 10.0.0.100/32 [20/0] via 10.60.60.1, eth0, weight 1, 6d08h46m + +# check icmp +vyos@rt-ce2-SPOKE:~$ ping 10.0.0.100 interface 10.0.0.90 c 4 +PING 10.0.0.100 (10.0.0.100) from 10.0.0.90 : 56(84) bytes of data. +64 bytes from 10.0.0.100: icmp_seq=1 ttl=62 time=4.97 ms +64 bytes from 10.0.0.100: icmp_seq=2 ttl=62 time=4.45 ms +64 bytes from 10.0.0.100: icmp_seq=3 ttl=62 time=4.20 ms +64 bytes from 10.0.0.100: icmp_seq=4 ttl=62 time=4.29 ms + +--- 10.0.0.100 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 9ms +rtt min/avg/max/mdev = 4.201/4.476/4.971/0.309 ms + +# check network path +vyos@rt-ce2-SPOKE:~$ traceroute 10.0.0.100 +traceroute to 10.0.0.100 (10.0.0.100), 30 hops max, 60 byte packets + 1 10.60.60.1 (10.60.60.1) 1.343 ms 1.190 ms 1.152 ms + 2 * * * + 3 * * * + 4 10.0.0.100 (10.0.0.100) 7.504 ms 7.480 ms 7.488 ms +``` + +**Note:** At the moment, trace mpls doesn’t show labels/paths. So we’ll see * * * for the transit routers of the mpls backbone. diff --git a/docs/configexamples/md-lac-lns.md b/docs/configexamples/md-lac-lns.md new file mode 100644 index 00000000..5bf5edb2 --- /dev/null +++ b/docs/configexamples/md-lac-lns.md @@ -0,0 +1,174 @@ +--- +lastproofread: '2024-02-21' +--- + +(examples-lac-lns)= + +# PPPoE over L2TP + +This document is to describe a basic setup using PPPoE over L2TP. +LAC and LNS are components of the broadband topology. +LAC - L2TP access concentrator +LNS - L2TP Network Server +LAC and LNS forms L2TP tunnel. LAC receives packets from PPPoE clients and +forward them to LNS. LNS is the termination point that comes from PPP packets +from the remote client. + +In this example we use VyOS 1.5 as LNS and Cisco IOS as LAC. +All users with domain **vyos.io** will be tunneled to LNS via L2TP. + +## Network Topology + +```{image} /_static/images/lac-lns-diagram.jpg +:align: center +:alt: Network Topology Diagram +:width: 60% +``` + +## Configurations + +### LAC + +```none +aaa new-model +! +aaa authentication ppp default local +! +vpdn enable +vpdn aaa attribute nas-ip-address vpdn-nas +! +vpdn-group LAC + request-dialin + protocol l2tp + domain vyos.io + initiate-to ip 192.168.139.100 + source-ip 192.168.139.101 + local name LAC + l2tp tunnel password 0 test123 +! +bba-group pppoe MAIN-BBA + virtual-template 1 +! +interface GigabitEthernet0/0 + description To LNS + ip address 192.168.139.101 255.255.255.0 + duplex auto + speed auto + media-type rj45 +! +interface GigabitEthernet0/1 + description To PPPoE clients + no ip address + duplex auto + speed auto + media-type rj45 + pppoe enable group MAIN-BBA +! +interface Virtual-Template1 + description pppoe MAIN-BBA + no ip address + no peer default ip address + ppp mtu adaptive + ppp authentication chap +! +``` + +### LNS + +```none +set interfaces ethernet eth0 address '192.168.139.100/24' +set nat source rule 100 outbound-interface name 'eth0' +set nat source rule 100 source address '10.0.0.0/24' +set nat source rule 100 translation address 'masquerade' +set protocols static route 0.0.0.0/0 next-hop 192.168.139.2 +set vpn l2tp remote-access authentication mode 'radius' +set vpn l2tp remote-access authentication radius server 192.168.139.110 key 'radiustest' +set vpn l2tp remote-access client-ip-pool TEST-POOL range '10.0.0.2-10.0.0.100' +set vpn l2tp remote-access default-pool 'TEST-POOL' +set vpn l2tp remote-access gateway-address '10.0.0.1' +set vpn l2tp remote-access lns host-name 'LAC' +set vpn l2tp remote-access lns shared-secret 'test123' +set vpn l2tp remote-access name-server '8.8.8.8' +set vpn l2tp remote-access ppp-options disable-ccp +``` + +:::{note} +This setup requires the Compression Control Protocol (CCP) +being disabled, the command `set vpn l2tp remote-access ppp-options disable-ccp` +accomplishes that. +::: + +### Client + +In this lab we use Windows PPPoE client. + +```{image} /_static/images/lac-lns-winclient.jpg +:align: center +:alt: Window PPPoE Client Configuration +:width: 100% +``` + +### Monitoring + +Monitoring on LNS side + +```none +vyos@vyos:~$ show l2tp-server sessions + ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes +--------+--------------+----------+-----+--------+-----------------+------------+--------+----------+-----------+---------- + l2tp0 | test@vyos.io | 10.0.0.2 | | | 192.168.139.101 | | active | 00:00:35 | 188.4 KiB | 9.3 MiB +``` + +Monitoring on LAC side + +```none +Router#show pppoe session + 1 session in FORWARDED (FWDED) State + 1 session total +Uniq ID PPPoE RemMAC Port VT VA State + SID LocMAC VA-st Type + 1 1 000c.290b.20a6 Gi0/1 1 N/A FWDED + 0c58.88ac.0001 + +Router#show l2tp +L2TP Tunnel and Session Information Total tunnels 1 sessions 1 + +LocTunID RemTunID Remote Name State Remote Address Sessn L2TP Class/ + Count VPDN Group +23238 2640 LAC est 192.168.139.100 1 LAC + +LocID RemID TunID Username, Intf/ State Last Chg Uniq ID + Vcid, Circuit +25641 25822 23238 test@vyos.io, Gi0/1 est 00:05:36 1 +``` + +Monitoring on RADIUS Server side + +```none +root@Radius:~# cat /var/log/freeradius/radacct/192.168.139.100/detail-20240221 +Wed Feb 21 13:37:17 2024 + User-Name = "test@vyos.io" + NAS-Port = 0 + NAS-Port-Id = "l2tp0" + NAS-Port-Type = Virtual + Service-Type = Framed-User + Framed-Protocol = PPP + Calling-Station-Id = "192.168.139.101" + Called-Station-Id = "192.168.139.100" + Acct-Status-Type = Start + Acct-Authentic = RADIUS + Acct-Session-Id = "45c731e169d9a4f1" + Acct-Session-Time = 0 + Acct-Input-Octets = 0 + Acct-Output-Octets = 0 + Acct-Input-Packets = 0 + Acct-Output-Packets = 0 + Acct-Input-Gigawords = 0 + Acct-Output-Gigawords = 0 + Framed-IP-Address = 10.0.0.2 + NAS-IP-Address = 192.168.139.100 + Event-Timestamp = "Feb 21 2024 13:37:17 UTC" + Tmp-String-9 = "ai:" + Acct-Unique-Session-Id = "ea6a1089816f19c0d0f1819bc61c3318" + Timestamp = 1708522637 +``` diff --git a/docs/configexamples/md-nmp.md b/docs/configexamples/md-nmp.md new file mode 100644 index 00000000..71855f89 --- /dev/null +++ b/docs/configexamples/md-nmp.md @@ -0,0 +1,69 @@ +--- +lastproofread: '2023-03-26' +--- + +(examples-nmp)= + +# NMP example + +Consider how to quickly set up NMP and VyOS for monitoring. +NMP is multi-vendor network monitoring from 'SolarWinds' built to scale and expand with the needs of your network. + +## Configuration 'VyOS' + +First prepare our VyOS router for connection to NMP. We have to set up the SNMP protocol and connectivity between the router and NMP. + +```none +set interfaces ethernet eth0 address 'dhcp' +set system name-server '8.8.8.8' +set service snmp community router authorization 'test' +set service snmp community router network '0.0.0.0/0' +``` + +## Configuration 'NMP' + +Next, you just should follow the pictures: + +```{image} /_static/images/nmp1.png +:align: center +:alt: Network Topology Diagram +:width: 80% +``` + +```{image} /_static/images/nmp2.png +:align: center +:alt: Network Topology Diagram +:width: 80% +``` + +```{image} /_static/images/nmp3.png +:align: center +:alt: Network Topology Diagram +:width: 80% +``` + +```{image} /_static/images/nmp4.png +:align: center +:alt: Network Topology Diagram +:width: 80% +``` + +```{image} /_static/images/nmp5.png +:align: center +:alt: Network Topology Diagram +:width: 80% +``` + +```{image} /_static/images/nmp6.png +:align: center +:alt: Network Topology Diagram +:width: 80% +``` + +```{image} /_static/images/nmp7.png +:align: center +:alt: Network Topology Diagram +:width: 80% +``` + +In the end, you'll get a powerful instrument for monitoring the VyOS systems. diff --git a/docs/configexamples/md-ospf-unnumbered.md b/docs/configexamples/md-ospf-unnumbered.md new file mode 100644 index 00000000..9174d1b4 --- /dev/null +++ b/docs/configexamples/md-ospf-unnumbered.md @@ -0,0 +1,118 @@ +--- +lastproofread: '2021-06-29' +--- + +(examples-ospf-unnumbered)= + +# OSPF unnumbered with ECMP + +General information can be found in the {ref}`routing-ospf` chapter. + +## Configuration + +- Router A: + +```none +set interfaces ethernet eth0 address '10.0.0.1/24' +set interfaces ethernet eth1 address '192.168.0.1/32' +set interfaces ethernet eth1 ip ospf authentication md5 key-id 1 md5-key 'yourpassword' +set interfaces ethernet eth1 ip ospf network 'point-to-point' +set interfaces ethernet eth2 address '192.168.0.1/32' +set interfaces ethernet eth2 ip ospf authentication md5 key-id 1 md5-key 'yourpassword' +set interfaces ethernet eth2 ip ospf network 'point-to-point' +set interfaces loopback lo address '192.168.0.1/32' +set protocols ospf area 0.0.0.0 authentication 'md5' +set protocols ospf area 0.0.0.0 network '192.168.0.1/32' +set protocols ospf parameters router-id '192.168.0.1' +set protocols ospf redistribute connected +``` + +- Router B: + +```none +set interfaces ethernet eth0 address '10.0.0.2/24' +set interfaces ethernet eth1 address '192.168.0.2/32' +set interfaces ethernet eth1 ip ospf authentication md5 key-id 1 md5-key 'yourpassword' +set interfaces ethernet eth1 ip ospf network 'point-to-point' +set interfaces ethernet eth2 address '192.168.0.2/32' +set interfaces ethernet eth2 ip ospf authentication md5 key-id 1 md5-key 'yourpassword' +set interfaces ethernet eth2 ip ospf network 'point-to-point' +set interfaces loopback lo address '192.168.0.2/32' +set protocols ospf area 0.0.0.0 authentication 'md5' +set protocols ospf area 0.0.0.0 network '192.168.0.2/32' +set protocols ospf parameters router-id '192.168.0.2' +set protocols ospf redistribute connected +``` + + +## Results + +- Router A: + +```none +vyos@vyos:~$ show interfaces +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +eth0 10.0.0.1/24 u/u +eth1 192.168.0.1/32 u/u +eth2 192.168.0.1/32 u/u +lo 127.0.0.1/8 u/u + 192.168.0.1/32 + ::1/128 +``` + +```none +vyos@vyos:~$ show ip route +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued route, r - rejected route + +S>* 0.0.0.0/0 [210/0] via 10.0.0.254, eth0, 00:57:34 +O 10.0.0.0/24 [110/20] via 192.168.0.2, eth1 onlink, 00:13:21 + via 192.168.0.2, eth2 onlink, 00:13:21 +C>* 10.0.0.0/24 is directly connected, eth0, 00:57:35 +O 192.168.0.1/32 [110/0] is directly connected, lo, 00:48:53 +C * 192.168.0.1/32 is directly connected, eth2, 00:56:31 +C * 192.168.0.1/32 is directly connected, eth1, 00:56:31 +C>* 192.168.0.1/32 is directly connected, lo, 00:57:36 +O>* 192.168.0.2/32 [110/1] via 192.168.0.2, eth1 onlink, 00:29:03 + * via 192.168.0.2, eth2 onlink, 00:29:03 +``` + +- Router B: + +```none +vyos@vyos:~$ show interfaces +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +eth0 10.0.0.2/24 u/u +eth1 192.168.0.2/32 u/u +eth2 192.168.0.2/32 u/u +lo 127.0.0.1/8 u/u + 192.168.0.2/32 + ::1/128 +``` + +```none +vyos@vyos:~$ show ip route +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued route, r - rejected route + +S>* 0.0.0.0/0 [210/0] via 10.0.0.254, eth0, 00:57:34 +O 10.0.0.0/24 [110/20] via 192.168.0.1, eth1 onlink, 00:13:21 + via 192.168.0.1, eth2 onlink, 00:13:21 +C>* 10.0.0.0/24 is directly connected, eth0, 00:57:35 +O 192.168.0.2/32 [110/0] is directly connected, lo, 00:48:53 +C * 192.168.0.2/32 is directly connected, eth2, 00:56:31 +C * 192.168.0.2/32 is directly connected, eth1, 00:56:31 +C>* 192.168.0.2/32 is directly connected, lo, 00:57:36 +O>* 192.168.0.1/32 [110/1] via 192.168.0.1, eth1 onlink, 00:29:03 + * via 192.168.0.1, eth2 onlink, 00:29:03 +``` diff --git a/docs/configexamples/md-pppoe-ipv6-basic.md b/docs/configexamples/md-pppoe-ipv6-basic.md new file mode 100644 index 00000000..9b1503f3 --- /dev/null +++ b/docs/configexamples/md-pppoe-ipv6-basic.md @@ -0,0 +1,111 @@ +--- +lastproofread: '2021-06-29' +--- + +(examples-pppoe-ipv6-basic)= + +# PPPoE IPv6 Basic Setup for Home Network + +This document is to describe a basic setup using PPPoE with DHCPv6-PD + +SLAAC to construct a typical home network. The user can follow the steps +described here to quickly setup a working network and use this as a starting +point to further configure or fine-tune other settings. + +To achieve this, your ISP is required to support DHCPv6-PD. If you're not sure, +please contact your ISP for more information. + +## Network Topology + +```{image} /_static/images/pppoe-ipv6-pd-diagram.jpg +:align: center +:alt: Network Topology Diagram +:width: 60% +``` + +## Configurations + +### PPPoE Setup + +```none +set interfaces pppoe pppoe0 authentication password <YOUR PASSWORD> +set interfaces pppoe pppoe0 authentication user <YOUR USERNAME> +set interfaces pppoe pppoe0 service-name <YOUR SERVICENAME> +set interfaces pppoe pppoe0 source-interface 'eth0' +``` + +- Fill `password` and `user` with the credential provided by your ISP. +- `service-name` can be an arbitrary string. + +### DHCPv6-PD Setup + +During address configuration, in addition to assigning an address to the WAN +interface, ISP also provides a prefix to allow the router to configure addresses +of LAN interface and other nodes connecting to LAN, which is called prefix +delegation (PD). + +```none +set interfaces pppoe pppoe0 ipv6 address autoconf +set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth1 address '100' +``` + +- Here we use the prefix to configure the address of eth1 (LAN) to form + `<prefix>::64`, where `64` is hexadecimal of address 100. +- For home network users, most of time ISP only provides /64 prefix, hence + there is no need to set SLA ID and prefix length. See {ref}`pppoe-interface` + for more information. + +### Router Advertisement + +We need to enable router advertisement for LAN network so that PC can receive +the prefix and use SLAAC to configure the address automatically. + +```none +set service router-advert interface eth1 link-mtu '1492' +set service router-advert interface eth1 name-server <NAME SERVER> +set service router-advert interface eth1 prefix ::/64 valid-lifetime '172800' +``` + +- Set MTU in advertisement to 1492 because of PPPoE header overhead. +- Set DNS server address in the advertisement so that clients can obtain it by + using RDNSS option. Most operating systems (Windows, Linux, Mac) should + already support it. +- Here we set the prefix to `::/64` to indicate advertising any /64 prefix + the LAN interface is assigned. +- Since some ISPs disconnects continuous connection for every 2~3 days, we set + `valid-lifetime` to 2 days to allow PC for phasing out old address. + +### Basic Firewall + +To have basic protection while keeping IPv6 network functional, we need to: + +- Allow all established and related traffic for router and LAN +- Allow all icmpv6 packets for router and LAN +- Allow DHCPv6 packets for router + +```none +set firewall ipv6 name WAN_IN default-action 'drop' +set firewall ipv6 name WAN_IN rule 10 action 'accept' +set firewall ipv6 name WAN_IN rule 10 state established 'enable' +set firewall ipv6 name WAN_IN rule 10 state related 'enable' +set firewall ipv6 name WAN_IN rule 20 action 'accept' +set firewall ipv6 name WAN_IN rule 20 protocol 'icmpv6' +set firewall ipv6 name WAN_LOCAL default-action 'drop' +set firewall ipv6 name WAN_LOCAL rule 10 action 'accept' +set firewall ipv6 name WAN_LOCAL rule 10 state established 'enable' +set firewall ipv6 name WAN_LOCAL rule 10 state related 'enable' +set firewall ipv6 name WAN_LOCAL rule 20 action 'accept' +set firewall ipv6 name WAN_LOCAL rule 20 protocol 'icmpv6' +set firewall ipv6 name WAN_LOCAL rule 30 action 'accept' +set firewall ipv6 name WAN_LOCAL rule 30 destination port '546' +set firewall ipv6 name WAN_LOCAL rule 30 protocol 'udp' +set firewall ipv6 name WAN_LOCAL rule 30 source port '547' +set firewall ipv6 forward filter rule 10 action jump +set firewall ipv6 forward filter rule 10 jump-target 'WAN_IN' +set firewall ipv6 forward filter rule 10 inbound-interface name 'pppoe0' +set firewall ipv6 input filter rule 10 action jump +set firewall ipv6 input filter rule 10 jump-target 'WAN_LOCAL' +set firewall ipv6 input filter rule 10 inbound-interface name 'pppoe0' +``` + +Note to allow the router to receive DHCPv6 response from ISP. We need to allow +packets with source port 547 (server) and destination port 546 (client). diff --git a/docs/configexamples/md-qos.md b/docs/configexamples/md-qos.md new file mode 100644 index 00000000..c22a0a13 --- /dev/null +++ b/docs/configexamples/md-qos.md @@ -0,0 +1,187 @@ +--- +lastproofread: '2023-02-18' +--- + +(examples-qos)= + +# QoS example + +## Configuration 'dcsp' and shaper using QoS + +In this case, we'll try to make a simple lab using QoS and the general ability of the VyOS system. +We recommend you to go through the main article about [QoS](https://docs.vyos.io/en/latest/configuration/trafficpolicy/index.html) first. + +Using the general schema for example: + +```{image} /_static/images/qos1.png +:align: center +:alt: Network Topology Diagram +:width: 80% +``` + +We have four hosts on the local network 172.17.1.0/24. All hosts are labeled CS0 by default. We need to replace labels on all hosts except vpc8. +We will replace the labels on the nearest router “VyOS3” using the IP addresses of the sources. + +- 172.17.1.2 CS0 -> CS4 +- 172.17.1.3 CS0 -> CS5 +- 172.17.1.4 CS0 -> CS6 +- 172.17.1.40 CS0 by default + +Next, we will replace only all CS4 labels on the “VyOS2” router. + +- CS4 -> CS5 + +In the end, we will configure the traffic shaper using QoS mechanisms on the “VYOS2” router. + +## Configuration: + +Set IP addresses on all VPCs and a default gateway 172.17.1.1. We'll use in this case only static routes. +On the VyOS3 router, we need to change the 'dscp' labels for the VPCs. To do this, we use this configuration. + +```none +set interfaces ethernet eth0 address '10.1.1.100/24' +set interfaces ethernet eth1 address '172.17.1.1/24' +set protocols static route 0.0.0.0/0 next-hop 10.1.1.1 +set qos policy shaper vyos3 class 10 match ADDRESS10 ip source address '172.17.1.2/32' +set qos policy shaper vyos3 class 10 set-dscp 'CS4' +set qos policy shaper vyos3 class 20 match ADDRESS20 ip source address '172.17.1.3/32' +set qos policy shaper vyos3 class 20 set-dscp 'CS5' +set qos policy shaper vyos3 class 30 match ADDRESS20 ip source address '172.17.1.4/32' +set qos policy shaper vyos3 class 30 set-dscp 'CS6' +set qos policy shaper vyos3 default bandwidth '10%' +set qos policy shaper vyos3 default ceiling '100%' +set qos policy shaper vyos3 default priority '7' +set qos policy shaper vyos3 default queue-type 'fair-queue' +set qos interface eth0 egress 'vyos3' +``` + +Main rules: + +- ADDRESS10 change CS0 -> CS4 source 172.17.1.2/32 +- ADDRESS20 change CS0 -> CS5 source 172.17.1.3/32 +- ADDRESS30 change CS0 -> CS6 source 172.17.1.4/32 + +Check the result + +```{image} /_static/images/qos2.png +:align: center +:alt: Network Topology Diagram +:width: 80% +``` + +Before the interface eth0 on router VyOS3 + +```{image} /_static/images/qos3.png +:align: center +:alt: Network Topology Diagram +:width: 80% +``` + +After the interface eth0 on router VyOS3 + +```{image} /_static/images/qos4.png +:align: center +:alt: Network Topology Diagram +:width: 80% +``` + +On the router, VyOS4 set all traffic as CS4. We have to configure the default class and class for changing all labels from CS0 to CS4 + +```none +set interfaces ethernet eth0 address '10.2.1.100/24' +set protocols static route 0.0.0.0/0 next-hop 10.2.1.1 +set qos policy shaper vyos4 class 10 bandwidth '100%' +set qos policy shaper vyos4 class 10 burst '15k' +set qos policy shaper vyos4 class 10 match ALL ether protocol 'all' +set qos policy shaper vyos4 class 10 queue-type 'fair-queue' +set qos policy shaper vyos4 class 10 set-dscp 'CS4' +set qos policy shaper vyos4 default bandwidth '10%' +set qos policy shaper vyos4 default burst '15k' +set qos policy shaper vyos4 default ceiling '100%' +set qos policy shaper vyos4 default priority '7' +set qos policy shaper vyos4 default queue-type 'fair-queue' +set qos interface eth0 egress 'vyos4' +``` + +Next on the router VyOS2 we will change labels on all incoming traffic only from CS4-> CS6 + +```{image} /_static/images/qos5.png +:align: center +:alt: Network Topology Diagram +:width: 80% +``` + +```none +set interfaces ethernet eth0 address '10.1.1.1/24' +set interfaces ethernet eth1 address '10.2.1.1/24' +set interfaces ethernet eth2 address '10.9.9.1/24' +set protocols static route 172.17.1.0/24 next-hop 10.1.1.100 +set qos policy shaper vyos2 class 10 bandwidth '100%' +set qos policy shaper vyos2 class 10 burst '15k' +set qos policy shaper vyos2 class 10 match VYOS2 ip dscp 'CS4' +set qos policy shaper vyos2 class 10 queue-type 'fair-queue' +set qos policy shaper vyos2 class 10 set-dscp 'CS5' +set qos policy shaper vyos2 default bandwidth '100%' +set qos policy shaper vyos2 default burst '15k' +set qos policy shaper vyos2 default ceiling '100%' +set qos policy shaper vyos2 default priority '7' +set qos policy shaper vyos2 default queue-type 'fair-queue' +set qos interface eth2 egress 'vyos2' +``` + +```{image} /_static/images/qos6.png +:align: center +:alt: Network Topology Diagram +:width: 80% +``` + +- 172.17.1.2/24 CS0 + +```{image} /_static/images/qos7.png +:align: center +:alt: Network Topology Diagram +:width: 80% +``` + +- 172.17.1.2/24 CS0 - > CS4 + +```{image} /_static/images/qos8.png +:align: center +:alt: Network Topology Diagram +:width: 80% +``` + +- 172.17.1.2/24 CS4 - > CS5 + +```{image} /_static/images/qos9.png +:align: center +:alt: Network Topology Diagram +:width: 80% +``` + +In the end, on the router “VyOS2” we will set outgoing bandwidth limits between the “VyOS3” and “VyOS1” routers. Let's set a limit for IP 10.1.1.100 = 5 Mbps(Tx). We will check the result of the work with the help of the “iPerf” utility. + +Set up bandwidth limits on the eth2 interface of the router “VyOS2”. + +```none +vyos@vyos2# show qos policy shaper vyos2 class 20 +bandwidth 5mbit +description "for VyOS3 eth0" +match VyOS3 { + ip { + source { + address 10.1.1.100/32 + } + } +} +``` + +Check the result. + +```{image} /_static/images/qos10.png +:align: center +:alt: Network Topology Diagram +:width: 80% +``` + +As we see shaper is working and the traffic will not work over 5 Mbit/s. diff --git a/docs/configexamples/md-segment-routing-isis.md b/docs/configexamples/md-segment-routing-isis.md new file mode 100644 index 00000000..76cb726c --- /dev/null +++ b/docs/configexamples/md-segment-routing-isis.md @@ -0,0 +1,277 @@ +--- +lastproofread: '2023-04-10' +--- + +(examples-segment-routing-isis)= + +# Segment-routing IS-IS example + +When utilizing VyOS in an environment with Cisco IOS-XR gear you can use this +blue print as an initial setup to get MPLS ISIS-SR working between those two +devices.The lab was build using {abbr}`EVE-NG (Emulated Virtual +Environment NG)`. + +:::{figure} /_static/images/vyos-sr-isis.png +:alt: ISIS-SR network + +ISIS-SR example network +::: + +The below configuration is used as example where we keep focus on +VyOS-P1/VyOS-P2/XRv-P3 which we share the settings. + +## Configuration + +- VyOS-P1: + +```none +set interfaces dummy dum0 address '192.0.2.1/32' +set interfaces ethernet eth1 address '192.0.2.5/30' +set interfaces ethernet eth1 mtu '8000' +set interfaces ethernet eth3 address '192.0.2.21/30' +set interfaces ethernet eth3 mtu '8000' +set protocols isis interface dum0 passive +set protocols isis interface eth1 network point-to-point +set protocols isis interface eth3 network point-to-point +set protocols isis level 'level-2' +set protocols isis log-adjacency-changes +set protocols isis metric-style 'wide' +set protocols isis net '49.0000.0000.0000.0001.00' +set protocols isis segment-routing maximum-label-depth '8' +set protocols isis segment-routing prefix 192.0.2.1/32 index value '1' +set protocols mpls interface 'eth1' +set protocols mpls interface 'eth3' +set system host-name 'P1-VyOS' +``` + +- XRv-P3: + +```none +hostname P3-VyOS +interface Loopback0 + ipv4 address 192.0.2.3 255.255.255.255 +! +interface GigabitEthernet0/0/0/1 + mtu 8014 + ipv4 address 192.0.2.6 255.255.255.252 +! +interface GigabitEthernet0/0/0/2 + mtu 8014 + ipv4 address 192.0.2.18 255.255.255.252 +! +router isis VyOS + is-type level-2-only + net 49.0000.0000.0000.0003.00 + log adjacency changes + address-family ipv4 unicast + metric-style wide + segment-routing mpls + ! + interface Loopback0 + passive + address-family ipv4 unicast + prefix-sid index 3 + ! + ! + interface GigabitEthernet0/0/0/1 + point-to-point + address-family ipv4 unicast + ! + ! + interface GigabitEthernet0/0/0/2 + point-to-point + address-family ipv4 unicast + ! + ! +! +``` + +- VyOS-P2: + +```none +set interfaces dummy dum0 address '192.0.2.2/32' +set interfaces ethernet eth2 address '192.0.2.17/30' +set interfaces ethernet eth2 mtu '8000' +set interfaces ethernet eth3 address '192.0.2.26/30' +set interfaces ethernet eth3 mtu '8000' +set protocols isis interface dum0 passive +set protocols isis interface eth2 network point-to-point +set protocols isis interface eth3 network point-to-point +set protocols isis level 'level-2' +set protocols isis log-adjacency-changes +set protocols isis metric-style 'wide' +set protocols isis net '49.0000.0000.0000.0002.00' +set protocols isis segment-routing maximum-label-depth '8' +set protocols isis segment-routing prefix 192.0.2.2/32 index value '2' +set protocols mpls interface 'eth2' +set protocols mpls interface 'eth3' +set system host-name 'P2-VyOS' +``` + +This gives us MPLS segment routing enabled and labels forwarding : + +```none +vyos@P1-VyOS:~$ show mpls table +Inbound Label Type Nexthop Outbound Label +----------------------------------------------------------------- +15000 SR (IS-IS) 192.0.2.6 implicit-null +15001 SR (IS-IS) 192.0.2.22 implicit-null +15002 SR (IS-IS) fe80::5200:ff:fe04:3 implicit-null +16002 SR (IS-IS) 192.0.2.6 16002 +16003 SR (IS-IS) 192.0.2.6 implicit-null +16011 SR (IS-IS) 192.0.2.22 implicit-null + +vyos@P2-VyOS:~$ show mpls table +Inbound Label Type Nexthop Outbound Label +------------------------------------------------------- +15000 SR (IS-IS) 192.0.2.18 implicit-null +16001 SR (IS-IS) 192.0.2.18 16001 +16003 SR (IS-IS) 192.0.2.18 implicit-null +16011 SR (IS-IS) 192.0.2.18 16011 + +RP/0/0/CPU0:P3-VyOS#show mpls forwarding +Tue Mar 28 17:47:18.928 UTC +Local Outgoing Prefix Outgoing Next Hop Bytes +Label Label or ID Interface Switched +------ ----------- ------------------ ------------ --------------- ------------ +16001 Pop SR Pfx (idx 1) Gi0/0/0/1 192.0.2.5 0 +16002 Pop SR Pfx (idx 2) Gi0/0/0/2 192.0.2.17 0 +16011 16011 SR Pfx (idx 11) Gi0/0/0/1 192.0.2.5 0 +24000 Pop SR Adj (idx 1) Gi0/0/0/1 192.0.2.5 0 +24001 Pop SR Adj (idx 3) Gi0/0/0/1 192.0.2.5 0 +24002 Pop SR Adj (idx 1) Gi0/0/0/2 192.0.2.17 0 +24003 Pop SR Adj (idx 3) Gi0/0/0/2 192.0.2.17 0 +``` + +VyOS is able to check MSD per devices: + +```none +vyos@P1-VyOS:~$ show isis segment-routing node +Area VyOS: +IS-IS L1 SR-Nodes: + +IS-IS L2 SR-Nodes: + +System ID SRGB SRLB Algorithm MSD +--------------------------------------------------------------- +0000.0000.0001 16000 - 23999 15000 - 15999 SPF 8 +0000.0000.0002 16000 - 23999 15000 - 15999 SPF 8 +0000.0000.0003 16000 - 23999 0 - 4294967295 SPF 10 +0000.0000.0011 16000 - 23999 15000 - 15999 SPF 8 + +vyos@P2-VyOS:~$ show isis segment-routing node +Area VyOS: + IS-IS L1 SR-Nodes: + + IS-IS L2 SR-Nodes: + + System ID SRGB SRLB Algorithm MSD + --------------------------------------------------------------- + 0000.0000.0001 16000 - 23999 15000 - 15999 SPF 8 + 0000.0000.0002 16000 - 23999 15000 - 15999 SPF 8 + 0000.0000.0003 16000 - 23999 0 - 4294967295 SPF 10 + 0000.0000.0011 16000 - 23999 15000 - 15999 SPF 8 +``` + +Here is the routing tables showing the MPLS segment routing label operations: + +```none +vyos@P1-VyOS:~$ show ip route isis +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +I>* 192.0.2.2/32 [115/30] via 192.0.2.6, eth1, label 16002, weight 1, 1d03h18m +I>* 192.0.2.3/32 [115/10] via 192.0.2.6, eth1, label implicit-null, weight 1, 1d03h18m +I 192.0.2.4/30 [115/20] via 192.0.2.6, eth1 inactive, weight 1, 1d03h18m +I>* 192.0.2.11/32 [115/20] via 192.0.2.22, eth3, label implicit-null, weight 1, 1d02h47m +I>* 192.0.2.16/30 [115/20] via 192.0.2.6, eth1, weight 1, 1d03h18m +I 192.0.2.20/30 [115/20] via 192.0.2.22, eth3 inactive, weight 1, 1d02h48m +I>* 192.0.2.24/30 [115/30] via 192.0.2.6, eth1, weight 1, 1d03h18m + + +vyos@P2-VyOS:~$ show ip route isis +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +I>* 192.0.2.1/32 [115/30] via 192.0.2.18, eth2, label 16001, weight 1, 1d03h17m +I>* 192.0.2.3/32 [115/10] via 192.0.2.18, eth2, label implicit-null, weight 1, 1d03h17m +I>* 192.0.2.4/30 [115/20] via 192.0.2.18, eth2, weight 1, 1d03h17m +I>* 192.0.2.11/32 [115/40] via 192.0.2.18, eth2, label 16011, weight 1, 1d02h47m +I 192.0.2.16/30 [115/20] via 192.0.2.18, eth2 inactive, weight 1, 1d03h17m +I>* 192.0.2.20/30 [115/30] via 192.0.2.18, eth2, weight 1, 1d03h17m + +RP/0/0/CPU0:P3-VyOS#show route isis +Tue Mar 28 18:19:16.417 UTC + +i L2 192.0.2.1/32 [115/20] via 192.0.2.5, 1d03h, GigabitEthernet0/0/0/1 +i L2 192.0.2.2/32 [115/20] via 192.0.2.17, 1d03h, GigabitEthernet0/0/0/2 +i L2 192.0.2.11/32 [115/30] via 192.0.2.5, 1d02h, GigabitEthernet0/0/0/1 +i L2 192.0.2.20/30 [115/20] via 192.0.2.5, 1d03h, GigabitEthernet0/0/0/1 +i L2 192.0.2.24/30 [115/20] via 192.0.2.17, 1d03h, GigabitEthernet0/0/0/2 +``` + +Information about prefix-sid and label-operation from VyOS + +```none +vyos@P1-VyOS:~$ show isis route prefix-sid +Area VyOS: +IS-IS L2 IPv4 routing table: + + Prefix Metric Interface Nexthop SID Label Op. + ---------------------------------------------------------------------- + 192.0.2.1/32 0 - - - - + 192.0.2.2/32 30 eth1 192.0.2.6 2 Swap(16002, 16002) + 192.0.2.3/32 10 eth1 192.0.2.6 3 Pop(16003) + 192.0.2.4/30 20 eth1 192.0.2.6 - - + 192.0.2.16/30 20 eth1 192.0.2.6 - - + 192.0.2.20/30 0 - - - - + 192.0.2.24/30 30 eth1 192.0.2.6 - - + + vyos@P2-VyOS:~$ show isis route prefix-sid + Area VyOS: + IS-IS L2 IPv4 routing table: + + Prefix Metric Interface Nexthop SID Label Op. + ----------------------------------------------------------------------- + 192.0.2.1/32 30 eth2 192.0.2.18 1 Swap(16001, 16001) + 192.0.2.2/32 0 - - - - + 192.0.2.3/32 10 eth2 192.0.2.18 3 Pop(16003) + 192.0.2.4/30 20 eth2 192.0.2.18 - - + 192.0.2.16/30 20 eth2 192.0.2.18 - - + 192.0.2.20/30 30 eth2 192.0.2.18 - - + 192.0.2.24/30 0 - - - - +``` + +Ping between VyOS-P1 / VyOS-P2 to confirm reachability: + +```none +vyos@P1-VyOS:~$ ping 192.0.2.2 source-address 192.0.2.1 +PING 192.0.2.2 (192.0.2.2) from 192.0.2.1 : 56(84) bytes of data. +64 bytes from 192.0.2.2: icmp_seq=1 ttl=63 time=3.47 ms +64 bytes from 192.0.2.2: icmp_seq=2 ttl=63 time=2.06 ms +64 bytes from 192.0.2.2: icmp_seq=3 ttl=63 time=3.90 ms +64 bytes from 192.0.2.2: icmp_seq=4 ttl=63 time=3.87 ms +^C +--- 192.0.2.2 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 3004ms +rtt min/avg/max/mdev = 2.064/3.326/3.903/0.748 ms + +vyos@P2-VyOS:~$ ping 192.0.2.1 source-address 192.0.2.2 +PING 192.0.2.1 (192.0.2.1) from 192.0.2.2 : 56(84) bytes of data. +64 bytes from 192.0.2.1: icmp_seq=1 ttl=63 time=2.91 ms +64 bytes from 192.0.2.1: icmp_seq=2 ttl=63 time=3.23 ms +64 bytes from 192.0.2.1: icmp_seq=3 ttl=63 time=2.91 ms +64 bytes from 192.0.2.1: icmp_seq=4 ttl=63 time=2.85 ms +^C +--- 192.0.2.1 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 3005ms +rtt min/avg/max/mdev = 2.846/2.972/3.231/0.151 ms +``` diff --git a/docs/configexamples/md-wan-load-balancing.md b/docs/configexamples/md-wan-load-balancing.md new file mode 100644 index 00000000..e35b9056 --- /dev/null +++ b/docs/configexamples/md-wan-load-balancing.md @@ -0,0 +1,175 @@ +--- +lastproofread: '2021-06-29' +--- + +(wan-load-balancing)= + + +# WAN Load Balancer examples + +## Example 1: Distributing load evenly + +The setup used in this example is shown in the following diagram: + +```{image} /_static/images/Wan_load_balancing1.png +:align: center +:alt: Network Topology Diagram +:width: 80% +``` + +### Overview + +> - All traffic coming in through eth2 is balanced between eth0 and eth1 +> on the router. +> - Pings will be sent to four targets for health testing (33.44.55.66, +> 44.55.66.77, 55.66.77.88 and 66.77.88.99). +> - All outgoing packets are assigned the source address of the assigned +> interface (SNAT). +> - eth0 is set to be removed from the load balancer's interface pool +> after 5 ping failures, eth1 will be removed after 4 ping failures. + +### Create static routes to ping targets + +Create static routes through the two ISPs towards the ping targets and +commit the changes: + +```none +set protocols static route 33.44.55.66/32 next-hop 11.22.33.1 +set protocols static route 44.55.66.77/32 next-hop 11.22.33.1 +set protocols static route 55.66.77.88/32 next-hop 22.33.44.1 +set protocols static route 66.77.88.99/32 next-hop 22.33.44.1 +``` + +### Configure the load balancer + +Configure the WAN load balancer with the parameters described above: + +```none +set load-balancing wan interface-health eth0 failure-count 5 +set load-balancing wan interface-health eth0 nexthop 11.22.33.1 +set load-balancing wan interface-health eth0 test 10 type ping +set load-balancing wan interface-health eth0 test 10 target 33.44.55.66 +set load-balancing wan interface-health eth0 test 20 type ping +set load-balancing wan interface-health eth0 test 20 target 44.55.66.77 +set load-balancing wan interface-health eth1 failure-count 4 +set load-balancing wan interface-health eth1 nexthop 22.33.44.1 +set load-balancing wan interface-health eth1 test 10 type ping +set load-balancing wan interface-health eth1 test 10 target 55.66.77.88 +set load-balancing wan interface-health eth1 test 20 type ping +set load-balancing wan interface-health eth1 test 20 target 66.77.88.99 +set load-balancing wan rule 10 inbound-interface eth2 +set load-balancing wan rule 10 interface eth0 +set load-balancing wan rule 10 interface eth1 +``` + +## Example 2: Failover based on interface weights + +This example uses the failover mode. + +(wan-example2-overwiew)= + +### Overview + +In this example, eth0 is the primary interface and eth1 is the secondary +interface. To provide simple failover functionality. If eth0 fails, eth1 +takes over. + +### Create interface weight based configuration + +The configuration steps are the same as in the previous example, except +rule 10. So we keep the configuration, remove rule 10 and add a new rule +for the failover mode: + +```none +delete load-balancing wan rule 10 +set load-balancing wan rule 10 failover +set load-balancing wan rule 10 inbound-interface eth2 +set load-balancing wan rule 10 interface eth0 weight 10 +set load-balancing wan rule 10 interface eth1 weight 1 +``` + +## Example 3: Failover based on rule order + +The previous example used the failover command to send traffic through +eth1 if eth0 fails. In this example, failover functionality is provided +by rule order. + +(wan-example3-overwiew)= + +### Overview + +Two rules will be created, the first rule directs traffic coming in +from eth2 to eth0 and the second rule directs the traffic to eth1. If +eth0 fails the first rule is bypassed and the second rule matches, +directing traffic to eth1. + +### Create rule order based configuration + +We keep the configuration from the previous example, delete rule 10 +and create the two new rules as described: + +```none +delete load-balancing wan rule 10 +set load-balancing wan rule 10 inbound-interface eth2 +set load-balancing wan rule 10 interface eth0 +set load-balancing wan rule 20 inbound-interface eth2 +set load-balancing wan rule 20 interface eth1 +``` + +## Example 4: Failover based on rule order - priority traffic + +A rule order for prioritizing traffic is useful in scenarios where the +secondary link has a lower speed and should only carry high priority +traffic. It is assumed for this example that eth1 is connected to a +slower connection than eth0 and should prioritize VoIP traffic. + +(wan-example4-overwiew)= + +### Overview + +A rule order for prioritizing traffic is useful in scenarios where the +secondary link has a lower speed and should only carry high priority +traffic. It is assumed for this example that eth1 is connected to a +slower connection than eth0 and should prioritize VoIP traffic. + +### Create rule order based configuration with low speed secondary link + +We keep the configuration from the previous example, delete rule 20 and +create a new rule as described: + +```none +delete load-balancing wan rule 20 +set load-balancing wan rule 20 inbound-interface eth2 +set load-balancing wan rule 20 interface eth1 +set load-balancing wan rule 20 destination port sip +set load-balancing wan rule 20 protocol tcp +set protocols static route 0.0.0.0/0 next-hop 11.22.33.1 +``` + +## Example 5: Exclude traffic from load balancing + +In this example two LAN interfaces exist in different subnets instead +of one like in the previous examples: + +```{image} /_static/images/Wan_load_balancing_exclude1.png +:align: center +:alt: Network Topology Diagram +:width: 80% +``` + +### Adding a rule for the second interface + +Based on the previous example, another rule for traffic from the second +interface eth3 can be added to the load balancer. However, traffic meant +to flow between the LAN subnets will be sent to eth0 and eth1 as well. +To prevent this, another rule is required. This rule excludes traffic +between the local subnets from the load balancer. It also excludes +locally-sources packets (required for web caching with load balancing). +eth+ is used as an alias that refers to all ethernet interfaces: + +```none +set load-balancing wan rule 5 exclude +set load-balancing wan rule 5 inbound-interface eth+ +set load-balancing wan rule 5 destination address 10.0.0.0/8 +``` + diff --git a/docs/configexamples/md-zone-policy.md b/docs/configexamples/md-zone-policy.md new file mode 100644 index 00000000..d9c22c09 --- /dev/null +++ b/docs/configexamples/md-zone-policy.md @@ -0,0 +1,415 @@ +--- +lastproofread: '2024-06-14' +--- + +(examples-zone-policy)= + +# Zone-Policy example + +:::{note} +In {vytask}`T2199` the syntax of the zone configuration was changed. +The zone configuration moved from `zone-policy zone <name>` to `firewall +zone <name>`. +::: + +## Native IPv4 and IPv6 + +We have three networks. + +```none +WAN - 172.16.10.0/24, 2001:0DB8:0:9999::0/64 +LAN - 192.168.100.0/24, 2001:0DB8:0:AAAA::0/64 +DMZ - 192.168.200.0/24, 2001:0DB8:0:BBBB::0/64 +``` + +**This specific example is for a router on a stick, but is very easily +adapted for however many NICs you have**: + +- Internet - 192.168.200.100 - TCP/80 +- Internet - 192.168.200.100 - TCP/443 +- Internet - 192.168.200.100 - TCP/25 +- Internet - 192.168.200.100 - TCP/53 +- VyOS acts as DHCP, DNS forwarder, NAT, router and firewall. +- 192.168.200.200/2001:0DB8:0:BBBB::200 is an internal/external DNS, web + and mail (SMTP/IMAP) server. +- 192.168.100.10/2001:0DB8:0:AAAA::10 is the administrator's console. It + can SSH to VyOS. +- LAN and DMZ hosts have basic outbound access: Web, FTP, SSH. +- LAN can access DMZ resources. +- DMZ cannot access LAN resources. +- Inbound WAN connect to DMZ host. + +```{image} /_static/images/zone-policy-diagram.png +:align: center +:alt: Network Topology Diagram +:width: 80% +``` + +The VyOS interface is assigned the .1/:1 address of their respective +networks. WAN is on VLAN 10, LAN on VLAN 20, and DMZ on VLAN 30. + +It will look something like this: + +```none +interfaces { + ethernet eth0 { + duplex auto + hw-id 00:53:ed:6e:2a:92 + smp_affinity auto + speed auto + vif 10 { + address 172.16.10.1/24 + address 2001:db8:0:9999::1/64 + } + vif 20 { + address 192.168.100.1/24 + address 2001:db8:0:AAAA::1/64 + } + vif 30 { + address 192.168.200.1/24 + address 2001:db8:0:BBBB::1/64 + } + } + loopback lo { + } +} +``` + +## Zones Basics + +Each interface is assigned to a zone. The interface can be physical or +virtual such as tunnels (VPN, PPTP, GRE, etc) and are treated exactly +the same. + +Traffic flows from zone A to zone B. That flow is what I refer to as a +zone-pair-direction. eg. A->B and B->A are two zone-pair-destinations. + +Ruleset are created per zone-pair-direction. + +I name rule sets to indicate which zone-pair-direction they represent. +eg. ZoneA-ZoneB or ZoneB-ZoneA. LAN-DMZ, DMZ-LAN. + +In VyOS, you have to have unique Ruleset names. In the event of overlap, +I add a "-6" to the end of v6 rulesets. eg. LAN-DMZ, LAN-DMZ-6. This +allows for each auto-completion and uniqueness. + +In this example we have 4 zones. LAN, WAN, DMZ, Local. The local zone is +the firewall itself. + +If your computer is on the LAN and you need to SSH into your VyOS box, +you would need a rule to allow it in the LAN-Local ruleset. If you want +to access a webpage from your VyOS box, you need a rule to allow it in +the Local-LAN ruleset. + +In rules, it is good to keep them named consistently. As the number of +rules you have grows, the more consistency you have, the easier your +life will be. + +```none +Rule 1 - State Established, Related +Rule 2 - State Invalid +Rule 100 - ICMP +Rule 200 - Web +Rule 300 - FTP +Rule 400 - NTP +Rule 500 - SMTP +Rule 600 - DNS +Rule 700 - DHCP +Rule 800 - SSH +Rule 900 - IMAPS +``` + +The first two rules are to deal with the idiosyncrasies of VyOS and +iptables. + +Zones and Rulesets both have a default action statement. When using +Zone-Policies, the default action is set by the zone-policy statement +and is represented by rule 10000. + +It is good practice to log both accepted and denied traffic. It can save +you significant headaches when trying to troubleshoot a connectivity +issue. + +To add logging to the default rule, do: + +```none +set firewall name <ruleSet> default-log +``` + +By default, iptables does not allow traffic for established sessions to +return, so you must explicitly allow this. I do this by adding two rules +to every ruleset. 1 allows established and related state packets through +and rule 2 drops and logs invalid state packets. We place the +established/related rule at the top because the vast majority of traffic +on a network is established and the invalid rule to prevent invalid +state packets from mistakenly being matched against other rules. Having +the most matched rule listed first reduces CPU load in high volume +environments. Note: I have filed a bug to have this added as a default +action as well. + +''It is important to note, that you do not want to add logging to the +established state rule as you will be logging both the inbound and +outbound packets for each session instead of just the initiation of the +session. Your logs will be massive in a very short period of time.'' + +In VyOS you must have the interfaces created before you can apply it to +the zone and the rulesets must be created prior to applying it to a +zone-policy. + +I create/configure the interfaces first. Build out the rulesets for each +zone-pair-direction which includes at least the three state rules. Then +I setup the zone-policies. + +Zones do not allow for a default action of accept; either drop or +reject. It is important to remember this because if you apply an +interface to a zone and commit, any active connections will be dropped. +Specifically, if you are SSH’d into VyOS and add local or the interface +you are connecting through to a zone and do not have rulesets in place +to allow SSH and established sessions, you will not be able to connect. + +The following are the rules that were created for this example (may not +be complete), both in IPv4 and IPv6. If there is no IP specified, then +the source/destination address is not explicit. + +```none +WAN - DMZ:192.168.200.200 - tcp/80 +WAN - DMZ:192.168.200.200 - tcp/443 +WAN - DMZ:192.168.200.200 - tcp/25 +WAN - DMZ:192.168.200.200 - tcp/53 +WAN - DMZ:2001:0DB8:0:BBBB::200 - tcp/80 +WAN - DMZ:2001:0DB8:0:BBBB::200 - tcp/443 +WAN - DMZ:2001:0DB8:0:BBBB::200 - tcp/25 +WAN - DMZ:2001:0DB8:0:BBBB::200 - tcp/53 + +DMZ - Local - tcp/53 +DMZ - Local - tcp/123 +DMZ - Local - tcp/67,68 + +LAN - Local - tcp/53 +LAN - Local - tcp/123 +LAN - Local - tcp/67,68 +LAN:192.168.100.10 - Local - tcp/22 +LAN:2001:0DB8:0:AAAA::10 - Local - tcp/22 + +LAN - WAN - tcp/80 +LAN - WAN - tcp/443 +LAN - WAN - tcp/22 +LAN - WAN - tcp/20,21 + +DMZ - WAN - tcp/80 +DMZ - WAN - tcp/443 +DMZ - WAN - tcp/22 +DMZ - WAN - tcp/20,21 +DMZ - WAN - tcp/53 +DMZ - WAN - udp/53 + +Local - WAN - tcp/80 +Local - WAN - tcp/443 +Local - WAN - tcp/20,21 + +Local - DMZ - tcp/25 +Local - DMZ - tcp/67,68 +Local - DMZ - tcp/53 +Local - DMZ - udp/53 + +Local - LAN - tcp/67,68 + +LAN - DMZ - tcp/80 +LAN - DMZ - tcp/443 +LAN - DMZ - tcp/993 +LAN:2001:0DB8:0:AAAA::10 - DMZ:2001:0DB8:0:BBBB::200 - tcp/22 +LAN:192.168.100.10 - DMZ:192.168.200.200 - tcp/22 +``` + +Since we have 4 zones, we need to setup the following rulesets. + +```none +Lan-wan +Lan-local +Lan-dmz +Wan-lan +Wan-local +Wan-dmz +Local-lan +Local-wan +Local-dmz +Dmz-lan +Dmz-wan +Dmz-local +``` + +Even if the two zones will never communicate, it is a good idea to +create the zone-pair-direction rulesets and set default-log. This +will allow you to log attempts to access the networks. Without it, you +will never see the connection attempts. + +This is an example of the three base rules. + +```none +name wan-lan { + default-action drop + default-log + rule 1 { + action accept + state { + established enable + related enable + } + } + rule 2 { + action drop + log enable + state { + invalid enable + } + } +} +``` + +Here is an example of an IPv6 DMZ-WAN ruleset. + +```none +ipv6-name dmz-wan-6 { + default-action drop + default-log + rule 1 { + action accept + state { + established enable + related enable + } + } + rule 2 { + action drop + log enable + state { + invalid enable + } + rule 100 { + action accept + log enable + protocol ipv6-icmp + } + rule 200 { + action accept + destination { + port 80,443 + } + log enable + protocol tcp + } + rule 300 { + action accept + destination { + port 20,21 + } + log enable + protocol tcp + } + rule 500 { + action accept + destination { + port 25 + } + log enable + protocol tcp + source { + address 2001:db8:0:BBBB::200 + } + } + rule 600 { + action accept + destination { + port 53 + } + log enable + protocol tcp_udp + source { + address 2001:db8:0:BBBB::200 + } + } + rule 800 { + action accept + destination { + port 22 + } + log enable + protocol tcp + } +} +``` + +Once you have all of your rulesets built, then you need to create your +zone-policy. + +Start by setting the interface and default action for each zone. + +```none +set firewall zone dmz default-action drop +set firewall zone dmz interface eth0.30 +``` + +In this case, we are setting the v6 ruleset that represents traffic +sourced from the LAN, destined for the DMZ. Because the zone-policy +firewall syntax is a little awkward, I keep it straight by thinking of +it backwards. + +```none +set firewall zone dmz from lan firewall ipv6-name lan-dmz-6 +``` + +DMZ-LAN policy is LAN-DMZ. You can get a rhythm to it when you build out +a bunch at one time. + +In the end, you will end up with something like this config. I took out +everything but the Firewall, Interfaces, and zone-policy sections. It is +long enough as is. + +## IPv6 Tunnel + +If you are using a IPv6 tunnel from HE.net or someone else, the basis is +the same except you have two WAN interfaces. One for v4 and one for v6. + +You would have 5 zones instead of just 4 and you would configure your v6 +ruleset between your tunnel interface and your LAN/DMZ zones instead of +to the WAN. + +LAN, WAN, DMZ, local and TUN (tunnel) + +v6 pairs would be: + +```none +lan-tun +lan-local +lan-dmz +tun-lan +tun-local +tun-dmz +local-lan +local-tun +local-dmz +dmz-lan +dmz-tun +dmz-local +``` + +Notice, none go to WAN since WAN wouldn't have a v6 address on it. + +You would have to add a couple of rules on your wan-local ruleset to +allow protocol 41 in. + +Something like: + +```none +rule 400 { + action accept + destination { + address 172.16.10.1 + } + log enable + protocol 41 + source { + address ip.of.tunnel.broker + } +} +``` diff --git a/docs/configuration/container/md-index.md b/docs/configuration/container/md-index.md new file mode 100644 index 00000000..c5163a99 --- /dev/null +++ b/docs/configuration/container/md-index.md @@ -0,0 +1,406 @@ +--- +lastproofread: '2022-06-10' +--- + +# Container + +The VyOS container implementation is based on `Podman<https://podman.io/>` as +a deamonless container engine. + +## Configuration + +```{eval-rst} +.. cfgcmd:: set container name <name> image + + Sets the image name in the hub registry + + .. code-block:: none + + set container name mysql-server image mysql:8.0 + + If a registry is not specified, Docker.io will be used as the container + registry unless an alternative registry is specified using + **set container registry <name>** or the registry is included + in the image name + + .. code-block:: none + + set container name mysql-server image quay.io/mysql:8.0 +``` + +```{eval-rst} +.. cfgcmd:: set container name <name> entrypoint <entrypoint> + + Override the default entrypoint from the image for a container. +``` + +```{eval-rst} +.. cfgcmd:: set container name <name> command <command> + + Override the default command from the image for a container. +``` + +```{eval-rst} +.. cfgcmd:: set container name <name> arguments <arguments> + + Set the command arguments for a container. +``` + +```{eval-rst} +.. cfgcmd:: set container name <name> host-name <hostname> + + Set the host name for a container. +``` + +```{eval-rst} +.. cfgcmd:: set container name <name> allow-host-pid + + The container and the host share the same process namespace. + This means that processes running on the host are visible inside the + container, and processes inside the container are visible on the host. + + The command translates to "--pid host" when the container is created. +``` + +```{eval-rst} +.. cfgcmd:: set container name <name> allow-host-networks + + Allow host networking in a container. The network stack of the container is + not isolated from the host and will use the host IP. + + The command translates to "--net host" when the container is created. + + .. note:: **allow-host-networks** cannot be used with **network** +``` + +```{eval-rst} +.. cfgcmd:: set container name <name> network <networkname> + + Attaches user-defined network to a container. + Only one network must be specified and must already exist. +``` + +```{eval-rst} +.. cfgcmd:: set container name <name> network <networkname> address <address> + + Optionally set a specific static IPv4 or IPv6 address for the container. + This address must be within the named network prefix. + + .. note:: The first IP in the container network is reserved by the + engine and cannot be used +``` + +```{eval-rst} +.. cfgcmd:: set container name <name> description <text> + + Set a container description +``` + +```{eval-rst} +.. cfgcmd:: set container name <name> environment <key> value <value> + + Add custom environment variables. + Multiple environment variables are allowed. + The following commands translate to "-e key=value" when the container + is created. + + .. code-block:: none + + set container name mysql-server environment MYSQL_DATABASE value 'zabbix' + set container name mysql-server environment MYSQL_USER value 'zabbix' + set container name mysql-server environment MYSQL_PASSWORD value 'zabbix_pwd' + set container name mysql-server environment MYSQL_ROOT_PASSWORD value 'root_pwd' +``` + +```{eval-rst} +.. cfgcmd:: set container name <name> port <portname> source <portnumber> +``` + +```{eval-rst} +.. cfgcmd:: set container name <name> port <portname> destination <portnumber> +``` + +```{eval-rst} +.. cfgcmd:: set container name <name> port <portname> protocol <tcp | udp> + + Publish a port for the container. + + .. code-block:: none + + set container name zabbix-web-nginx-mysql port http source 80 + set container name zabbix-web-nginx-mysql port http destination 8080 + set container name zabbix-web-nginx-mysql port http protocol tcp +``` + +```{eval-rst} +.. cfgcmd:: set container name <name> volume <volumename> source <path> +``` + +```{eval-rst} +.. cfgcmd:: set container name <name> volume <volumename> destination <path> + + Mount a volume into the container + + .. code-block:: none + + set container name coredns volume 'corefile' source /config/coredns/Corefile + set container name coredns volume 'corefile' destination /etc/Corefile +``` + +```{eval-rst} +.. cfgcmd:: set container name <name> volume <volumename> mode <ro | rw> + + Volume is either mounted as rw (read-write - default) or ro (read-only) +``` + +```{eval-rst} +.. cfgcmd:: set container name <name> uid <number> +``` + +```{eval-rst} +.. cfgcmd:: set container name <name> gid <number> + + Set the User ID or Group ID of the container +``` + +```{eval-rst} +.. cfgcmd:: set container name <name> restart [no | on-failure | always] + + Set the restart behavior of the container. + + - **no**: Do not restart containers on exit + - **on-failure**: Restart containers when they exit with a non-zero + exit code, retrying indefinitely (default) + - **always**: Restart containers when they exit, regardless of status, + retrying indefinitely +``` + +```{eval-rst} +.. cfgcmd:: set container name <name> cpu-quota <num> + + This specifies the number of CPU resources the container can use. + + Default is 0 for unlimited. + For example, 1.25 limits the container to use up to 1.25 cores + worth of CPU time. + This can be a decimal number with up to three decimal places. + + The command translates to "--cpus=<num>" when the container is created. +``` + +```{eval-rst} +.. cfgcmd:: set container name <name> memory <MB> + + Constrain the memory available to the container. + + Default is 512 MB. Use 0 MB for unlimited memory. +``` + +```{eval-rst} +.. cfgcmd:: set container name <name> device <devicename> source <path> +``` + +```{eval-rst} +.. cfgcmd:: set container name <name> device <devicename> destination <path> + + Add a host device to the container. +``` + +```{eval-rst} +.. cfgcmd:: set container name <name> capability <text> + + Set container capabilities or permissions. + + - **net-admin**: Network operations (interface, firewall, routing tables) + - **net-bind-service**: Bind a socket to privileged ports + (port numbers less than 1024) + - **net-raw**: Permission to create raw network sockets + - **setpcap**: Capability sets (from bounded or inherited set) + - **sys-admin**: Administration operations (quotactl, mount, sethostname, + setdomainame) + - **sys-time**: Permission to set system clock +``` + +```{eval-rst} +.. cfgcmd:: set container name <name> sysctl parameter <parameter> value <value> + + Set container sysctl values. + + The subset of possible parameters are: + + - Kernel Parameters: kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, + kernel.shmall, kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced + - Parameters beginning with fs.mqueue.* + - Parameters beginning with net.* (only if user-defined network is used) +``` + +```{eval-rst} +.. cfgcmd:: set container name <name> label <label> value <value> + + Add metadata label for this container. +``` + +```{eval-rst} +.. cfgcmd:: set container name <name> disable + + Disable a container. +``` + +### Container Networks + +```{eval-rst} +.. cfgcmd:: set container network <name> + + Creates a named container network +``` + +```{eval-rst} +.. cfgcmd:: set container network <name> description + + A brief description what this network is all about. +``` + +```{eval-rst} +.. cfgcmd:: set container network <name> prefix <ipv4|ipv6> + + Define IPv4 and/or IPv6 prefix for a given network name. + Both IPv4 and IPv6 can be used in parallel. +``` + +```{eval-rst} +.. cfgcmd:: set container network <name> vrf <nme> + + Bind container network to a given VRF instance. +``` + +### Container Registry + +```{eval-rst} +.. cfgcmd:: set container registry <name> + + Adds registry to list of unqualified-search-registries. By default, for any + image that does not include the registry in the image name, VyOS will use + docker.io and quay.io as the container registry. +``` + +```{eval-rst} +.. cfgcmd:: set container registry <name> disable + + Disable a given container registry +``` + +```{eval-rst} +.. cfgcmd:: set container registry <name> authentication username +``` + +```{eval-rst} +.. cfgcmd:: set container registry <name> authentication password + + Some container registries require credentials to be used. + + Credentials can be defined here and will only be used when adding a + container image to the system. + +``` + +## Operation Commands + +```{eval-rst} +.. opcmd:: add container image <containername> + + Pull a new image for container +``` + +```{eval-rst} +.. opcmd:: show container + + Show the list of all active containers. +``` + +```{eval-rst} +.. opcmd:: show container image + + Show the local container images. +``` + +```{eval-rst} +.. opcmd:: show container log <containername> + + Show logs from a given container +``` + +```{eval-rst} +.. opcmd:: show container network + + Show a list available container networks +``` + +```{eval-rst} +.. opcmd:: restart container <containername> + + Restart a given container +``` + +```{eval-rst} +.. opcmd:: update container image <containername> + + Update container image +``` + +```{eval-rst} +.. opcmd:: delete container image <image id|all> [force] + + Delete a particular container image based on it's image ID. + You can also delete all container images at once. + + You can not delete a container image if it has more then one tag + assigned, this is why there is a `force` option to pass down to + the container image to also remove those images. +``` + +## Example Configuration + +> For the sake of demonstration, [example #1 in the official documentation](https://www.zabbix.com/documentation/current/manual/installation/containers) +> to the declarative VyOS CLI syntax. +> +> ```none +> set container network zabbix prefix 172.20.0.0/16 +> set container network zabbix description 'Network for Zabbix component containers' +> +> set container name mysql-server image mysql:8.0 +> set container name mysql-server network zabbix +> +> set container name mysql-server environment 'MYSQL_DATABASE' value 'zabbix' +> set container name mysql-server environment 'MYSQL_USER' value 'zabbix' +> set container name mysql-server environment 'MYSQL_PASSWORD' value 'zabbix_pwd' +> set container name mysql-server environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' +> +> set container name zabbix-java-gateway image zabbix/zabbix-java-gateway:alpine-5.2-latest +> set container name zabbix-java-gateway network zabbix +> +> set container name zabbix-server-mysql image zabbix/zabbix-server-mysql:alpine-5.2-latest +> set container name zabbix-server-mysql network zabbix +> +> set container name zabbix-server-mysql environment 'DB_SERVER_HOST' value 'mysql-server' +> set container name zabbix-server-mysql environment 'MYSQL_DATABASE' value 'zabbix' +> set container name zabbix-server-mysql environment 'MYSQL_USER' value 'zabbix' +> set container name zabbix-server-mysql environment 'MYSQL_PASSWORD' value 'zabbix_pwd' +> set container name zabbix-server-mysql environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' +> set container name zabbix-server-mysql environment 'ZBX_JAVAGATEWAY' value 'zabbix-java-gateway' +> +> set container name zabbix-server-mysql port zabbix source 10051 +> set container name zabbix-server-mysql port zabbix destination 10051 +> +> set container name zabbix-web-nginx-mysql image zabbix/zabbix-web-nginx-mysql:alpine-5.2-latest +> set container name zabbix-web-nginx-mysql network zabbix +> +> set container name zabbix-web-nginx-mysql environment 'MYSQL_DATABASE' value 'zabbix' +> set container name zabbix-web-nginx-mysql environment 'ZBX_SERVER_HOST' value 'zabbix-server-mysql' +> set container name zabbix-web-nginx-mysql environment 'DB_SERVER_HOST' value 'mysql-server' +> set container name zabbix-web-nginx-mysql environment 'MYSQL_USER' value 'zabbix' +> set container name zabbix-web-nginx-mysql environment 'MYSQL_PASSWORD' value 'zabbix_pwd' +> set container name zabbix-web-nginx-mysql environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' +> +> set container name zabbix-web-nginx-mysql port http source 80 +> set container name zabbix-web-nginx-mysql port http destination 8080 +> ``` diff --git a/docs/configuration/firewall/md-bridge.md b/docs/configuration/firewall/md-bridge.md new file mode 100644 index 00000000..ebb9287d --- /dev/null +++ b/docs/configuration/firewall/md-bridge.md @@ -0,0 +1,543 @@ +--- +lastproofread: '2023-11-08' +--- + +(firewall-configuration)= + +# Bridge Firewall Configuration + +:::{note} +**Documentation under development** +::: + +## Overview + +In this section there's useful information of all firewall configuration that +can be done regarding bridge, and appropiate op-mode commands. +Configuration commands covered in this section: + +```{eval-rst} +.. cfgcmd:: set firewall bridge ... +``` + +From main structure defined in {doc}`Firewall Overview</configuration/firewall/index>` +in this section you can find detailed information only for the next part +of the general structure: + +```none +- set firewall + * bridge + - forward + + filter + - name + + custom_name +``` + +Traffic which is received by the router on an interface which is member of a +bridge is processed on the **Bridge Layer**. A simplified packet flow diagram +for this layer is shown next: + +:::{figure} /_static/images/firewall-bridge-packet-flow.png +::: + +For traffic that needs to be forwared internally by the bridge, base chain is +is **forward**, and it's base command for filtering is `set firewall bridge +forward filter ...`, which happens in stage 4, highlightened with red color. + +Custom bridge firewall chains can be create with command `set firewall bridge +name <name> ...`. In order to use such custom chain, a rule with action jump, +and the appropiate target should be defined in a base chain. + +:::{note} +**Layer 3 bridge**: +When an IP address is assigned to the bridge interface, and if traffic +is sent to the router to this IP (for example using such IP as +default gateway), then rules defined for **bridge firewall** won't +match, and firewall analysis continues at **IP layer**. +::: + +## Bridge Rules + +For firewall filtering, firewall rules needs to be created. Each rule is +numbered, has an action to apply if the rule is matched, and the ability +to specify multiple criteria matchers. Data packets go through the rules +from 1 - 999999, so order is crucial. At the first match the action of the +rule will be executed. + +### Actions + +If a rule is defined, then an action must be defined for it. This tells the +firewall what to do if all criteria matchers defined for such rule do match. + +In firewall bridge rules, the action can be: + +> - `accept`: accept the packet. +> - `continue`: continue parsing next rule. +> - `drop`: drop the packet. +> - `jump`: jump to another custom chain. +> - `return`: Return from the current chain and continue at the next rule +> of the last chain. +> - `queue`: Enqueue packet to userspace. + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> action + [accept | continue | drop | jump | queue | return] +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge name <name> rule <1-999999> action + [accept | continue | drop | jump | queue | return] + + This required setting defines the action of the current rule. If action is + set to jump, then jump-target is also needed. +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + jump-target <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge name <name> rule <1-999999> + jump-target <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + queue <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge name <name> rule <1-999999> + queue <0-65535> + + To be used only when action is set to ``queue``. Use this command to specify + queue target to use. Queue range is also supported. +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + queue-options bypass +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge name <name> rule <1-999999> + queue-options bypass + + To be used only when action is set to ``queue``. Use this command to let + packet go through firewall when no userspace software is connected to the + queue. +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + queue-options fanout +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge name <name> rule <1-999999> + queue-options fanout + + To be used only when action is set to ``queue``. Use this command to + distribute packets between several queues. +``` + +Also, **default-action** is an action that takes place whenever a packet does +not match any rule in it's chain. For base chains, possible options for +**default-action** are **accept** or **drop**. + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter default-action + [accept | drop] +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge name <name> default-action + [accept | continue | drop | jump | queue | return] + + This set the default action of the rule-set if no rule matched a packet + criteria. If default-action is set to ``jump``, then + ``default-jump-target`` is also needed. Note that for base chains, default + action can only be set to ``accept`` or ``drop``, while on custom chain, + more actions are available. +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge name <name> default-jump-target <text> + + To be used only when ``defult-action`` is set to ``jump``. Use this + command to specify jump target for default rule. +``` + +:::{note} +**Important note about default-actions:** +If default action for any base chain is not defined, then the default +action is set to **accept** for that chain. For custom chains, if default +action is not defined, then the default-action is set to **drop**. +::: + +### Firewall Logs + +Logging can be enable for every single firewall rule. If enabled, other +log options can be defined. + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> log +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge name <name> rule <1-999999> log + + Enable logging for the matched packet. If this configuration command is not + present, then log is not enabled. +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter default-log +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge name <name> default-log + + Use this command to enable the logging of the default action on + the specified chain. +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + log-options level [emerg | alert | crit | err | warn | notice + | info | debug] +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge name <name> rule <1-999999> + log-options level [emerg | alert | crit | err | warn | notice + | info | debug] + + Define log-level. Only applicable if rule log is enable. +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + log-options group <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge name <name> rule <1-999999> + log-options group <0-65535> + + Define log group to send message to. Only applicable if rule log is enable. +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + log-options snapshot-length <0-9000> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge name <name> rule <1-999999> + log-options snapshot-length <0-9000> + + Define length of packet payload to include in netlink message. Only + applicable if rule log is enable and log group is defined. +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + log-options queue-threshold <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge name <name> rule <1-999999> + log-options queue-threshold <0-65535> + + Define number of packets to queue inside the kernel before sending them to + userspace. Only applicable if rule log is enable and log group is defined. +``` + +### Firewall Description + +For reference, a description can be defined for every defined custom chain. + +```{eval-rst} +.. cfgcmd:: set firewall bridge name <name> description <text> + + Provide a rule-set description to a custom firewall chain. +``` + +### Rule Status + +When defining a rule, it is enable by default. In some cases, it is useful to +just disable the rule, rather than removing it. + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> disable +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge name <name> rule <1-999999> disable + + Command for disabling a rule but keep it in the configuration. +``` + +### Matching criteria + +There are a lot of matching criteria against which the packet can be tested. + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + destination mac-address <mac-address> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge name <name> rule <1-999999> + destination mac-address <mac-address> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + source mac-address <mac-address> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge name <name> rule <1-999999> + source mac-address <mac-address> + + Match criteria based on source and/or destination mac-address. +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + inbound-interface name <iface> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge name <name> rule <1-999999> + inbound-interface name <iface> + + Match based on inbound interface. Wilcard ``*`` can be used. + For example: ``eth2*``. Prepending character ``!`` for inverted matching + criteria is also supportd. For example ``!eth2`` +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + inbound-interface group <iface_group> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge name <name> rule <1-999999> + inbound-interface group <iface_group> + + Match based on inbound interface group. Prepending character ``!`` for + inverted matching criteria is also supportd. For example ``!IFACE_GROUP`` +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + outbound-interface name <iface> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge name <name> rule <1-999999> + outbound-interface name <iface> + + Match based on outbound interface. Wilcard ``*`` can be used. + For example: ``eth2*``. Prepending character ``!`` for inverted matching + criteria is also supportd. For example ``!eth2`` +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + outbound-interface group <iface_group> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge name <name> rule <1-999999> + outbound-interface group <iface_group> + + Match based on outbound interface group. Prepending character ``!`` for + inverted matching criteria is also supportd. For example ``!IFACE_GROUP`` +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + vlan id <0-4096> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge name <name> rule <1-999999> + vlan id <0-4096> + + Match based on vlan ID. Range is also supported. +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + vlan priority <0-7> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge name <name> rule <1-999999> + vlan priority <0-7> + + Match based on vlan priority(pcp). Range is also supported. +``` + +## Operation-mode Firewall + +### Rule-set overview + +In this section you can find all useful firewall op-mode commands. + +General commands for firewall configuration, counter and statiscits: + +```{eval-rst} +.. opcmd:: show firewall +``` + +```{eval-rst} +.. opcmd:: show firewall summary +``` + +```{eval-rst} +.. opcmd:: show firewall statistics +``` + +And, to print only bridge firewall information: + +```{eval-rst} +.. opcmd:: show firewall bridge +``` + +```{eval-rst} +.. opcmd:: show firewall bridge forward filter +``` + +```{eval-rst} +.. opcmd:: show firewall bridge forward filter rule <rule> +``` + +```{eval-rst} +.. opcmd:: show firewall bridge name <name> +``` + +```{eval-rst} +.. opcmd:: show firewall bridge name <name> rule <rule> +``` + +### Show Firewall log + +```{eval-rst} +.. opcmd:: show log firewall +``` + +```{eval-rst} +.. opcmd:: show log firewall bridge +``` + +```{eval-rst} +.. opcmd:: show log firewall bridge forward +``` + +```{eval-rst} +.. opcmd:: show log firewall bridge forward filter +``` + +```{eval-rst} +.. opcmd:: show log firewall bridge name <name> +``` + +```{eval-rst} +.. opcmd:: show log firewall bridge forward filter rule <rule> +``` + +```{eval-rst} +.. opcmd:: show log firewall bridge name <name> rule <rule> + + Show the logs of all firewall; show all bridge firewall logs; show all logs + for forward hook; show all logs for forward hook and priority filter; show + all logs for particular custom chain; show logs for specific Rule-Set. +``` + +### Example + +Configuration example: + +```none +set firewall bridge forward filter default-action 'drop' +set firewall bridge forward filter default-log +set firewall bridge forward filter rule 10 action 'continue' +set firewall bridge forward filter rule 10 inbound-interface name 'eth2' +set firewall bridge forward filter rule 10 vlan id '22' +set firewall bridge forward filter rule 20 action 'drop' +set firewall bridge forward filter rule 20 inbound-interface group 'TRUNK-RIGHT' +set firewall bridge forward filter rule 20 vlan id '60' +set firewall bridge forward filter rule 30 action 'jump' +set firewall bridge forward filter rule 30 jump-target 'TEST' +set firewall bridge forward filter rule 30 outbound-interface name '!eth1' +set firewall bridge forward filter rule 35 action 'accept' +set firewall bridge forward filter rule 35 vlan id '11' +set firewall bridge forward filter rule 40 action 'continue' +set firewall bridge forward filter rule 40 destination mac-address '66:55:44:33:22:11' +set firewall bridge forward filter rule 40 source mac-address '11:22:33:44:55:66' +set firewall bridge name TEST default-action 'accept' +set firewall bridge name TEST default-log +set firewall bridge name TEST rule 10 action 'continue' +set firewall bridge name TEST rule 10 log +set firewall bridge name TEST rule 10 vlan priority '0' +``` + +And op-mode commands: + +```none +vyos@BRI:~$ show firewall bridge +Rulesets bridge Information + +--------------------------------- +bridge Firewall "forward filter" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- --------------------------------------------------------------------- +10 continue all 0 0 iifname "eth2" vlan id 22 continue +20 drop all 0 0 iifname @I_TRUNK-RIGHT vlan id 60 +30 jump all 2130 170688 oifname != "eth1" jump NAME_TEST +35 accept all 2080 168616 vlan id 11 accept +40 continue all 0 0 ether daddr 66:55:44:33:22:11 ether saddr 11:22:33:44:55:66 continue +default drop all 0 0 + +--------------------------------- +bridge Firewall "name TEST" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- -------------------------------------------------- +10 continue all 2130 170688 vlan pcp 0 prefix "[bri-NAM-TEST-10-C]" continue +default accept all 2130 170688 + +vyos@BRI:~$ +vyos@BRI:~$ show firewall bridge name TEST +Ruleset Information + +--------------------------------- +bridge Firewall "name TEST" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- -------------------------------------------------- +10 continue all 2130 170688 vlan pcp 0 prefix "[bri-NAM-TEST-10-C]" continue +default accept all 2130 170688 + +vyos@BRI:~$ +``` + +Inspect logs: + +```none +vyos@BRI:~$ show log firewall bridge +Dec 05 14:37:47 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102 +Dec 05 14:37:48 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102 +Dec 05 14:37:49 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102 +... +vyos@BRI:~$ show log firewall bridge forward filter +Dec 05 14:42:22 kernel: [bri-FWD-filter-default-D]IN=eth2 OUT=eth1 MAC=33:33:00:00:00:16:50:00:00:06:00:00:86:dd SRC=0000:0000:0000:0000:0000:0000:0000:0000 DST=ff02:0000:0000:0000:0000:0000:0000:0016 LEN=96 TC=0 HOPLIMIT=1 FLOWLBL=0 PROTO=ICMPv6 TYPE=143 CODE=0 +Dec 05 14:42:22 kernel: [bri-FWD-filter-default-D]IN=eth2 OUT=eth1 MAC=33:33:00:00:00:16:50:00:00:06:00:00:86:dd SRC=0000:0000:0000:0000:0000:0000:0000:0000 DST=ff02:0000:0000:0000:0000:0000:0000:0016 LEN=96 TC=0 HOPLIMIT=1 FLOWLBL=0 PROTO=ICMPv6 TYPE=143 CODE=0 +``` diff --git a/docs/configuration/firewall/md-flowtables.md b/docs/configuration/firewall/md-flowtables.md new file mode 100644 index 00000000..bc9fc457 --- /dev/null +++ b/docs/configuration/firewall/md-flowtables.md @@ -0,0 +1,195 @@ +--- +lastproofread: '2024-06-20' +--- + +(firewall-flowtables-configuration)= + +# Flowtables Firewall Configuration + +:::{note} +**Documentation under development** +::: + +## Overview + +In this section there's useful information of all firewall configuration that +can be done regarding flowtables. + +```{eval-rst} +.. cfgcmd:: set firewall flowtables ... +``` + +From main structure defined in +{doc}`Firewall Overview</configuration/firewall/index>` +in this section you can find detailed information only for the next part +of the general structure: + +```none +- set firewall + * flowtable + - custom_flow_table + + ... +``` + +Flowtables allows you to define a fastpath through the flowtable datapath. +The flowtable supports for the layer 3 IPv4 and IPv6 and the layer 4 TCP +and UDP protocols. + +:::{figure} /_static/images/firewall-flowtable-packet-flow.png +::: + +Once the first packet of the flow successfully goes through the IP forwarding +path (black circles path), from the second packet on, you might decide to +offload the flow to the flowtable through your ruleset. The flowtable +infrastructure provides a rule action that allows you to specify when to add +a flow to the flowtable (On forward filtering, red circle number 6) + +A packet that finds a matching entry in the flowtable (flowtable hit) is +transmitted to the output netdevice, hence, packets bypass the classic IP +forwarding path and uses the **Fast Path** (orange circles path). The visible +effect is that you do not see these packets from any of the Netfilter +hooks coming after ingress. In case that there is no matching entry in the +flowtable (flowtable miss), the packet follows the classic IP forwarding path. + +:::{note} +**Flowtable Reference:** +<https://docs.kernel.org/networking/nf_flowtable.html> +::: + +## Flowtable Configuration + +In order to use flowtables, the minimal configuration needed includes: + +> - Create flowtable: create flowtable, which includes the interfaces +> that are going to be used by the flowtable. +> - Create firewall rule: create a firewall rule, setting action to +> `offload` and using desired flowtable for `offload-target`. + +Creating a flow table: + +```{eval-rst} +.. cfgcmd:: set firewall flowtable <flow_table_name> interface <iface> + + Define interfaces to be used in the flowtable. +``` + +```{eval-rst} +.. cfgcmd:: set firewall flowtable <flow_table_name> description <text> +``` + +Provide a description to the flow table. + +```{eval-rst} +.. cfgcmd:: set firewall flowtable <flow_table_name> offload + <hardware | software> + + Define type of offload to be used by the flowtable: ``hardware`` or + ``software``. By default, ``software`` offload is used. +``` + +:::{note} +**Hardware offload:** should be supported by the NICs used. +::: + +Creating rules for using flow tables: + +```{eval-rst} +.. cfgcmd:: set firewall [ipv4 | ipv6] forward filter rule <1-999999> + action offload + + Create firewall rule in forward chain, and set action to ``offload``. +``` + +```{eval-rst} +.. cfgcmd:: set firewall [ipv4 | ipv6] forward filter rule <1-999999> + offload-target <flowtable> + + Create firewall rule in forward chain, and define which flowtbale + should be used. Only applicable if action is ``offload``. +``` + +## Configuration Example + +Things to be considred in this setup: + +> - Two interfaces are going to be used in the flowtables: eth0 and eth1 +> - Minumum firewall ruleset is provided, which includes some filtering rules, +> and appropiate rules for using flowtable offload capabilities. + +As described, first packet will be evaluated by all the firewall path, so +desired connection should be explicitely accepted. Same thing should be taken +into account for traffic in reverse order. In most cases state policies are +used in order to accept connection in reverse patch. + +We will only accept traffic comming from interface eth0, protocol tcp and +destination port 1122. All other traffic traspassing the router should be +blocked. + +### Commands + +```none +set firewall flowtable FT01 interface 'eth0' +set firewall flowtable FT01 interface 'eth1' +set firewall ipv4 forward filter default-action 'drop' +set firewall ipv4 forward filter rule 10 action 'offload' +set firewall ipv4 forward filter rule 10 offload-target 'FT01' +set firewall ipv4 forward filter rule 10 state 'established' +set firewall ipv4 forward filter rule 10 state 'related' +set firewall ipv4 forward filter rule 20 action 'accept' +set firewall ipv4 forward filter rule 20 state 'established' +set firewall ipv4 forward filter rule 20 state 'related' +set firewall ipv4 forward filter rule 110 action 'accept' +set firewall ipv4 forward filter rule 110 destination address '192.0.2.100' +set firewall ipv4 forward filter rule 110 destination port '1122' +set firewall ipv4 forward filter rule 110 inbound-interface name 'eth0' +set firewall ipv4 forward filter rule 110 protocol 'tcp' +``` + +### Explanation + +Analysis on what happens for desired connection: + +> 1\. First packet is received on eth0, with destination address 192.0.2.100, +> protocol tcp and destination port 1122. Assume such destination address is +> reachable through interface eth1. +> +> 2\. Since this is the first packet, connection status of this connection, +> so far is **new**. So neither rule 10 nor 20 are valid. +> +> 3. Rule 110 is hit, so connection is accepted. +> +> 4\. Once answer from server 192.0.2.100 is seen in opposite direction, +> connection state will be triggered to **established**, so this reply is +> accepted in rule 20. +> +> 5\. Second packet for this connection is received by the router. Since +> connection state is **established**, then rule 10 is hit, and a new entry +> in the flowtable FT01 is added for this connection. +> +> 6\. All the following packets will skip traditional path, and will be offloaded +> and will use the **Fast Path**. + +### Checks + +It's time to check conntrack table, to see if any connection was accepted, +and if was properly offloaded + +```none +vyos@FlowTables:~$ show firewall ipv4 forward filter +Ruleset Information + +--------------------------------- +ipv4 Firewall "forward filter" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- ---------------------------------------------------------------- +10 offload all 8 468 ct state { established, related } flow add @VYOS_FLOWTABLE_FT01 +20 accept all 8 468 ct state { established, related } accept +110 accept tcp 2 120 ip daddr 192.0.2.100 tcp dport 1122 iifname "eth0" accept +default drop all 7 420 + +vyos@FlowTables:~$ sudo conntrack -L | grep tcp +conntrack v1.4.6 (conntrack-tools): 5 flow entries have been shown. +tcp 6 src=198.51.100.100 dst=192.0.2.100 sport=41676 dport=1122 src=192.0.2.100 dst=198.51.100.100 sport=1122 dport=41676 [OFFLOAD] mark=0 use=2 +vyos@FlowTables:~$ +``` diff --git a/docs/configuration/firewall/md-global-options.md b/docs/configuration/firewall/md-global-options.md new file mode 100644 index 00000000..6ca5a0e2 --- /dev/null +++ b/docs/configuration/firewall/md-global-options.md @@ -0,0 +1,187 @@ +--- +lastproofread: '2023-12-26' +--- + +(firewall-global-options-configuration)= + +# Global Options Firewall Configuration + +## Overview + +Some firewall settings are global and have an affect on the whole system. +In this section there's useful information about these global-options that can +be configured using vyos cli. + +Configuration commands covered in this section: + +```{eval-rst} +.. cfgcmd:: set firewall global-options ... +``` + +## Configuration + +```{eval-rst} +.. cfgcmd:: set firewall global-options all-ping [enable | disable] + + 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 global-options all-ping** affects only to LOCAL + and it always behaves in the most restrictive way + + .. code-block:: none + + set firewall global-options 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 dropping or rejecting local echo requests. In case of conflict, + VyOS will not answer ICMP echo requests. + + .. code-block:: none + + set firewall global-options all-ping disable + + When the command 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options broadcast-ping [enable | disable] + + This setting enable or disable the response of icmp broadcast + messages. The following system parameter will be altered: + + * ``net.ipv4.icmp_echo_ignore_broadcasts`` +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options ip-src-route [enable | disable] +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options ipv6-src-route [enable | disable] + + This setting handle if VyOS accept packets with a source route + option. The following system parameter will be altered: + + * ``net.ipv4.conf.all.accept_source_route`` + * ``net.ipv6.conf.all.accept_source_route`` +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options receive-redirects [enable | disable] +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options ipv6-receive-redirects + [enable | disable] + + enable or disable of ICMPv4 or ICMPv6 redirect messages accepted + by VyOS. The following system parameter will be altered: + + * ``net.ipv4.conf.all.accept_redirects`` + * ``net.ipv6.conf.all.accept_redirects`` +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options send-redirects [enable | disable] + + enable or disable ICMPv4 redirect messages send by VyOS + The following system parameter will be altered: + + * ``net.ipv4.conf.all.send_redirects`` +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options log-martians [enable | disable] + + enable or disable the logging of martian IPv4 packets. + The following system parameter will be altered: + + * ``net.ipv4.conf.all.log_martians`` +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options source-validation + [strict | loose | disable] + + Set the IPv4 source validation mode. + The following system parameter will be altered: + + * ``net.ipv4.conf.all.rp_filter`` +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options syn-cookies [enable | disable] + + Enable or Disable if VyOS use IPv4 TCP SYN Cookies. + The following system parameter will be altered: + + * ``net.ipv4.tcp_syncookies`` +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options twa-hazards-protection + [enable | disable] + + Enable or Disable VyOS to be {rfc}`1337` conform. + The following system parameter will be altered: + + * ``net.ipv4.tcp_rfc1337`` +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options state-policy established action + [accept | drop | reject] +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options state-policy established log +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options state-policy established log-level + [emerg | alert | crit | err | warn | notice | info | debug] + + Set the global setting for an established connection. +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options state-policy invalid action + [accept | drop | reject] +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options state-policy invalid log +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options state-policy invalid log-level + [emerg | alert | crit | err | warn | notice | info | debug] + + Set the global setting for invalid packets. +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options state-policy related action + [accept | drop | reject] +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options state-policy related log +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options state-policy related log-level + [emerg | alert | crit | err | warn | notice | info | debug] + + Set the global setting for related connections. +``` diff --git a/docs/configuration/firewall/md-groups.md b/docs/configuration/firewall/md-groups.md new file mode 100644 index 00000000..d3c2db6e --- /dev/null +++ b/docs/configuration/firewall/md-groups.md @@ -0,0 +1,495 @@ +--- +lastproofread: '2023-11-08' +--- + +(firewall-groups-configuration)= + +# Firewall groups + +## Configuration + +Firewall groups represent collections of IP addresses, networks, ports, +mac addresses, domains or interfaces. Once created, a group can be referenced +by firewall, nat and policy route rules as either a source or destination +matcher, and/or as inbound/outbound in the case of interface group. + +### Address Groups + +In an **address group** a single IP address or IP address ranges are +defined. + +```{eval-rst} +.. cfgcmd:: set firewall group address-group <name> address [address | + address range] +``` + +```{eval-rst} +.. cfgcmd:: set firewall group ipv6-address-group <name> address <address> + + Define a IPv4 or a IPv6 address group + + .. code-block:: none + + set firewall group address-group ADR-INSIDE-v4 address 192.168.0.1 + set firewall group address-group ADR-INSIDE-v4 address 10.0.0.1-10.0.0.8 + set firewall group ipv6-address-group ADR-INSIDE-v6 address 2001:db8::1 +``` + +```{eval-rst} +.. cfgcmd:: set firewall group address-group <name> description <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall group ipv6-address-group <name> description <text> + + Provide a IPv4 or IPv6 address group description +``` + +### Network Groups + +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. + +```{eval-rst} +.. cfgcmd:: set firewall group network-group <name> network <CIDR> +``` + +```{eval-rst} +.. cfgcmd:: set firewall group ipv6-network-group <name> network <CIDR> + + Define a IPv4 or IPv6 Network group. + + .. code-block:: none + + set firewall group network-group NET-INSIDE-v4 network 192.168.0.0/24 + 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 +``` + +```{eval-rst} +.. cfgcmd:: set firewall group network-group <name> description <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall group ipv6-network-group <name> description <text> + + Provide an IPv4 or IPv6 network group description. +``` + +### Interface Groups + +An **interface group** represents a collection of interfaces. + +```{eval-rst} +.. cfgcmd:: set firewall group interface-group <name> interface <text> + + Define an interface group. Wildcard are accepted too. +``` + +```none +set firewall group interface-group LAN interface bond1001 +set firewall group interface-group LAN interface eth3* +``` + +```{eval-rst} +.. cfgcmd:: set firewall group interface-group <name> description <text> + + Provide an interface group description +``` + +### Port Groups + +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 +`-`. + +```{eval-rst} +.. cfgcmd:: set firewall group port-group <name> port + [portname | portnumber | startport-endport] + + Define a port group. A port name can be any name defined in + /etc/services. e.g.: http + + .. code-block:: none + + set firewall group port-group PORT-TCP-SERVER1 port http + set firewall group port-group PORT-TCP-SERVER1 port 443 + set firewall group port-group PORT-TCP-SERVER1 port 5000-5010 +``` + +```{eval-rst} +.. cfgcmd:: set firewall group port-group <name> description <text> + + Provide a port group description. +``` + +### MAC Groups + +A **mac group** represents a collection of mac addresses. + +```{eval-rst} +.. cfgcmd:: set firewall group mac-group <name> mac-address <mac-address> + + Define a mac group. +``` + +```none +set firewall group mac-group MAC-G01 mac-address 88:a4:c2:15:b6:4f +set firewall group mac-group MAC-G01 mac-address 4c:d5:77:c0:19:81 +``` + +```{eval-rst} +.. cfgcmd:: set firewall group mac-group <name> description <text> + + Provide a mac group description. +``` + +### Domain Groups + +A **domain group** represents a collection of domains. + +```{eval-rst} +.. cfgcmd:: set firewall group domain-group <name> address <domain> + + Define a domain group. +``` + +```none +set firewall group domain-group DOM address example.com +``` + +```{eval-rst} +.. cfgcmd:: set firewall group domain-group <name> description <text> + + Provide a domain group description. +``` + +### Dynamic Groups + +Firewall dynamic groups are different from all the groups defined previously +because, not only they can be used as source/destination in firewall rules, +but members of these groups are not defined statically using vyos +configuration. + +Instead, members of these groups are added dynamically using firewall +rules. + +#### Defining Dynamic Address Groups + +Dynamic address group is supported by both IPv4 and IPv6 families. +Commands used to define dynamic IPv4|IPv6 address groups are: + +```{eval-rst} +.. cfgcmd:: set firewall group dynamic-group address-group <name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall group dynamic-group ipv6-address-group <name> +``` + +Add description to firewall groups: + +```{eval-rst} +.. cfgcmd:: set firewall group dynamic-group address-group <name> + description <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall group dynamic-group ipv6-address-group <name> + description <text> +``` + +#### Adding elements to Dynamic Firewall Groups + +Once dynamic firewall groups are defined, they should be used in firewall +rules in order to dynamically add elements to it. + +Commands used for this task are: + +- Add destination IP address of the connection to a dynamic address group: + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 [forward | input | output] filter rule + <1-999999> add-address-to-group destination-address address-group <name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> add-address-to-group + destination-address address-group <name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 [forward | input | output] filter rule + <1-999999> add-address-to-group destination-address address-group <name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> add-address-to-group + destination-address address-group <name> +``` + +- Add source IP address of the connection to a dynamic address group: + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 [forward | input | output] filter rule + <1-999999> add-address-to-group source-address address-group <name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> add-address-to-group + source-address address-group <name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 [forward | input | output] filter rule + <1-999999> add-address-to-group source-address address-group <name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> add-address-to-group + source-address address-group <name> +``` + +Also, specific timeout can be defined per rule. In case rule gets a hit, +source or destinatination address will be added to the group, and this +element will remain in the group until timeout expires. If no timeout +is defined, then the element will remain in the group until next reboot, +or until a new commit that changes firewall configuration is done. + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 [forward | input | output] filter rule + <1-999999> add-address-to-group [destination-address | source-address] + timeout <timeout> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> add-address-to-group + [destination-address | source-address] timeout <timeout> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 [forward | input | output] filter rule + <1-999999> add-address-to-group [destination-address | source-address] + timeout <timeout> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> add-address-to-group + [destination-address | source-address] timeout <timeout> +``` + +Timeout can be defined using seconds, minutes, hours or days: + +```none +set firewall ipv6 name FOO rule 10 add-address-to-group source-address timeout +Possible completions: +<number>s Timeout value in seconds +<number>m Timeout value in minutes +<number>h Timeout value in hours +<number>d Timeout value in days +``` + +#### Using Dynamic Firewall Groups + +As any other firewall group, dynamic firewall groups can be used in firewall +rules as matching options. For example: + +```none set firewall ipv4 input filter rule 10 source group dynamic-address-group FOO set firewall ipv4 input filter rule 10 destination group dynamic-address-group BAR + +``` + +## Examples + +### General example + +As said before, once firewall groups are created, they can be referenced +either in firewall, nat, nat66 and/or policy-route rules. + +Here is an example were multiple groups are created: + +> ```none +> set firewall group address-group SERVERS address 198.51.100.101 +> set firewall group address-group SERVERS address 198.51.100.102 +> set firewall group network-group TRUSTEDv4 network 192.0.2.0/30 +> set firewall group network-group TRUSTEDv4 network 203.0.113.128/25 +> set firewall group ipv6-network-group TRUSTEDv6 network 2001:db8::/64 +> set firewall group interface-group LAN interface eth2.2001 +> set firewall group interface-group LAN interface bon0 +> set firewall group port-group PORT-SERVERS port http +> set firewall group port-group PORT-SERVERS port 443 +> set firewall group port-group PORT-SERVERS port 5000-5010 +> ``` + +And next, some configuration example where groups are used: + +> ```none +> set firewall ipv4 output filter rule 10 action accept +> set firewall ipv4 output filter rule 10 outbound-interface group !LAN +> set firewall ipv4 forward filter rule 20 action accept +> set firewall ipv4 forward filter rule 20 source group network-group TRUSTEDv4 +> set firewall ipv6 input filter rule 10 action accept +> set firewall ipv6 input filter rule 10 source group network-group TRUSTEDv6 +> set nat destination rule 101 inbound-interface group LAN +> set nat destination rule 101 destination group address-group SERVERS +> set nat destination rule 101 protocol tcp +> set nat destination rule 101 destination group port-group PORT-SERVERS +> set nat destination rule 101 translation address 203.0.113.250 +> set policy route PBR rule 201 destination group port-group PORT-SERVERS +> set policy route PBR rule 201 protocol tcp +> set policy route PBR rule 201 set table 15 +> ``` + +### Port knocking example + +Using dynamic firewall groups, we can secure access to the router, or any other +device if needed, by using the technique of port knocking. + +A 4 step port knocking example is shown next: + +> ```none +> set firewall global-options state-policy established action 'accept' +> set firewall global-options state-policy invalid action 'drop' +> set firewall global-options state-policy related action 'accept' +> set firewall group dynamic-group address-group ALLOWED +> set firewall group dynamic-group address-group PN_01 +> set firewall group dynamic-group address-group PN_02 +> set firewall ipv4 input filter default-action 'drop' +> set firewall ipv4 input filter rule 5 action 'accept' +> set firewall ipv4 input filter rule 5 protocol 'icmp' +> set firewall ipv4 input filter rule 10 action 'drop' +> set firewall ipv4 input filter rule 10 add-address-to-group source-address address-group 'PN_01' +> set firewall ipv4 input filter rule 10 add-address-to-group source-address timeout '2m' +> set firewall ipv4 input filter rule 10 description 'Port_nock 01' +> set firewall ipv4 input filter rule 10 destination port '9990' +> set firewall ipv4 input filter rule 10 protocol 'tcp' +> set firewall ipv4 input filter rule 20 action 'drop' +> set firewall ipv4 input filter rule 20 add-address-to-group source-address address-group 'PN_02' +> set firewall ipv4 input filter rule 20 add-address-to-group source-address timeout '3m' +> set firewall ipv4 input filter rule 20 description 'Port_nock 02' +> set firewall ipv4 input filter rule 20 destination port '9991' +> set firewall ipv4 input filter rule 20 protocol 'tcp' +> set firewall ipv4 input filter rule 20 source group dynamic-address-group 'PN_01' +> set firewall ipv4 input filter rule 30 action 'drop' +> set firewall ipv4 input filter rule 30 add-address-to-group source-address address-group 'ALLOWED' +> set firewall ipv4 input filter rule 30 add-address-to-group source-address timeout '2h' +> set firewall ipv4 input filter rule 30 description 'Port_nock 03' +> set firewall ipv4 input filter rule 30 destination port '9992' +> set firewall ipv4 input filter rule 30 protocol 'tcp' +> set firewall ipv4 input filter rule 30 source group dynamic-address-group 'PN_02' +> set firewall ipv4 input filter rule 99 action 'accept' +> set firewall ipv4 input filter rule 99 description 'Port_nock 04 - Allow ssh' +> set firewall ipv4 input filter rule 99 destination port '22' +> set firewall ipv4 input filter rule 99 protocol 'tcp' +> set firewall ipv4 input filter rule 99 source group dynamic-address-group 'ALLOWED' +> ``` + +Before testing, we can check members of firewall groups: + +> ```none +> vyos@vyos# run show firewall group +> Firewall Groups +> +> Name Type References Members Timeout Expires +> ------- ---------------------- -------------------- ------------- --------- --------- +> ALLOWED address_group(dynamic) ipv4-input-filter-30 N/D N/D N/D +> PN_01 address_group(dynamic) ipv4-input-filter-10 N/D N/D N/D +> PN_02 address_group(dynamic) ipv4-input-filter-20 N/D N/D N/D +> [edit] +> vyos@vyos# +> ``` + +With this configuration, in order to get ssh access to the router, user +needs to: + +1\. Generate a new TCP connection with destination port 9990. As shown next, +a new entry was added to dynamic firewall group **PN_01** + +> ```none +> vyos@vyos# run show firewall group +> Firewall Groups +> +> Name Type References Members Timeout Expires +> ------- ---------------------- -------------------- ------------- --------- --------- +> ALLOWED address_group(dynamic) ipv4-input-filter-30 N/D N/D N/D +> PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.89.31 120 119 +> PN_02 address_group(dynamic) ipv4-input-filter-20 N/D N/D N/D +> [edit] +> vyos@vyos# +> ``` + +2\. Generate a new TCP connection with destination port 9991. As shown next, +a new entry was added to dynamic firewall group **PN_02** + +> ```none +> vyos@vyos# run show firewall group +> Firewall Groups +> +> Name Type References Members Timeout Expires +> ------- ---------------------- -------------------- ------------- --------- --------- +> ALLOWED address_group(dynamic) ipv4-input-filter-30 N/D N/D N/D +> PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.89.31 120 106 +> PN_02 address_group(dynamic) ipv4-input-filter-20 192.168.89.31 180 179 +> [edit] +> vyos@vyos# +> ``` + +3\. Generate a new TCP connection with destination port 9992. As shown next, +a new entry was added to dynamic firewall group **ALLOWED** + +> ```none +> vyos@vyos# run show firewall group +> Firewall Groups +> +> Name Type References Members Timeout Expires +> ------- ---------------------- -------------------- ------------- --------- --------- +> ALLOWED address_group(dynamic) ipv4-input-filter-30 192.168.89.31 7200 7199 +> PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.89.31 120 89 +> PN_02 address_group(dynamic) ipv4-input-filter-20 192.168.89.31 180 170 +> [edit] +> vyos@vyos# +> ``` + +4. Now user can connect through ssh to the router (assuming ssh is configured). + +## Operation-mode + +```{eval-rst} +.. opcmd:: show firewall group +``` + +```{eval-rst} +.. opcmd:: show firewall group <name> + + Overview of defined groups. You see the firewall group name, type, + references (where the group is used), members, timeout and expiration (last + two only present in dynamic firewall groups). +``` + +Here is an example of such command: + +> ```none +> vyos@vyos:~$ show firewall group +> Firewall Groups +> +> Name Type References Members Timeout Expires +> ------------ ---------------------- ---------------------- ---------------- --------- --------- +> SERVERS address_group nat-destination-101 198.51.100.101 +> 198.51.100.102 +> ALLOWED address_group(dynamic) ipv4-input-filter-30 192.168.77.39 7200 7174 +> PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.0.245 120 112 +> 192.168.77.39 120 85 +> PN_02 address_group(dynamic) ipv4-input-filter-20 192.168.77.39 180 151 +> LAN interface_group ipv4-output-filter-10 bon0 +> nat-destination-101 eth2.2001 +> TRUSTEDv6 ipv6_network_group ipv6-input-filter-10 2001:db8::/64 +> TRUSTEDv4 network_group ipv4-forward-filter-20 192.0.2.0/30 +> 203.0.113.128/25 +> PORT-SERVERS port_group route-PBR-201 443 +> route-PBR-201 5000-5010 +> nat-destination-101 http +> vyos@vyos:~$ +> ``` diff --git a/docs/configuration/firewall/md-index.md b/docs/configuration/firewall/md-index.md new file mode 100644 index 00000000..53c5a7fc --- /dev/null +++ b/docs/configuration/firewall/md-index.md @@ -0,0 +1,181 @@ +--- +lastproofread: '2023-11-23' +--- + +# Firewall + +As VyOS is based on Linux it leverages its firewall. The Netfilter project +created iptables and its successor nftables for the Linux kernel to +work directly on packet data flows. This now extends the concept of +zone-based security to allow for manipulating the data at multiple stages once +accepted by the network interface and the driver before being handed off to +the destination (e.g., a web server OR another device). + +A simplified traffic flow diagram, based on Netfilter packet flow, is shown +next, in order to have a full view and understanding of how packets are +processed, and what possible paths traffic can take. + +:::{figure} /_static/images/firewall-gral-packet-flow.png +::: + +The main points regarding this packet flow and terminology used in VyOS +firewall are covered below: + +> - **Bridge Port?**: choose appropriate path based on whether interface +> where the packet was received is part of a bridge, or not. + +If the interface where the packet was received isn't part of a bridge, then +packetis processed at the **IP Layer**: + +> - **Prerouting**: several actions can be done in this stage, and currently +> these actions are defined in different parts in VyOS configuration. Order +> is important, and all these actions are performed before any actions +> defined under `firewall` section. Relevant configuration that acts in +> this stage are: +> +> > - **Conntrack Ignore**: rules defined under `set system conntrack ignore +> > [ipv4 | ipv6] ...`. +> > - **Policy Route**: rules defined under `set policy [route | route6] +> > ...`. +> > - **Destination NAT**: rules defined under `set [nat | nat66] +> > destination...`. +> +> - **Destination is the router?**: choose appropriate path based on +> destination IP address. Transit forward continues to **forward**, +> while traffic that destination IP address is configured on the router +> continues to **input**. +> +> - **Input**: stage where traffic destined for the router itself can be +> filtered and controlled. This is where all rules for securing the router +> should take place. This includes ipv4 and ipv6 filtering rules, defined +> in: +> +> - `set firewall ipv4 input filter ...`. +> - `set firewall ipv6 input filter ...`. +> +> - **Forward**: stage where transit traffic can be filtered and controlled. +> This includes ipv4 and ipv6 filtering rules, defined in: +> +> - `set firewall ipv4 forward filter ...`. +> - `set firewall ipv6 forward filter ...`. +> +> - **Output**: stage where traffic that originates from the router itself +> can be filtered and controlled. Bear in mind that this traffic can be a +> new connection originated by a internal process running on VyOS router, +> such as NTP, or a response to traffic received externaly through +> **input** (for example response to an ssh login attempt to the router). +> This includes ipv4 and ipv6 filtering rules, defined in: +> +> - `set firewall ipv4 output filter ...`. +> - `set firewall ipv6 output filter ...`. +> +> - **Postrouting**: as in **Prerouting**, several actions defined in +> different parts of VyOS configuration are performed in this +> stage. This includes: +> +> - **Source NAT**: rules defined under `set [nat | nat66] +> destination...`. + +If the interface where the packet was received is part of a bridge, then +the packet is processed at the **Bridge Layer**, which contains a basic setup for +bridge filtering: + +> - **Forward (Bridge)**: stage where traffic that is trespasing through the +> bridge is filtered and controlled: +> +> - `set firewall bridge forward filter ...`. + +The main structure of the VyOS firewall CLI is shown next: + +```none +- set firewall + * bridge + - forward + + filter + * flowtable + - custom_flow_table + + ... + * global-options + + all-ping + + broadcast-ping + + ... + * group + - address-group + - ipv6-address-group + - network-group + - ipv6-network-group + - interface-group + - mac-group + - port-group + - domain-group + * ipv4 + - forward + + filter + - input + + filter + - output + + filter + - name + + custom_name + * ipv6 + - forward + + filter + - input + + filter + - output + + filter + - ipv6-name + + custom_name + * zone + - custom_zone_name + + ... +``` + +Please, refer to appropriate section for more information about firewall +configuration: + +```{eval-rst} +.. toctree:: + :maxdepth: 1 + :includehidden: + + global-options + groups + bridge + ipv4 + ipv6 + flowtables +``` + +:::{note} +**For more information** +of Netfilter hooks and Linux networking packet flows can be +found in [Netfilter-Hooks](https://wiki.nftables.org/wiki-nftables/index.php/Netfilter_hooks) +::: + +## Zone-based firewall + +```{eval-rst} +.. toctree:: + :maxdepth: 1 + :includehidden: + + zone +``` + +With zone-based firewalls a new concept was implemented, in addition to the +standard in and out traffic flows, a local flow was added. This local was for +traffic originating and destined to the router itself. Which means additional +rules were required to secure the firewall itself from the network, in +addition to the existing inbound and outbound rules from the traditional +concept above. + +To configure VyOS with the +{doc}`zone-based firewall configuration </configuration/firewall/zone>` + +As the example image below shows, the device now needs rules to allow/block +traffic to or from the services running on the device that have open +connections on that interface. + +:::{figure} /_static/images/firewall-zonebased.png +::: diff --git a/docs/configuration/firewall/md-ipv4.md b/docs/configuration/firewall/md-ipv4.md new file mode 100644 index 00000000..23ff6c39 --- /dev/null +++ b/docs/configuration/firewall/md-ipv4.md @@ -0,0 +1,2037 @@ +--- +lastproofread: '2023-11-08' +--- + +(firewall-ipv4-configuration)= + +# IPv4 Firewall Configuration + +## Overview + +In this section there's useful information of all firewall configuration that +can be done regarding IPv4, and appropiate op-mode commands. +Configuration commands covered in this section: + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 ... +``` + +From main structure defined in +{doc}`Firewall Overview</configuration/firewall/index>` +in this section you can find detailed information only for the next part +of the general structure: + +```none +- set firewall + * ipv4 + - forward + + filter + - input + + filter + - output + + filter + - name + + custom_name +``` + +For transit traffic, which is received by the router and forwarded, base chain +is **forward**. A simplified packet flow diagram for transit traffic is shown +next: + +:::{figure} /_static/images/firewall-fwd-packet-flow.png +::: + +Where firewall base chain to configure firewall filtering rules for transit +traffic is `set firewall ipv4 forward filter ...`, which happens in stage 5, +highlightened with red color. + +For traffic towards the router itself, base chain is **input**, while traffic +originated by the router, base chain is **output**. +A new simplified packet flow diagram is shown next, which shows the path +for traffic destinated to the router itself, and traffic generated by the +router (starting from circle number 6): + +:::{figure} /_static/images/firewall-input-packet-flow.png +::: + +Base chain is for traffic toward the router is `set firewall ipv4 input +filter ...` + +And base chain for traffic generated by the router is `set firewall ipv4 +output filter ...` + +:::{note} +**Important note about default-actions:** +If default action for any base chain is not defined, then the default +action is set to **accept** for that chain. For custom chains, if default +action is not defined, then the default-action is set to **drop** +::: + +Custom firewall chains can be created, with commands +`set firewall ipv4 name <name> ...`. In order to use +such custom chain, a rule with **action jump**, and the appropiate **target** +should be defined in a base chain. + +## Firewall - IPv4 Rules + +For firewall filtering, firewall rules needs to be created. Each rule is +numbered, has an action to apply if the rule is matched, and the ability +to specify multiple criteria matchers. Data packets go through the rules +from 1 - 999999, so order is crucial. At the first match the action of the +rule will be executed. + +### Actions + +If a rule is defined, then an action must be defined for it. This tells the +firewall what to do if all criteria matchers defined for such rule do match. + +The action can be : + +> - `accept`: accept the packet. +> - `continue`: continue parsing next rule. +> - `drop`: drop the packet. +> - `reject`: reject the packet. +> - `jump`: jump to another custom chain. +> - `return`: Return from the current chain and continue at the next rule +> of the last chain. +> - `queue`: Enqueue packet to userspace. +> - `synproxy`: synproxy the packet. + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> action + [accept | continue | drop | jump | queue | reject | return | synproxy] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> action + [accept | continue | drop | jump | queue | reject | return | synproxy] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> action + [accept | continue | drop | jump | queue | reject | return] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> action + [accept | continue | drop | jump | queue | reject | return] + + This required setting defines the action of the current rule. If action is + set to jump, then jump-target is also needed. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + jump-target <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + jump-target <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + jump-target <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + jump-target <text> + + To be used only when action is set to ``jump``. Use this command to specify + jump target. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + queue <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + queue <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + queue <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + queue <0-65535> + + To be used only when action is set to ``queue``. Use this command to specify + queue target to use. Queue range is also supported. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + queue-options bypass +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + queue-options bypass +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + queue-options bypass +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + queue-options bypass + + To be used only when action is set to ``queue``. Use this command to let + packet go through firewall when no userspace software is connected to the + queue. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + queue-options fanout +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + queue-options fanout +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + queue-options fanout +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + queue-options fanout + + To be used only when action is set to ``queue``. Use this command to + distribute packets between several queues. +``` + +Also, **default-action** is an action that takes place whenever a packet does +not match any rule in it's chain. For base chains, possible options for +**default-action** are **accept** or **drop**. + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter default-action + [accept | drop] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter default-action + [accept | drop] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter default-action + [accept | drop] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> default-action + [accept | drop | jump | queue | reject | return] + + This set the default action of the rule-set if no rule matched a packet + criteria. If default-action is set to ``jump``, then + ``default-jump-target`` is also needed. Note that for base chains, default + action can only be set to ``accept`` or ``drop``, while on custom chain, + more actions are available. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> default-jump-target <text> + + To be used only when ``defult-action`` is set to ``jump``. Use this + command to specify jump target for default rule. +``` + +:::{note} +**Important note about default-actions:** +If default action for any base chain is not defined, then the default +action is set to **accept** for that chain. For custom chains, if default +action is not defined, then the default-action is set to **drop**. +::: + +### Firewall Logs + +Logging can be enable for every single firewall rule. If enabled, other +log options can be defined. + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> log +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> log +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> log +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> log + + Enable logging for the matched packet. If this configuration command is not + present, then log is not enabled. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter default-log +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter default-log +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter default-log +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> default-log + + Use this command to enable the logging of the default action on + the specified chain. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + log-options level [emerg | alert | crit | err | warn | notice + | info | debug] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + log-options level [emerg | alert | crit | err | warn | notice + | info | debug] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + log-options level [emerg | alert | crit | err | warn | notice + | info | debug] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + log-options level [emerg | alert | crit | err | warn | notice + | info | debug] + + Define log-level. Only applicable if rule log is enable. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + log-options group <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + log-options group <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + log-options group <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + log-options group <0-65535> + + Define log group to send message to. Only applicable if rule log is enable. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + log-options snapshot-length <0-9000> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + log-options snapshot-length <0-9000> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + log-options snapshot-length <0-9000> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + log-options snapshot-length <0-9000> + + Define length of packet payload to include in netlink message. Only + applicable if rule log is enable and log group is defined. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + log-options queue-threshold <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + log-options queue-threshold <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + log-options queue-threshold <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + log-options queue-threshold <0-65535> + + Define number of packets to queue inside the kernel before sending them to + userspace. Only applicable if rule log is enable and log group is defined. +``` + +### Firewall Description + +For reference, a description can be defined for every single rule, and for +every defined custom chain. + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> description <text> + + Provide a rule-set description to a custom firewall chain. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + description <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + description <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + description <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> description <text> + + Provide a description for each rule. +``` + +### Rule Status + +When defining a rule, it is enable by default. In some cases, it is useful to +just disable the rule, rather than removing it. + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> disable +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> disable +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> disable +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> disable + + Command for disabling a rule but keep it in the configuration. +``` + +### Matching criteria + +There are a lot of matching criteria against which the packet can be tested. + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + connection-status nat [destination | source] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + connection-status nat [destination | source] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + connection-status nat [destination | source] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + connection-status nat [destination | source] + + Match criteria based on nat connection status. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + connection-mark <1-2147483647> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + connection-mark <1-2147483647> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + connection-mark <1-2147483647> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + connection-mark <1-2147483647> + + Match criteria based on connection mark. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + source address [address | addressrange | CIDR] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + source address [address | addressrange | CIDR] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + source address [address | addressrange | CIDR] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + source address [address | addressrange | CIDR] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + destination address [address | addressrange | CIDR] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + destination address [address | addressrange | CIDR] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + destination address [address | addressrange | CIDR] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + destination address [address | addressrange | CIDR] + + Match criteria based on source and/or destination address. This is similar + to the network groups part, but here you are able to negate the matching + addresses. + + .. code-block:: none + + set firewall ipv4 name FOO rule 50 source address 192.0.2.10-192.0.2.11 + # with a '!' the rule match everything except the specified subnet + set firewall ipv4 input filter FOO rule 51 source address !203.0.113.0/24 +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + source address-mask [address] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + source address-mask [address] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + source address-mask [address] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + source address-mask [address] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + destination address-mask [address] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + destination address-mask [address] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + destination address-mask [address] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + destination address-mask [address] + + An arbitrary netmask can be applied to mask addresses to only match against + a specific portion. + + This functions for both individual addresses and address groups. + + .. code-block:: none + + # Match any IPv4 address with `11` as the 2nd octet and `13` as the forth octet + set firewall ipv4 name FOO rule 100 destination address 0.11.0.13 + set firewall ipv4 name FOO rule 100 destination address-mask 0.255.0.255 +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + source fqdn <fqdn> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + source fqdn <fqdn> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + source fqdn <fqdn> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + source fqdn <fqdn> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + destination fqdn <fqdn> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + destination fqdn <fqdn> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + destination fqdn <fqdn> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + destination fqdn <fqdn> + + Specify a Fully Qualified Domain Name as source/destination matcher. Ensure + router is able to resolve such dns query. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + source geoip country-code <country> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + source geoip country-code <country> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + source geoip country-code <country> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + source geoip country-code <country> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + destination geoip country-code <country> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + destination geoip country-code <country> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + destination geoip country-code <country> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + destination geoip country-code <country> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + source geoip inverse-match +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + source geoip inverse-match +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + source geoip inverse-match +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + source geoip inverse-match +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + destination geoip inverse-match +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + destination geoip inverse-match +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + destination geoip inverse-match +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + destination geoip inverse-match + + Match IP addresses based on its geolocation. More info: `geoip matching + <https://wiki.nftables.org/wiki-nftables/index.php/GeoIP_matching>`_. + Use inverse-match to match anything except the given country-codes. +``` + +Data is provided by DB-IP.com under CC-BY-4.0 license. Attribution required, +permits redistribution so we can include a database in images(~3MB +compressed). Includes cron script (manually callable by op-mode update +geoip) to keep database and rules updated. + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + source mac-address <mac-address> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + source mac-address <mac-address> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + source mac-address <mac-address> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + source mac-address <mac-address> + + Only in the source criteria, you can specify a mac-address. + + .. code-block:: none + + set firewall ipv4 input filter rule 100 source mac-address 00:53:00:11:22:33 + set firewall ipv4 input filter rule 101 source mac-address !00:53:00:aa:12:34 + +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + source port [1-65535 | portname | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + source port [1-65535 | portname | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + source port [1-65535 | portname | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + source port [1-65535 | portname | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + destination port [1-65535 | portname | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + destination port [1-65535 | portname | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + destination port [1-65535 | portname | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + destination port [1-65535 | portname | start-end] + + A port can be set with a port number or a name which is here + defined: ``/etc/services``. + + .. code-block:: none + + set firewall ipv4 forward filter rule 10 source port '22' + set firewall ipv4 forward filter rule 11 source port '!http' + set firewall ipv4 forward filter rule 12 source port 'https' + + Multiple source ports can be specified as a comma-separated list. + The whole list can also be "negated" using ``!``. For example: +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + source group address-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + source group address-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + source group address-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + source group address-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + destination group address-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + destination group address-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + destination group address-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + destination group address-group <name | !name> + + Use a specific address-group. Prepend character ``!`` for inverted matching + criteria. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + source group dynamic-address-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + source group dynamic-address-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + source group dynamic-address-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + source group dynamic-address-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + destination group dynamic-address-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + destination group dynamic-address-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + destination group dynamic-address-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + destination group dynamic-address-group <name | !name> + + Use a specific dynamic-address-group. Prepend character ``!`` for inverted + matching criteria. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + source group network-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + source group network-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + source group network-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + source group network-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + destination group network-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + destination group network-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + destination group network-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + destination group network-group <name | !name> + + Use a specific network-group. Prepend character ``!`` for inverted matching + criteria. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + source group port-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + source group port-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + source group port-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + source group port-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + destination group port-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + destination group port-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + destination group port-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + destination group port-group <name | !name> + + Use a specific port-group. Prepend character ``!`` for inverted matching + criteria. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + source group domain-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + source group domain-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + source group domain-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + source group domain-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + destination group domain-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + destination group domain-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + destination group domain-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + destination group domain-group <name | !name> + + Use a specific domain-group. Prepend character ``!`` for inverted matching + criteria. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + source group mac-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + source group mac-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + source group mac-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + source group mac-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + destination group mac-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + destination group mac-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + destination group mac-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + destination group mac-group <name | !name> + + Use a specific mac-group. Prepend character ``!`` for inverted matching + criteria. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + dscp [0-63 | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + dscp [0-63 | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + dscp [0-63 | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + dscp [0-63 | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + dscp-exclude [0-63 | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + dscp-exclude [0-63 | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + dscp-exclude [0-63 | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + dscp-exclude [0-63 | start-end] + + Match based on dscp value. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + fragment [match-frag | match-non-frag] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + fragment [match-frag | match-non-frag] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + fragment [match-frag | match-non-frag] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + fragment [match-frag | match-non-frag] + + Match based on fragment criteria. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + icmp [code | type] <0-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + icmp [code | type] <0-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + icmp [code | type] <0-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + icmp [code | type] <0-255> + + Match based on icmp code and type. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + icmp type-name <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + icmp type-name <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + icmp type-name <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + icmp type-name <text> + + Match based on icmp type-name criteria. Use tab for information + about what **type-name** criteria are supported. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + inbound-interface name <iface> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + inbound-interface name <iface> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + inbound-interface name <iface> + + Match based on inbound interface. Wilcard ``*`` can be used. + For example: ``eth2*``. Prepending character ``!`` for inverted matching + criteria is also supportd. For example ``!eth2`` +``` + +:::{note} +If an interface is attached to a non-default vrf, when using +**inbound-interface**, vrf name must be used. For example `set firewall +ipv4 forward filter rule 10 inbound-interface name MGMT` +::: + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + inbound-interface group <iface_group> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + inbound-interface group <iface_group> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + inbound-interface group <iface_group> + + Match based on inbound interface group. Prepending character ``!`` for + inverted matching criteria is also supportd. For example ``!IFACE_GROUP`` +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + outbound-interface name <iface> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + outbound-interface name <iface> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + outbound-interface name <iface> + + Match based on outbound interface. Wilcard ``*`` can be used. + For example: ``eth2*``. Prepending character ``!`` for inverted matching + criteria is also supportd. For example ``!eth2`` +``` + +:::{note} +If an interface is attached to a non-default vrf, when using +**outbound-interface**, real interface name must be used. For example +`set firewall ipv4 forward filter rule 10 outbound-interface name eth0` +::: + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + outbound-interface group <iface_group> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + outbound-interface group <iface_group> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + outbound-interface group <iface_group> + + Match based on outbound interface group. Prepending character ``!`` for + inverted matching criteria is also supportd. For example ``!IFACE_GROUP`` +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + ipsec [match-ipsec | match-none] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + ipsec [match-ipsec | match-none] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + ipsec [match-ipsec | match-none] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + ipsec [match-ipsec | match-none] + + Match based on ipsec criteria. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + limit burst <0-4294967295> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + limit burst <0-4294967295> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + limit burst <0-4294967295> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + limit burst <0-4294967295> + + Match based on the maximum number of packets to allow in excess of rate. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + limit rate <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + limit rate <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + limit rate <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + limit rate <text> + + Match based on the maximum average rate, specified as **integer/unit**. + For example **5/minutes** +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + packet-length <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + packet-length <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + packet-length <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + packet-length <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + packet-length-exclude <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + packet-length-exclude <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + packet-length-exclude <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + packet-length-exclude <text> + + Match based on packet length criteria. Multiple values from 1 to 65535 + and ranges are supported. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + packet-type [broadcast | host | multicast | other] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + packet-type [broadcast | host | multicast | other] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + packet-type [broadcast | host | multicast | other] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + packet-type [broadcast | host | multicast | other] + + Match based on packet type criteria. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + protocol [<text> | <0-255> | all | tcp_udp] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + protocol [<text> | <0-255> | all | tcp_udp] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + protocol [<text> | <0-255> | all | tcp_udp] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + protocol [<text> | <0-255> | all | tcp_udp] + + Match a protocol criteria. A protocol number or a name which is here + defined: ``/etc/protocols``. + Special names are ``all`` for all protocols and ``tcp_udp`` for tcp and udp + based packets. The ``!`` negate the selected protocol. + + .. code-block:: none + + set firewall ipv4 forward fitler rule 10 protocol tcp_udp + set firewall ipv4 forward fitler rule 11 protocol !tcp_udp +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + recent time [second | minute | hour] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + recent time [second | minute | hour] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + recent time [second | minute | hour] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + recent time [second | minute | hour] + + Match bases on recently seen sources. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + tcp flags [not] <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + tcp flags [not] <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + tcp flags [not] <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + tcp flags [not] <text> + + Allowed values fpr TCP flags: ``ack``, ``cwr``, ``ecn``, ``fin``, ``psh``, + ``rst``, ``syn`` and ``urg``. Multiple values are supported, and for + inverted selection use ``not``, as shown in the example. + + .. code-block:: none + + set firewall ipv4 input filter rule 10 tcp flags 'ack' + set firewall ipv4 input filter rule 12 tcp flags 'syn' + set firewall ipv4 input filter rule 13 tcp flags not 'fin' +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + state [established | invalid | new | related] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + state [established | invalid | new | related] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + state [established | invalid | new | related] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + state [established | invalid | new | related] + + Match against the state of a packet. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + time startdate <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + time startdate <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + time startdate <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + time startdate <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + time starttime <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + time starttime <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + time starttime <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + time starttime <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + time stopdate <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + time stopdate <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + time stopdate <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + time stopdate <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + time stoptime <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + time stoptime <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + time stoptime <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + time stoptime <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + time weekdays <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + time weekdays <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + time weekdays <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + time weekdays <text> + + Time to match the defined rule. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + ttl <eq | gt | lt> <0-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + ttl <eq | gt | lt> <0-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + ttl <eq | gt | lt> <0-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + ttl <eq | gt | lt> <0-255> + + Match time to live parameter, where 'eq' stands for 'equal'; 'gt' stands for + 'greater than', and 'lt' stands for 'less than'. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + recent time <second | minute | hour> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + recent time <second | minute | hour> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + recent time <second | minute | hour> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + recent time <second | minute | hour> + + Match when 'count' amount of connections are seen within 'time'. These + matching criteria can be used to block brute-force attempts. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + conntrack-helper <module> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + conntrack-helper <module> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + conntrack-helper <module> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + conntrack-helper <module> + + Match based on connection tracking protocol helper module to secure use of + that helper module. See below for possible completions `<module>`. + + .. code-block:: none + + Possible completions: + ftp Related traffic from FTP helper + h323 Related traffic from H.323 helper + pptp Related traffic from PPTP helper + nfs Related traffic from NFS helper + sip Related traffic from SIP helper + tftp Related traffic from TFTP helper + sqlnet Related traffic from SQLNet helper + +``` + +## Synproxy + +Synproxy connections + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 [input | forward] filter rule <1-999999> + action synproxy +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 [input | forward] filter rule <1-999999> + protocol tcp +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 [input | forward] filter rule <1-999999> + synproxy tcp mss <501-65535> + + Set TCP-MSS (maximum segment size) for the connection +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 [input | forward] filter rule <1-999999> + synproxy tcp window-scale <1-14> + + Set the window scale factor for TCP window scaling +``` + +### Example synproxy + +Requirements to enable synproxy: + +> - Traffic must be symmetric +> - Synproxy relies on syncookies and TCP timestamps, ensure these are enabled +> - Disable conntrack loose track option + +```none +set system sysctl parameter net.ipv4.tcp_timestamps value '1' + +set system conntrack tcp loose disable +set system conntrack ignore ipv4 rule 10 destination port '8080' +set system conntrack ignore ipv4 rule 10 protocol 'tcp' +set system conntrack ignore ipv4 rule 10 tcp flags syn + +set firewall global-options syn-cookies 'enable' +set firewall ipv4 input filter rule 10 action 'synproxy' +set firewall ipv4 input filter rule 10 destination port '8080' +set firewall ipv4 input filter rule 10 inbound-interface name 'eth1' +set firewall ipv4 input filter rule 10 protocol 'tcp' +set firewall ipv4 input filter rule 10 synproxy tcp mss '1460' +set firewall ipv4 input filter rule 10 synproxy tcp window-scale '7' +set firewall ipv4 input filter rule 1000 action 'drop' +set firewall ipv4 input filter rule 1000 state invalid +``` + +## Operation-mode Firewall + +### Rule-set overview + +```{eval-rst} +.. opcmd:: show firewall + + This will show you a basic firewall overview, for all ruleset, and not + only for ipv4 + + .. code-block:: none + + vyos@vyos:~$ show firewall + Rulesets Information + + --------------------------------- + ipv4 Firewall "forward filter" + + Rule Action Protocol Packets Bytes Conditions + ------- -------- ---------- --------- ------- ----------------------------- + 20 accept all 0 0 ip saddr @N_TRUSTEDv4 accept + 21 jump all 0 0 jump NAME_AUX + default accept all 0 0 + + --------------------------------- + ipv4 Firewall "input filter" + + Rule Action Protocol Packets Bytes Conditions + ------- -------- ---------- --------- ------- ------------------------- + 10 accept all 156 14377 iifname != @I_LAN accept + default accept all 0 0 + + --------------------------------- + ipv4 Firewall "name AUX" + + Rule Action Protocol Packets Bytes Conditions + ------ -------- ---------- --------- ------- -------------------------------------------- + 10 accept icmp 0 0 meta l4proto icmp accept + 20 accept udp 0 0 meta l4proto udp ip saddr @A_SERVERS accept + 30 drop all 0 0 ip saddr != @A_SERVERS iifname "eth2" + + --------------------------------- + ipv4 Firewall "output filter" + + Rule Action Protocol Packets Bytes Conditions + ------- -------- ---------- --------- ------- ---------------------------------------- + 10 reject all 0 0 oifname @I_LAN + 20 accept icmp 2 168 meta l4proto icmp oifname "eth0" accept + default accept all 72 9258 + + --------------------------------- + ipv6 Firewall "input filter" + + Rule Action Protocol Packets Bytes Conditions + ------- -------- ---------- --------- ------- ------------------------------- + 10 accept all 0 0 ip6 saddr @N6_TRUSTEDv6 accept + default accept all 2 112 + + vyos@vyos:~$ +``` + +```{eval-rst} +.. opcmd:: show firewall summary + + This will show you a summary of rule-sets and groups + + .. code-block:: none + + vyos@vyos:~$ show firewall summary + Ruleset Summary + + IPv6 Ruleset: + + Ruleset Hook Ruleset Priority Description + -------------- -------------------- ------------------------- + forward filter + input filter + ipv6_name IPV6-VyOS_MANAGEMENT + ipv6_name IPV6-WAN_IN PUBLIC_INTERNET + + IPv4 Ruleset: + + Ruleset Hook Ruleset Priority Description + -------------- ------------------ ------------------------- + forward filter + input filter + name VyOS_MANAGEMENT + name WAN_IN PUBLIC_INTERNET + + Firewall Groups + + Name Type References Members + ----------------------- ------------------ ----------------------- ---------------- + PBX address_group WAN_IN-100 198.51.100.77 + SERVERS address_group WAN_IN-110 192.0.2.10 + WAN_IN-111 192.0.2.11 + WAN_IN-112 192.0.2.12 + WAN_IN-120 + WAN_IN-121 + WAN_IN-122 + SUPPORT address_group VyOS_MANAGEMENT-20 192.168.1.2 + WAN_IN-20 + PHONE_VPN_SERVERS address_group WAN_IN-160 10.6.32.2 + PINGABLE_ADRESSES address_group WAN_IN-170 192.168.5.2 + WAN_IN-171 + PBX ipv6_address_group IPV6-WAN_IN-100 2001:db8::1 + SERVERS ipv6_address_group IPV6-WAN_IN-110 2001:db8::2 + IPV6-WAN_IN-111 2001:db8::3 + IPV6-WAN_IN-112 2001:db8::4 + IPV6-WAN_IN-120 + IPV6-WAN_IN-121 + IPV6-WAN_IN-122 + SUPPORT ipv6_address_group IPV6-VyOS_MANAGEMENT-20 2001:db8::5 + IPV6-WAN_IN-20 + +``` + +```{eval-rst} +.. opcmd:: show firewall ipv4 [forward | input | output] filter +``` + +```{eval-rst} +.. opcmd:: show firewall ipv4 name <name> + + This command will give an overview of a single rule-set. + + .. code-block:: none + + vyos@vyos:~$ show firewall ipv4 input filter + Ruleset Information + + --------------------------------- + IPv4 Firewall "input filter" + + Rule Action Protocol Packets Bytes Conditions + ------- -------- ---------- --------- ------- ----------------------------------------- + 5 jump all 0 0 iifname "eth2" jump NAME_VyOS_MANAGEMENT + default accept all +``` + +```{eval-rst} +.. opcmd:: show firewall ipv4 [forward | input | output] + filter rule <1-999999> +``` + +```{eval-rst} +.. opcmd:: show firewall ipv4 name <name> rule <1-999999> + + This command will give an overview of a rule in a single rule-set, plus + information for default action. +``` + +```none +vyos@vyos:~$show firewall ipv4 output filter rule 20 +Rule Information + +--------------------------------- +ipv4 Firewall "output filter" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- ---------------------------------------- +20 accept icmp 2 168 meta l4proto icmp oifname "eth0" accept +default accept all 286 47614 + +vyos@vyos:~$ +``` + +```{eval-rst} +.. opcmd:: show firewall statistics + + This will show you a statistic of all rule-sets since the last boot. +``` + +### Show Firewall log + +```{eval-rst} +.. opcmd:: show log firewall +``` + +```{eval-rst} +.. opcmd:: show log firewall ipv4 +``` + +```{eval-rst} +.. opcmd:: show log firewall ipv4 [forward | input | output | name] +``` + +```{eval-rst} +.. opcmd:: show log firewall ipv4 [forward | input | output] filter +``` + +```{eval-rst} +.. opcmd:: show log firewall ipv4 name <name> +``` + +```{eval-rst} +.. opcmd:: show log firewall ipv4 [forward | input | output] filter rule <rule> +``` + +```{eval-rst} +.. opcmd:: show log firewall ipv4 name <name> rule <rule> + + Show the logs of all firewall; show all ipv4 firewall logs; show all logs + for particular hook; show all logs for particular hook and priority; + show all logs for particular custom chain; show logs for specific Rule-Set. +``` + +### Example Partial Config + +```none +firewall { + 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 + } + } + ipv4 { + forward { + filter { + default-action accept + rule 5 { + action accept + source { + group { + network-group GOOD-NETWORKS + } + } + } + rule 10 { + action drop + description "Bad Networks" + protocol all + source { + group { + network-group BAD-NETWORKS + } + } + } + } + } + } +} +``` + +### Update geoip database + +```{eval-rst} +.. opcmd:: update geoip + + Command used to update GeoIP database and firewall sets. +``` diff --git a/docs/configuration/firewall/md-ipv6.md b/docs/configuration/firewall/md-ipv6.md new file mode 100644 index 00000000..e2db7928 --- /dev/null +++ b/docs/configuration/firewall/md-ipv6.md @@ -0,0 +1,2026 @@ +--- +lastproofread: '2023-11-08' +--- + +(firewall-ipv6-configuration)= + +# IPv6 Firewall Configuration + +## Overview + +In this section there's useful information of all firewall configuration that +can be done regarding IPv6, and appropiate op-mode commands. +Configuration commands covered in this section: + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 ... +``` + +From main structure defined in +{doc}`Firewall Overview</configuration/firewall/index>` +in this section you can find detailed information only for the next part +of the general structure: + +```none +- set firewall + * ipv6 + - forward + + filter + - input + + filter + - output + + filter + - name + + custom_name +``` + +For transit traffic, which is received by the router and forwarded, base chain +is **forward**. A simplified packet flow diagram for transit traffic is shown +next: + +:::{figure} /_static/images/firewall-fwd-packet-flow.png +::: + +Where firewall base chain to configure firewall filtering rules for transit +traffic is `set firewall ipv6 forward filter ...`, which happens in stage 5, +highlightened with red color. + +For traffic towards the router itself, base chain is **input**, while traffic +originated by the router, base chain is **output**. +A new simplified packet flow diagram is shown next, which shows the path +for traffic destinated to the router itself, and traffic generated by the +router (starting from circle number 6): + +:::{figure} /_static/images/firewall-input-packet-flow.png +::: + +Base chain is for traffic toward the router is `set firewall ipv6 input +filter ...` + +And base chain for traffic generated by the router is `set firewall ipv6 +output filter ...` + +:::{note} +**Important note about default-actions:** +If default action for any base chain is not defined, then the default +action is set to **accept** for that chain. For custom chains, if default +action is not defined, then the default-action is set to **drop** +::: + +Custom firewall chains can be created, with commands +`set firewall ipv6 name <name> ...`. In order to use +such custom chain, a rule with **action jump**, and the appropiate **target** +should be defined in a base chain. + +## Firewall - IPv6 Rules + +For firewall filtering, firewall rules needs to be created. Each rule is +numbered, has an action to apply if the rule is matched, and the ability +to specify multiple criteria matchers. Data packets go through the rules +from 1 - 999999, so order is crucial. At the first match the action of the +rule will be executed. + +### Actions + +If a rule is defined, then an action must be defined for it. This tells the +firewall what to do if all criteria matchers defined for such rule do match. + +The action can be : + +> - `accept`: accept the packet. +> - `continue`: continue parsing next rule. +> - `drop`: drop the packet. +> - `reject`: reject the packet. +> - `jump`: jump to another custom chain. +> - `return`: Return from the current chain and continue at the next rule +> of the last chain. +> - `queue`: Enqueue packet to userspace. +> - `synproxy`: synproxy the packet. + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> action + [accept | continue | drop | jump | queue | reject | return | synproxy] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> action + [accept | continue | drop | jump | queue | reject | return | synproxy] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> action + [accept | continue | drop | jump | queue | reject | return] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> action + [accept | continue | drop | jump | queue | reject | return] + + This required setting defines the action of the current rule. If action is + set to jump, then jump-target is also needed. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + jump-target <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + jump-target <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + jump-target <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + jump-target <text> + + To be used only when action is set to ``jump``. Use this command to specify + jump target. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + queue <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + queue <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + queue <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + queue <0-65535> + + To be used only when action is set to ``queue``. Use this command to specify + queue target to use. Queue range is also supported. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + queue-options bypass +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + queue-options bypass +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + queue-options bypass +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + queue-options bypass + + To be used only when action is set to ``queue``. Use this command to let + packet go through firewall when no userspace software is connected to the + queue. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + queue-options fanout +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + queue-options fanout +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + queue-options fanout +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + queue-options fanout + + To be used only when action is set to ``queue``. Use this command to + distribute packets between several queues. +``` + +Also, **default-action** is an action that takes place whenever a packet does +not match any rule in it's chain. For base chains, possible options for +**default-action** are **accept** or **drop**. + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter default-action + [accept | drop] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter default-action + [accept | drop] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter default-action + [accept | drop] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> default-action + [accept | drop | jump | queue | reject | return] + + This set the default action of the rule-set if no rule matched a packet + criteria. If default-action is set to ``jump``, then + ``default-jump-target`` is also needed. Note that for base chains, default + action can only be set to ``accept`` or ``drop``, while on custom chain, + more actions are available. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> default-jump-target <text> + + To be used only when ``defult-action`` is set to ``jump``. Use this + command to specify jump target for default rule. +``` + +:::{note} +**Important note about default-actions:** +If default action for any base chain is not defined, then the default +action is set to **accept** for that chain. For custom chains, if default +action is not defined, then the default-action is set to **drop**. +::: + +### Firewall Logs + +Logging can be enable for every single firewall rule. If enabled, other +log options can be defined. + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> log +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> log +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> log +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> log + + Enable logging for the matched packet. If this configuration command is not + present, then log is not enabled. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter default-log +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter default-log +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter default-log +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> default-log + + Use this command to enable the logging of the default action on + the specified chain. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + log-options level [emerg | alert | crit | err | warn | notice + | info | debug] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + log-options level [emerg | alert | crit | err | warn | notice + | info | debug] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + log-options level [emerg | alert | crit | err | warn | notice + | info | debug] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + log-options level [emerg | alert | crit | err | warn | notice + | info | debug] + + Define log-level. Only applicable if rule log is enable. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + log-options group <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + log-options group <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + log-options group <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + log-options group <0-65535> + + Define log group to send message to. Only applicable if rule log is enable. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + log-options snapshot-length <0-9000> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + log-options snapshot-length <0-9000> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + log-options snapshot-length <0-9000> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + log-options snapshot-length <0-9000> + + Define length of packet payload to include in netlink message. Only + applicable if rule log is enable and log group is defined. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + log-options queue-threshold <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + log-options queue-threshold <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + log-options queue-threshold <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + log-options queue-threshold <0-65535> + + Define number of packets to queue inside the kernel before sending them to + userspace. Only applicable if rule log is enable and log group is defined. +``` + +### Firewall Description + +For reference, a description can be defined for every single rule, and for +every defined custom chain. + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> description <text> + + Provide a rule-set description to a custom firewall chain. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + description <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + description <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + description <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> description <text> + + Provide a description for each rule. +``` + +### Rule Status + +When defining a rule, it is enable by default. In some cases, it is useful to +just disable the rule, rather than removing it. + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> disable +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> disable +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> disable +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> disable + + Command for disabling a rule but keep it in the configuration. +``` + +### Matching criteria + +There are a lot of matching criteria against which the packet can be tested. + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + connection-status nat [destination | source] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + connection-status nat [destination | source] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + connection-status nat [destination | source] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + connection-status nat [destination | source] + + Match criteria based on nat connection status. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + connection-mark <1-2147483647> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + connection-mark <1-2147483647> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + connection-mark <1-2147483647> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + connection-mark <1-2147483647> + + Match criteria based on connection mark. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + source address [address | addressrange | CIDR] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + source address [address | addressrange | CIDR] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + source address [address | addressrange | CIDR] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + source address [address | addressrange | CIDR] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + destination address [address | addressrange | CIDR] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + destination address [address | addressrange | CIDR] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + destination address [address | addressrange | CIDR] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + destination address [address | addressrange | CIDR] + + Match criteria based on source and/or destination address. This is similar + to the network groups part, but here you are able to negate the matching + addresses. + + .. code-block:: none + + set firewall ipv6 name FOO rule 100 source address 2001:db8::202 +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + source address-mask [address] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + source address-mask [address] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + source address-mask [address] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + source address-mask [address] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + destination address-mask [address] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + destination address-mask [address] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + destination address-mask [address] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + destination address-mask [address] + + An arbitrary netmask can be applied to mask addresses to only match against + a specific portion. This is particularly useful with IPv6 as rules will + remain valid if the IPv6 prefix changes and the host + portion of systems IPv6 address is static (for example, with SLAAC or + `tokenised IPv6 addresses + <https://datatracker.ietf.org + /doc/id/draft-chown-6man-tokenised-ipv6-identifiers-02.txt>`_) + + This functions for both individual addresses and address groups. + + .. stop_vyoslinter + .. code-block:: none + + # Match any IPv6 address with the suffix ::0000:0000:0000:beef + set firewall ipv6 forward filter rule 100 destination address ::beef + set firewall ipv6 forward filter rule 100 destination address-mask ::ffff:ffff:ffff:ffff + # Address groups + set firewall group ipv6-address-group WEBSERVERS address ::1000 + set firewall group ipv6-address-group WEBSERVERS address ::2000 + set firewall ipv6 forward filter rule 200 source group address-group WEBSERVERS + set firewall ipv6 forward filter rule 200 source address-mask ::ffff:ffff:ffff:ffff + + .. start_vyoslinter +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + source fqdn <fqdn> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + source fqdn <fqdn> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + source fqdn <fqdn> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + source fqdn <fqdn> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + destination fqdn <fqdn> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + destination fqdn <fqdn> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + destination fqdn <fqdn> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + destination fqdn <fqdn> + + Specify a Fully Qualified Domain Name as source/destination matcher. Ensure + router is able to resolve such dns query. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + source geoip country-code <country> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + source geoip country-code <country> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + source geoip country-code <country> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + source geoip country-code <country> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + destination geoip country-code <country> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + destination geoip country-code <country> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + destination geoip country-code <country> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + destination geoip country-code <country> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + source geoip inverse-match +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + source geoip inverse-match +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + source geoip inverse-match +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + source geoip inverse-match +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + destination geoip inverse-match +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + destination geoip inverse-match +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + destination geoip inverse-match +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + destination geoip inverse-match + + Match IP addresses based on its geolocation. More info: `geoip matching + <https://wiki.nftables.org/wiki-nftables/index.php/GeoIP_matching>`_. + Use inverse-match to match anything except the given country-codes. +``` + +Data is provided by DB-IP.com under CC-BY-4.0 license. Attribution required, +permits redistribution so we can include a database in images(~3MB +compressed). Includes cron script (manually callable by op-mode update +geoip) to keep database and rules updated. + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + source mac-address <mac-address> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + source mac-address <mac-address> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + source mac-address <mac-address> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + source mac-address <mac-address> + + Only in the source criteria, you can specify a mac-address. + + .. code-block:: none + + set firewall ipv6 input filter rule 100 source mac-address 00:53:00:11:22:33 + set firewall ipv6 input filter rule 101 source mac-address !00:53:00:aa:12:34 +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + source port [1-65535 | portname | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + source port [1-65535 | portname | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + source port [1-65535 | portname | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + source port [1-65535 | portname | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + destination port [1-65535 | portname | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + destination port [1-65535 | portname | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + destination port [1-65535 | portname | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + destination port [1-65535 | portname | start-end] + + A port can be set with a port number or a name which is here + defined: ``/etc/services``. + + .. code-block:: none + + set firewall ipv6 forward filter rule 10 source port '22' + set firewall ipv6 forward filter rule 11 source port '!http' + set firewall ipv6 forward filter rule 12 source port 'https' + + Multiple source ports can be specified as a comma-separated list. + The whole list can also be "negated" using ``!``. For example: + + .. code-block:: none + + set firewall ipv6 forward filter rule 10 source port '!22,https,3333-3338' +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + source group address-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + source group address-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + source group address-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + source group address-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + destination group address-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + destination group address-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + destination group address-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + destination group address-group <name | !name> + + Use a specific address-group. Prepend character ``!`` for inverted matching + criteria. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + source group dynamic-address-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + source group dynamic-address-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + source group dynamic-address-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + source group dynamic-address-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + destination group dynamic-address-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + destination group dynamic-address-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + destination group dynamic-address-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + destination group dynamic-address-group <name | !name> + + Use a specific dynamic-address-group. Prepend character ``!`` for inverted + matching criteria. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + source group network-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + source group network-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + source group network-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + source group network-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + destination group network-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + destination group network-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + destination group network-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + destination group network-group <name | !name> + + Use a specific network-group. Prepend character ``!`` for inverted matching + criteria. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + source group port-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + source group port-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + source group port-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + source group port-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + destination group port-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + destination group port-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + destination group port-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + destination group port-group <name | !name> + + Use a specific port-group. Prepend character ``!`` for inverted matching + criteria. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + source group domain-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + source group domain-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + source group domain-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + source group domain-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + destination group domain-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + destination group domain-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + destination group domain-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + destination group domain-group <name | !name> + + Use a specific domain-group. Prepend character ``!`` for inverted matching + criteria. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + source group mac-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + source group mac-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + source group mac-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + source group mac-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + destination group mac-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + destination group mac-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + destination group mac-group <name | !name> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + destination group mac-group <name | !name> + + Use a specific mac-group. Prepend character ``!`` for inverted matching + criteria. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + dscp [0-63 | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + dscp [0-63 | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + dscp [0-63 | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + dscp [0-63 | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + dscp-exclude [0-63 | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + dscp-exclude [0-63 | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + dscp-exclude [0-63 | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + dscp-exclude [0-63 | start-end] + + Match based on dscp value. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + fragment [match-frag | match-non-frag] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + fragment [match-frag | match-non-frag] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + fragment [match-frag | match-non-frag] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + fragment [match-frag | match-non-frag] + + Match based on fragment criteria. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + icmpv6 [code | type] <0-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + icmpv6 [code | type] <0-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + icmpv6 [code | type] <0-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + icmpv6 [code | type] <0-255> + + Match based on icmp|icmpv6 code and type. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + icmpv6 type-name <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + icmpv6 type-name <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + icmpv6 type-name <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + icmpv6 type-name <text> + + Match based on icmpv6 type-name criteria. Use tab for information + about what **type-name** criteria are supported. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + inbound-interface name <iface> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + inbound-interface name <iface> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + inbound-interface name <iface> + + Match based on inbound interface. Wilcard ``*`` can be used. + For example: ``eth2*``. Prepending character ``!`` for inverted matching + criteria is also supportd. For example ``!eth2`` +``` + +:::{note} +If an interface is attached to a non-default vrf, when using +**inbound-interface**, vrf name must be used. For example `set firewall +ipv6 forward filter rule 10 inbound-interface name MGMT` +::: + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + inbound-interface group <iface_group> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + inbound-interface group <iface_group> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + inbound-interface group <iface_group> + + Match based on inbound interface group. Prepending character ``!`` for + inverted matching criteria is also supportd. For example ``!IFACE_GROUP`` +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + outbound-interface name <iface> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + outbound-interface name <iface> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + outbound-interface name <iface> + + Match based on outbound interface. Wilcard ``*`` can be used. + For example: ``eth2*``. Prepending character ``!`` for inverted matching + criteria is also supportd. For example ``!eth2`` +``` + +:::{note} +If an interface is attached to a non-default vrf, when using +**outbound-interface**, real interface name must be used. For example +`set firewall ipv6 forward filter rule 10 outbound-interface name eth0` +::: + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + outbound-interface group <iface_group> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + outbound-interface group <iface_group> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + outbound-interface group <iface_group> + + Match based on outbound interface group. Prepending character ``!`` for + inverted matching criteria is also supportd. For example ``!IFACE_GROUP`` +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + ipsec [match-ipsec | match-none] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + ipsec [match-ipsec | match-none] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + ipsec [match-ipsec | match-none] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + ipsec [match-ipsec | match-none] + + Match based on ipsec criteria. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + limit burst <0-4294967295> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + limit burst <0-4294967295> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + limit burst <0-4294967295> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + limit burst <0-4294967295> + + Match based on the maximum number of packets to allow in excess of rate. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + limit rate <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + limit rate <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + limit rate <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + limit rate <text> + + Match based on the maximum average rate, specified as **integer/unit**. + For example **5/minutes** +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + packet-length <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + packet-length <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + packet-length <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + packet-length <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + packet-length-exclude <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + packet-length-exclude <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + packet-length-exclude <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + packet-length-exclude <text> + + Match based on packet length criteria. Multiple values from 1 to 65535 + and ranges are supported. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + packet-type [broadcast | host | multicast | other] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + packet-type [broadcast | host | multicast | other] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + packet-type [broadcast | host | multicast | other] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + packet-type [broadcast | host | multicast | other] + + Match based on packet type criteria. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + protocol [<text> | <0-255> | all | tcp_udp] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + protocol [<text> | <0-255> | all | tcp_udp] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + protocol [<text> | <0-255> | all | tcp_udp] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + protocol [<text> | <0-255> | all | tcp_udp] + + Match a protocol criteria. A protocol number or a name which is here + defined: ``/etc/protocols``. + Special names are ``all`` for all protocols and ``tcp_udp`` for tcp and udp + based packets. The ``!`` negate the selected protocol. + + .. code-block:: none + + set firewall ipv6 input filter rule 10 protocol tcp +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + recent time [second | minute | hour] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + recent time [second | minute | hour] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + recent time [second | minute | hour] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + recent time [second | minute | hour] + + Match bases on recently seen sources. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + tcp flags [not] <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + tcp flags [not] <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + tcp flags [not] <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + tcp flags [not] <text> + + Allowed values fpr TCP flags: ``ack``, ``cwr``, ``ecn``, ``fin``, ``psh``, + ``rst``, ``syn`` and ``urg``. Multiple values are supported, and for + inverted selection use ``not``, as shown in the example. + + .. code-block:: none + + set firewall ipv6 input filter rule 10 tcp flags 'ack' + set firewall ipv6 input filter rule 12 tcp flags 'syn' + set firewall ipv6 input filter rule 13 tcp flags not 'fin' +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + state [established | invalid | new | related] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + state [established | invalid | new | related] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + state [established | invalid | new | related] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + state [established | invalid | new | related] + + Match against the state of a packet. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + time startdate <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + time startdate <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + time startdate <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + time startdate <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + time starttime <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + time starttime <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + time starttime <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + time starttime <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + time stopdate <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + time stopdate <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + time stopdate <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + time stopdate <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + time stoptime <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + time stoptime <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + time stoptime <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + time stoptime <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + time weekdays <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + time weekdays <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + time weekdays <text> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + time weekdays <text> + + Time to match the defined rule. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + hop-limit <eq | gt | lt> <0-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + hop-limit <eq | gt | lt> <0-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + hop-limit <eq | gt | lt> <0-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + hop-limit <eq | gt | lt> <0-255> + + Match hop-limit parameter, where 'eq' stands for 'equal'; 'gt' stands for + 'greater than', and 'lt' stands for 'less than'. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + recent time <second | minute | hour> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + recent time <second | minute | hour> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + recent time <second | minute | hour> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + recent time <second | minute | hour> + + Match when 'count' amount of connections are seen within 'time'. These + matching criteria can be used to block brute-force attempts. +``` + +## Synproxy + +Synproxy connections + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 [input | forward] filter rule <1-999999> + action synproxy +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 [input | forward] filter rule <1-999999> + protocol tcp +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 [input | forward] filter rule <1-999999> + synproxy tcp mss <501-65535> + + Set TCP-MSS (maximum segment size) for the connection +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 [input | forward] filter rule <1-999999> + synproxy tcp window-scale <1-14> + + Set the window scale factor for TCP window scaling +``` + +### Example synproxy + +Requirements to enable synproxy: + +> - Traffic must be symmetric +> - Synproxy relies on syncookies and TCP timestamps, ensure these are enabled +> - Disable conntrack loose track option + +```none +set system sysctl parameter net.ipv4.tcp_timestamps value '1' + +set system conntrack tcp loose disable +set system conntrack ignore ipv6 rule 10 destination port '8080' +set system conntrack ignore ipv6 rule 10 protocol 'tcp' +set system conntrack ignore ipv6 rule 10 tcp flags syn + +set firewall global-options syn-cookies 'enable' +set firewall ipv6 input filter rule 10 action 'synproxy' +set firewall ipv6 input filter rule 10 destination port '8080' +set firewall ipv6 input filter rule 10 inbound-interface name 'eth1' +set firewall ipv6 input filter rule 10 protocol 'tcp' +set firewall ipv6 input filter rule 10 synproxy tcp mss '1460' +set firewall ipv6 input filter rule 10 synproxy tcp window-scale '7' +set firewall ipv6 input filter rule 1000 action 'drop' +set firewall ipv6 input filter rule 1000 state invalid +``` + +## Operation-mode Firewall + +### Rule-set overview + +```{eval-rst} +.. opcmd:: show firewall + + This will show you a basic firewall overview + + .. code-block:: none + + vyos@vyos:~$ show firewall + Rulesets Information + + --------------------------------- + IPv4 Firewall "forward filter" + + Rule Action Protocol Packets Bytes Conditions + ------- -------- ---------- --------- ------- ----------------------------------------- + 5 jump all 0 0 iifname "eth1" jump NAME_VyOS_MANAGEMENT + 10 jump all 0 0 oifname "eth1" jump NAME_WAN_IN + 15 jump all 0 0 iifname "eth3" jump NAME_WAN_IN + default accept all + + --------------------------------- + IPv4 Firewall "name VyOS_MANAGEMENT" + + Rule Action Protocol Packets Bytes Conditions + ------- -------- ---------- --------- ------- -------------------------------- + 5 accept all 0 0 ct state established accept + 10 drop all 0 0 ct state invalid + 20 accept all 0 0 ip saddr @A_GOOD_GUYS accept + 30 accept all 0 0 ip saddr @N_ENTIRE_RANGE accept + 40 accept all 0 0 ip saddr @A_VyOS_SERVERS accept + 50 accept icmp 0 0 meta l4proto icmp accept + default drop all 0 0 + + --------------------------------- + IPv6 Firewall "forward filter" + + Rule Action Protocol + ------- -------- ---------- + 5 jump all + 10 jump all + 15 jump all + default accept all + + --------------------------------- + IPv6 Firewall "input filter" + + Rule Action Protocol + ------- -------- ---------- + 5 jump all + default accept all + + --------------------------------- + IPv6 Firewall "ipv6_name IPV6-VyOS_MANAGEMENT" + + Rule Action Protocol + ------- -------- ---------- + 5 accept all + 10 drop all + 20 accept all + 30 accept all + 40 accept all + 50 accept ipv6-icmp + default drop all +``` + +```{eval-rst} +.. opcmd:: show firewall summary + + This will show you a summary of rule-sets and groups + + .. code-block:: none + + vyos@vyos:~$ show firewall summary + Ruleset Summary + + IPv6 Ruleset: + + Ruleset Hook Ruleset Priority Description + -------------- -------------------- ------------------------- + forward filter + input filter + ipv6_name IPV6-VyOS_MANAGEMENT + ipv6_name IPV6-WAN_IN PUBLIC_INTERNET + + IPv4 Ruleset: + + Ruleset Hook Ruleset Priority Description + -------------- ------------------ ------------------------- + forward filter + input filter + name VyOS_MANAGEMENT + name WAN_IN PUBLIC_INTERNET + + Firewall Groups + + Name Type References Members + ----------------------- ------------------ ----------------------- ---------------- + PBX address_group WAN_IN-100 198.51.100.77 + SERVERS address_group WAN_IN-110 192.0.2.10 + WAN_IN-111 192.0.2.11 + WAN_IN-112 192.0.2.12 + WAN_IN-120 + WAN_IN-121 + WAN_IN-122 + SUPPORT address_group VyOS_MANAGEMENT-20 192.168.1.2 + WAN_IN-20 + PHONE_VPN_SERVERS address_group WAN_IN-160 10.6.32.2 + PINGABLE_ADRESSES address_group WAN_IN-170 192.168.5.2 + WAN_IN-171 + PBX ipv6_address_group IPV6-WAN_IN-100 2001:db8::1 + SERVERS ipv6_address_group IPV6-WAN_IN-110 2001:db8::2 + IPV6-WAN_IN-111 2001:db8::3 + IPV6-WAN_IN-112 2001:db8::4 + IPV6-WAN_IN-120 + IPV6-WAN_IN-121 + IPV6-WAN_IN-122 + SUPPORT ipv6_address_group IPV6-VyOS_MANAGEMENT-20 2001:db8::5 + IPV6-WAN_IN-20 + +``` + +```{eval-rst} +.. opcmd:: show firewall ipv6 [forward | input | output] filter +``` + +```{eval-rst} +.. opcmd:: show firewall ipv6 ipv6-name <name> + + This command will give an overview of a single rule-set. + + .. code-block:: none + + vyos@vyos:~$ show firewall ipv6 input filter + Ruleset Information + + --------------------------------- + ipv6 Firewall "input filter" + + Rule Action Protocol Packets Bytes Conditions + ------- -------- ---------- --------- ------- ------------------------------------------------------------------------------ + 10 jump all 13 1456 iifname "eth1" jump NAME6_INP-ETH1 + 20 accept ipv6-icmp 10 1112 meta l4proto ipv6-icmp iifname "eth0" prefix "[ipv6-INP-filter-20-A]" accept + default accept all 14 1584 + + vyos@vyos:~$ +``` + +```{eval-rst} +.. opcmd:: show firewall ipv6 [forward | input | output] + filter rule <1-999999> +``` + +```{eval-rst} +.. opcmd:: show firewall ipv6 name <name> rule <1-999999> +``` + +```{eval-rst} +.. opcmd:: show firewall ipv6 ipv6-name <name> rule <1-999999> + + This command will give an overview of a rule in a single rule-set +``` + +```{eval-rst} +.. opcmd:: show firewall group <name> + + Overview of defined groups. You see the type, the members, and where the + group is used. + + .. code-block:: none + + vyos@vyos:~$ show firewall group LAN + Firewall Groups + + Name Type References Members + ------------ ------------------ ----------------------- ---------------- + LAN ipv6_network_group IPV6-VyOS_MANAGEMENT-30 2001:db8::0/64 + IPV6-WAN_IN-30 + LAN network_group VyOS_MANAGEMENT-30 192.168.200.0/24 + WAN_IN-30 + +``` + +```{eval-rst} +.. opcmd:: show firewall statistics + + This will show you a statistic of all rule-sets since the last boot. +``` + +### Show Firewall log + +```{eval-rst} +.. opcmd:: show log firewall +``` + +```{eval-rst} +.. opcmd:: show log firewall ipv6 +``` + +```{eval-rst} +.. opcmd:: show log firewall ipv6 [forward | input | output | name] +``` + +```{eval-rst} +.. opcmd:: show log firewall ipv6 [forward | input | output] filter +``` + +```{eval-rst} +.. opcmd:: show log firewall ipv6 name <name> +``` + +```{eval-rst} +.. opcmd:: show log firewall ipv6 [forward | input | output] filter rule <rule> +``` + +```{eval-rst} +.. opcmd:: show log firewall ipv6 name <name> rule <rule> + + Show the logs of all firewall; show all ipv6 firewall logs; show all logs + for particular hook; show all logs for particular hook and priority; + show all logs for particular custom chain; show logs for specific Rule-Set. +``` + +### Example Partial Config + +```none +firewall { + ipv6 { + input { + filter { + rule 10 { + action jump + inbound-interface { + name eth1 + } + jump-target INP-ETH1 + } + rule 20 { + action accept + inbound-interface { + name eth0 + } + log + protocol ipv6-icmp + } + } + } + name INP-ETH1 { + default-action drop + default-log + rule 10 { + action accept + protocol tcp_udp + } + } + } +} +``` + +### Update geoip database + +```{eval-rst} +.. opcmd:: update geoip + + Command used to update GeoIP database and firewall sets. +``` diff --git a/docs/configuration/firewall/md-zone.md b/docs/configuration/firewall/md-zone.md new file mode 100644 index 00000000..40ffd4b4 --- /dev/null +++ b/docs/configuration/firewall/md-zone.md @@ -0,0 +1,177 @@ +--- +lastproofread: '2023-11-01' +--- + +(firewall-zone)= + +# Zone Based Firewall + +## Overview + +:::{note} +Starting from VyOS 1.4-rolling-202308040557, a new firewall +structure can be found on all vyos instalations. Zone based firewall was +removed in that version, but re introduced in VyOS 1.4 and 1.5. All +versions built after 2023-10-22 has this feature. +Documentation for most of the new firewall CLI can be +found in the [firewall](https://docs.vyos.io/en/latest/configuration/firewall/general.html) +chapter. The legacy firewall is still available for versions before +1.4-rolling-202308040557 and can be found in the +{doc}`legacy firewall configuration </configuration/firewall/general-legacy>` +chapter. +::: + +In this section there's useful information of all firewall configuration that +is needed for zone-based firewall. +Configuration commands covered in this section: + +```{eval-rst} +.. cfgcmd:: set firewall zone ... +``` + +From main structure defined in +{doc}`Firewall Overview</configuration/firewall/index>` +in this section you can find detailed information only for the next part +of the general structure: + +```none +- set firewall + * zone + - custom_zone_name + + ... +``` + +In zone-based policy, interfaces are assigned to zones, and inspection policy +is applied to traffic moving between the zones and acted on according to +firewall rules. A zone is a group of interfaces that have similar functions or +features. It establishes the security borders of a network. A zone defines a +boundary where traffic is subjected to policy restrictions as it crosses to +another region of a network. + +Key Points: + +- A zone must be configured before an interface is assigned to it and an + interface can be assigned to only a single zone. +- All traffic to and from an interface within a zone is permitted. +- All traffic between zones is affected by existing policies +- Traffic cannot flow between zone member interface and any interface that is + not a zone member. +- You need 2 separate firewalls to define traffic: one for each direction. + +:::{note} +In {vytask}`T2199` the syntax of the zone configuration was changed. +The zone configuration moved from `zone-policy zone <name>` to `firewall +zone <name>`. +::: + +## Configuration + +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 rule-sets to interfaces, +they are applied to source zone-destination zone pairs. + +A basic introduction to zone-based firewalls can be found [here](https://support.vyos.io/en/kb/articles/a-primer-to-zone-based-firewall), +and an example at {ref}`examples-zone-policy`. + +### Define a Zone + +To define a zone setup either one with interfaces or a local zone. + +```{eval-rst} +.. cfgcmd:: set firewall zone <name> interface <interface> + + Set interfaces to a zone. A zone can have multiple interfaces. + But an interface can only be a member in one zone. +``` + +```{eval-rst} +.. cfgcmd:: set firewall zone <name> local-zone + + Define the zone as a local zone. A local zone has no interfaces and + will be applied to the router itself. +``` + +```{eval-rst} +.. cfgcmd:: set firewall zone <name> default-action [drop | reject] + + Change the default-action with this setting. +``` + +```{eval-rst} +.. cfgcmd:: set firewall zone <name> description + + Set a meaningful description. +``` + +### Applying a Rule-Set to a Zone + +Before you are able to apply a rule-set to a zone you have to create the zones +first. + +It helps to think of the syntax as: (see below). The 'rule-set' should be +written from the perspective of: *Source Zone*-to->\*Destination Zone\* + +```{eval-rst} +.. cfgcmd:: set firewall zone <Destination Zone> from <Source Zone> + firewall name <rule-set> +``` + +```{eval-rst} +.. cfgcmd:: set firewall zone <name> from <name> firewall name + <rule-set> +``` + +```{eval-rst} +.. cfgcmd:: set firewall zone <name> from <name> firewall ipv6-name + <rule-set> + + You apply a rule-set always to a zone from an other zone, it is recommended + to create one rule-set for each zone pair. + + .. code-block:: none + + set firewall zone DMZ from LAN firewall name LANv4-to-DMZv4 + set firewall zone LAN from DMZ firewall name DMZv4-to-LANv4 +``` + +## Operation-mode + +```{eval-rst} +.. opcmd:: show firewall zone-policy + + This will show you a basic summary of zones configuration. + + .. code-block:: none + + vyos@vyos:~$ show firewall zone-policy + Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 + ------ ------------ ----------- --------------- --------------- + LAN eth1 WAN WAN_to_LAN + eth2 + LOCAL LOCAL LAN LAN_to_LOCAL + WAN WAN_to_LOCAL WAN_to_LOCAL_v6 + WAN eth3 LAN LAN_to_WAN + eth0 LOCAL LOCAL_to_WAN + vyos@vyos:~$ +``` + +```{eval-rst} +.. opcmd:: show firewall zone-policy zone <zone> + + This will show you a basic summary of a particular zone. + + .. code-block:: none + + vyos@vyos:~$ show firewall zone-policy zone WAN + Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 + ------ ------------ ----------- --------------- --------------- + WAN eth3 LAN LAN_to_WAN + eth0 LOCAL LOCAL_to_WAN + vyos@vyos:~$ show firewall zone-policy zone LOCAL + Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 + ------ ------------ ----------- --------------- --------------- + LOCAL LOCAL LAN LAN_to_LOCAL + WAN WAN_to_LOCAL WAN_to_LOCAL_v6 + vyos@vyos:~$ +``` diff --git a/docs/configuration/highavailability/md-index.md b/docs/configuration/highavailability/md-index.md new file mode 100644 index 00000000..6cf6a254 --- /dev/null +++ b/docs/configuration/highavailability/md-index.md @@ -0,0 +1,491 @@ +--- +lastproofread: '2021-06-30' +--- + +(high-availability)= + +# High availability + +VRRP (Virtual Router 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 if they use the same address family, +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 address. + +minimal config + +```none +set high-availability vrrp group Foo vrid 10 +set high-availability vrrp group Foo interface eth0 +set high-availability vrrp group Foo address 192.0.2.1/24 +``` + +You can verify your VRRP group status with the operational mode +`run show vrrp` command: + +```none +vyos@vyos# run show vrrp +Name Interface VRID State Last Transition +---------- ----------- ------ ------- ----------------- +Foo eth1 10 MASTER 2s +``` + +## IPv6 support + +The `address` parameter can be either an IPv4 or IPv6 address, but you can +not mix IPv4 and IPv6 in the same group, and will need to create groups with +different VRIDs specially for IPv4 and IPv6. +If you want to use IPv4 + IPv6 address you can use option `excluded-address` + +## Address + +The `address` can be configured either on the VRRP interface or on not VRRP +interface. + +```none +set high-availability vrrp group Foo address 192.0.2.1/24 +set high-availability vrrp group Foo address 203.0.113.22/24 interface eth2 +set high-availability vrrp group Foo address 198.51.100.33/24 interface eth3 +``` + +## Disabling a VRRP group + +You can disable a VRRP group with `disable` option: + +```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. + +## Exclude address + +Exclude IP addresses from `VRRP packets`. This option `excluded-address` is +used when you want to set IPv4 + IPv6 addresses on the same virtual interface +or when used more than 20 IP addresses. + +```none +set high-availability vrrp group Foo excluded-address '203.0.113.254/24' +set high-availability vrrp group Foo excluded-address '2001:db8:aa::1/64' +set high-availability vrrp group Foo excluded-address '2001:db8:22::1/64' +``` + +## Setting VRRP group priority + +VRRP priority can be set with `priority` option: + +```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. + +```none +edit high-availability vrrp +set sync-group MAIN member VLAN9 +set sync-group MAIN member VLAN20 +``` + +In the following example, when VLAN9 transitions, VLAN20 will also transition: + +```none +vrrp { + group VLAN9 { + interface eth0.9 + address 10.9.1.1/24 + priority 200 + vrid 9 + } + group VLAN20 { + interface eth0.20 + priority 200 + 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 preemption 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: + +```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: + +```none +set high-availability vrrp group Foo preempt-delay 180 +``` + +## Track + +Track option to track non VRRP interface states. VRRP changes status to +`FAULT` if one of the track interfaces in state `down`. + +```none +set high-availability vrrp group Foo track interface eth0 +set high-availability vrrp group Foo track interface eth1 +``` + +Ignore VRRP main interface faults + +```none +set high-availability vrrp group Foo track exclude-vrrp-interface +``` + +## 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. + +```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 +``` + +## rfc3768-compatibility + +RFC 3768 defines a virtual MAC address to each VRRP virtual router. +This virtual router MAC address will be used as the source in all periodic VRRP +messages sent by the active node. When the rfc3768-compatibility option is set, +a new VRRP interface is created, to which the MAC address and the virtual IP +address is automatically assigned. + +```none +set high-availability vrrp group Foo rfc3768-compatibility +``` + +Verification + +```none +$show interfaces ethernet eth0v10 +eth0v10@eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue +state UP group default qlen 1000 +link/ether 00:00:5e:00:01:0a brd ff:ff:ff:ff:ff:ff +inet 172.25.0.247/16 scope global eth0v10 +valid_lft forever preferred_lft forever +``` + +:::{warning} +RFC 3768 creates a virtual interface. If you want to apply +the destination NAT rule to the traffic sent to the virtual MAC, set +the created virtual interface as `inbound-interface`. +::: + +## Global options + +On most scenarios, there's no need to change specific parameters, and using +default configuration is enough. But there are cases were extra configuration +is needed. + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp global-parameters startup_delay <1-600> + + This option specifies a delay in seconds before vrrp instances start up + after keepalived starts. +``` + +## Gratuitous ARP + +These configuration is not mandatory and in most cases there's no +need to configure it. But if necessary, Gratuitous ARP can be configured in +`global-parameters` and/or in `group` section. + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp global-parameters garp interval + <0.000-1000> +``` + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp group <name> garp interval <0.000-1000> + + Set delay between gratuitous ARP messages sent on an interface. + + 0 if not defined. +``` + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp global-parameters garp master-delay <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp group <name> garp master-delay <1-255> + + Set delay for second set of gratuitous ARPs after transition to MASTER. + + 5 if not defined. +``` + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp global-parameters garp master-refresh + <1-600> +``` + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp group <name> garp master-refresh + <1-600> + + Set minimum time interval for refreshing gratuitous ARPs while MASTER. + + 0 if not defined, which means no refreshing. +``` + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp global-parameters garp + master-refresh-repeat <1-600> +``` + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp group <name> garp + master-refresh-repeat <1-600> + + Set number of gratuitous ARP messages to send at a time while MASTER. + + 1 if not defined. +``` + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp global-parameters garp master-repeat + <1-600> +``` + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp group <name> garp master-repeat + <1-600> + + Set number of gratuitous ARP messages to send at a time after transition to + MASTER. + + 5 if not defined. +``` + +## Version + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp global-parameters version 2|3 + + Set the default VRRP version to use. This defaults to 2, but IPv6 instances + will always use version 3. +``` + +## 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: + +```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 +``` + +When the vrrp group is a member of the sync group will use only +the sync group health check script. +This example shows how to configure it for the sync group: + +```none +set high-availability vrrp sync-group Bar health-check script /config/scripts/vrrp-check.sh +set high-availability vrrp sync-group Bar health-check interval 60 +set high-availability vrrp sync-group Bar 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: + +```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" +``` + +To know more about scripting, check the {ref}`command-scripting` section. + +## Virtual-server + +```{include} /_include/need_improvement.txt +``` + +Virtual Server allows to Load-balance traffic destination virtual-address:port +between several real servers. + +### Algorithm + +Load-balancing schedule algorithm: + +- round-robin +- weighted-round-robin +- least-connection +- weighted-least-connection +- source-hashing +- destination-hashing +- locality-based-least-connection + +```none +set high-availability virtual-server 203.0.113.1 algorithm 'least-connection' +``` + +### Forward method + +- NAT +- direct +- tunnel + +```none +set high-availability virtual-server 203.0.113.1 forward-method 'nat' +``` + +### Health-check + +Custom health-check script allows checking real-server availability + +```none +set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 health-check script <path-to-script> +``` + +### Fwmark + +Firewall mark. It possible to loadbalancing traffic based on `fwmark` value + +```none +set high-availability virtual-server 203.0.113.1 fwmark '111' +``` + +### Real server + +Real server IP address and port + +```none +set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 port '80' +``` + +### Example + +Virtual-server can be configured with VRRP virtual address or without VRRP. + +In the next example all traffic destined to `203.0.113.1` and port `8280` +protocol TCP is balanced between 2 real servers `192.0.2.11` and +`192.0.2.12` to port `80` + +Real server is auto-excluded if port check with this server fail. + +```none +set interfaces ethernet eth0 address '203.0.113.11/24' +set interfaces ethernet eth1 address '192.0.2.1/24' +set high-availability vrrp group FOO interface 'eth0' +set high-availability vrrp group FOO no-preempt +set high-availability vrrp group FOO priority '150' +set high-availability vrrp group FOO address '203.0.113.1/24' +set high-availability vrrp group FOO vrid '10' + +set high-availability virtual-server 203.0.113.1 algorithm 'source-hashing' +set high-availability virtual-server 203.0.113.1 delay-loop '10' +set high-availability virtual-server 203.0.113.1 forward-method 'nat' +set high-availability virtual-server 203.0.113.1 persistence-timeout '180' +set high-availability virtual-server 203.0.113.1 port '8280' +set high-availability virtual-server 203.0.113.1 protocol 'tcp' +set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 port '80' +set high-availability virtual-server 203.0.113.1 real-server 192.0.2.12 port '80' +``` + +A firewall mark `fwmark` allows using multiple ports for high-availability +virtual-server. +It uses fwmark value. + +In this example all traffic destined to ports "80, 2222, 8888" protocol TCP +marks to fwmark "111" and balanced between 2 real servers. +Port "0" is required if multiple ports are used. + +```none +set interfaces ethernet eth0 address 'dhcp' +set interfaces ethernet eth0 description 'WAN' +set interfaces ethernet eth1 address '192.0.2.1/24' +set interfaces ethernet eth1 description 'LAN' + +set policy route PR interface 'eth0' +set policy route PR rule 10 destination port '80,2222,8888' +set policy route PR rule 10 protocol 'tcp' +set policy route PR rule 10 set mark '111' + +set high-availability virtual-server vyos fwmark '111' +set high-availability virtual-server vyos protocol 'tcp' +set high-availability virtual-server vyos real-server 192.0.2.11 health-check script '/config/scripts/check-real-server-first.sh' +set high-availability virtual-server vyos real-server 192.0.2.11 port '0' +set high-availability virtual-server vyos real-server 192.0.2.12 health-check script '/config/scripts/check-real-server-second.sh' +set high-availability virtual-server vyos real-server 192.0.2.12 port '0' + +set nat source rule 100 outbound-interface 'eth0' +set nat source rule 100 source address '192.0.2.0/24' +set nat source rule 100 translation address 'masquerade' +``` + +Op-mode check virtual-server status + +```none +vyos@r14:~$ run show virtual-server +IP Virtual Server version 1.2.1 (size=4096) +Prot LocalAddress:Port Scheduler Flags + -> RemoteAddress:Port Forward Weight ActiveConn InActConn +FWM 111 lc persistent 300 + -> 192.0.2.11:0 Masq 1 0 0 + -> 192.0.2.12:0 Masq 1 1 0 +``` diff --git a/docs/configuration/interfaces/md-bonding.md b/docs/configuration/interfaces/md-bonding.md new file mode 100644 index 00000000..ef6988e5 --- /dev/null +++ b/docs/configuration/interfaces/md-bonding.md @@ -0,0 +1,671 @@ +--- +lastproofread: '2021-06-30' +--- + +(bond-interface)= + +# Bond / Link Aggregation + +The bonding interface provides a method for aggregating multiple network +interfaces into a single logical "bonded" interface, or LAG, or ether-channel, +or port-channel. The behavior of the bonded interfaces depends upon the mode; +generally speaking, modes provide either hot standby or load balancing services. +Additionally, link integrity monitoring may be performed. + +## Configuration + +### Common interface configuration + +```{eval-rst} +.. cmdincludemd:: /_include/interface-common-with-dhcp.txt + :var0: bonding + :var1: bond0 +``` + +### Member Interfaces + +```{eval-rst} +.. cfgcmd:: set interfaces bonding <interface> member interface <member> + + Enslave `<member>` interface to bond `<interface>`. +``` + +### Bond options + +```{eval-rst} +.. cfgcmd:: set interfaces bonding <interface> mode <802.3ad | active-backup | + broadcast | round-robin | transmit-load-balance | adaptive-load-balance | + xor-hash> + + Specifies one of the bonding policies. The default is 802.3ad. Possible + values are: + + * ``802.3ad`` - IEEE 802.3ad Dynamic link aggregation. Creates aggregation + groups that share the same speed and duplex settings. Utilizes all slaves + in the active aggregator according to the 802.3ad specification. + + Slave selection for outgoing traffic is done according to the transmit + hash policy, which may be changed from the default simple XOR policy via + the {cfgcmd}`hash-policy` option, documented below. + + .. note:: Not all transmit policies may be 802.3ad compliant, particularly + in regards to the packet misordering requirements of section 43.2.4 + of the 802.3ad standard. + + * ``active-backup`` - Active-backup policy: Only one slave in the bond is + active. A different slave becomes active if, and only if, the active slave + fails. The bond's MAC address is externally visible on only one port + (network adapter) to avoid confusing the switch. + + When a failover occurs in active-backup mode, bonding will issue one or + more gratuitous ARPs on the newly active slave. One gratuitous ARP is + issued for the bonding master interface and each VLAN interfaces + configured above it, provided that the interface has at least one IP + address configured. Gratuitous ARPs issued for VLAN interfaces are tagged + with the appropriate VLAN id. + + This mode provides fault tolerance. The {cfgcmd}`primary` option, + documented below, affects the behavior of this mode. + + * ``broadcast`` - Broadcast policy: transmits everything on all slave + interfaces. + + This mode provides fault tolerance. + + * ``round-robin`` - Round-robin policy: Transmit packets in sequential + order from the first available slave through the last. + + This mode provides load balancing and fault tolerance. + + * ``transmit-load-balance`` - Adaptive transmit load balancing: channel + bonding that does not require any special switch support. + + Incoming traffic is received by the current slave. If the receiving slave + fails, another slave takes over the MAC address of the failed receiving + slave. + + * ``adaptive-load-balance`` - Adaptive load balancing: includes + transmit-load-balance plus receive load balancing for IPV4 traffic, and + does not require any special switch support. The receive load balancing + is achieved by ARP negotiation. The bonding driver intercepts the ARP + Replies sent by the local system on their way out and overwrites the + source hardware address with the unique hardware address of one of the + slaves in the bond such that different peers use different hardware + addresses for the server. + + Receive traffic from connections created by the server is also balanced. + When the local system sends an ARP Request the bonding driver copies and + saves the peer's IP information from the ARP packet. When the ARP Reply + arrives from the peer, its hardware address is retrieved and the bonding + driver initiates an ARP reply to this peer assigning it to one of the + slaves in the bond. A problematic outcome of using ARP negotiation for + balancing is that each time that an ARP request is broadcast it uses the + hardware address of the bond. Hence, peers learn the hardware address + of the bond and the balancing of receive traffic collapses to the current + slave. This is handled by sending updates (ARP Replies) to all the peers + with their individually assigned hardware address such that the traffic + is redistributed. Receive traffic is also redistributed when a new slave + is added to the bond and when an inactive slave is re-activated. The + receive load is distributed sequentially (round robin) among the group + of highest speed slaves in the bond. + + When a link is reconnected or a new slave joins the bond the receive + traffic is redistributed among all active slaves in the bond by initiating + ARP Replies with the selected MAC address to each of the clients. The + updelay parameter (detailed below) must be set to a value equal or greater + than the switch's forwarding delay so that the ARP Replies sent to the + peers will not be blocked by the switch. + + * ``xor-hash`` - XOR policy: Transmit based on the selected transmit + hash policy. The default policy is a simple [(source MAC address XOR'd + with destination MAC address XOR packet type ID) modulo slave count]. + Alternate transmit policies may be selected via the {cfgcmd}`hash-policy` + option, described below. + + This mode provides load balancing and fault tolerance. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces bonding <interface> min-links <0-16> + + Specifies the minimum number of links that must be active before asserting + carrier. It is similar to the Cisco EtherChannel min-links feature. This + allows setting the minimum number of member ports that must be up (link-up + state) before marking the bond device as up (carrier on). This is useful for + situations where higher level services such as clustering want to ensure a + minimum number of low bandwidth links are active before switchover. + + This option only affects 802.3ad mode. + + The default value is 0. This will cause the carrier to be asserted + (for 802.3ad mode) whenever there is an active aggregator, + regardless of the number of available links in that aggregator. + + .. note:: Because an aggregator cannot be active without at least one + available link, setting this option to 0 or to 1 has the exact same + effect. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces bonding <interface> lacp-rate <slow|fast> + + Option specifying the rate in which we'll ask our link partner to transmit + LACPDU packets in 802.3ad mode. + + This option only affects 802.3ad mode. + + * slow: Request partner to transmit LACPDUs every 30 seconds + + * fast: Request partner to transmit LACPDUs every 1 second + + The default value is slow. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces bonding <interface> system-mac <mac address> + + This option allow to specifies the 802.3ad system MAC address.You can set a + random mac-address that can be used for these LACPDU exchanges. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces bonding <interface> hash-policy <policy> + + * **layer2** - Uses XOR of hardware MAC addresses and packet type ID field + to generate the hash. The formula is + + .. code-block:: none + + hash = source MAC XOR destination MAC XOR packet type ID + slave number = hash modulo slave count + + This algorithm will place all traffic to a particular network peer on + the same slave. + + This algorithm is 802.3ad compliant. + + * **layer2+3** - This policy uses a combination of layer2 and layer3 + protocol information to generate the hash. Uses XOR of hardware MAC + addresses and IP addresses to generate the hash. The formula is: + + .. code-block:: none + + hash = source MAC XOR destination MAC XOR packet type ID + hash = hash XOR source IP XOR destination IP + hash = hash XOR (hash RSHIFT 16) + hash = hash XOR (hash RSHIFT 8) + + And then hash is reduced modulo slave count. + + If the protocol is IPv6 then the source and destination addresses are + first hashed using ipv6_addr_hash. + + This algorithm will place all traffic to a particular network peer on the + same slave. For non-IP traffic, the formula is the same as for the layer2 + transmit hash policy. + + This policy is intended to provide a more balanced distribution of traffic + than layer2 alone, especially in environments where a layer3 gateway + device is required to reach most destinations. + + This algorithm is 802.3ad compliant. + + * **layer3+4** - This policy uses upper layer protocol information, when + available, to generate the hash. This allows for traffic to a particular + network peer to span multiple slaves, although a single connection will + not span multiple slaves. + + The formula for unfragmented TCP and UDP packets is + + .. code-block:: none + + hash = source port, destination port (as in the header) + hash = hash XOR source IP XOR destination IP + hash = hash XOR (hash RSHIFT 16) + hash = hash XOR (hash RSHIFT 8) + + And then hash is reduced modulo slave count. + + If the protocol is IPv6 then the source and destination addresses are + first hashed using ipv6_addr_hash. + + For fragmented TCP or UDP packets and all other IPv4 and IPv6 protocol + traffic, the source and destination port information is omitted. For + non-IP traffic, the formula is the same as for the layer2 transmit hash + policy. + + This algorithm is not fully 802.3ad compliant. A single TCP or UDP + conversation containing both fragmented and unfragmented packets will see + packets striped across two interfaces. This may result in out of order + delivery. Most traffic types will not meet these criteria, as TCP rarely + fragments traffic, and most UDP traffic is not involved in extended + conversations. Other implementations of 802.3ad may or may not tolerate + this noncompliance. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces bonding <interface> primary <interface> + + An `<interface>` specifying which slave is the primary device. The specified + device will always be the active slave while it is available. Only when the + primary is off-line will alternate devices be used. This is useful when one + slave is preferred over another, e.g., when one slave has higher throughput + than another. + + The primary option is only valid for active-backup, transmit-load-balance, + and adaptive-load-balance mode. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces bonding <interface> arp-monitor interval <time> + + Specifies the ARP link monitoring `<time>` in seconds. + + The ARP monitor works by periodically checking the slave devices to determine + whether they have sent or received traffic recently (the precise criteria + depends upon the bonding mode, and the state of the slave). Regular traffic + is generated via ARP probes issued for the addresses specified by the + {cfgcmd}`arp-monitor target` option. + + If ARP monitoring is used in an etherchannel compatible mode (modes + round-robin and xor-hash), the switch should be configured in a mode that + evenly distributes packets across all links. If the switch is configured to + distribute the packets in an XOR fashion, all replies from the ARP targets + will be received on the same link which could cause the other team members + to fail. + + A value of 0 disables ARP monitoring. The default value is 0. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces bonding <interface> arp-monitor target <address> + + Specifies the IP addresses to use as ARP monitoring peers when + {cfgcmd}`arp-monitor interval` option is > 0. These are the targets of the + ARP request sent to determine the health of the link to the targets. + + Multiple target IP addresses can be specified. At least one IP address must + be given for ARP monitoring to function. + + The maximum number of targets that can be specified is 16. The default value + is no IP address. +``` + +### VLAN + +```{eval-rst} +.. cmdincludemd:: /_include/interface-vlan-8021q.txt + :var0: bonding + :var1: bond0 +``` + +### Port Mirror (SPAN) + +```{eval-rst} +.. cmdincludemd:: ../../_include/interface-mirror.txt + :var0: bondinging + :var1: bond1 + :var2: eth3 +``` + +#### EVPN Multihoming + +All-Active Multihoming is used for redundancy and load sharing. Servers are +attached to two or more PEs and the links are bonded (link-aggregation). +This group of server links is referred to as an {abbr}`ES (Ethernet Segment)`. + +An Ethernet Segment can be configured by specifying a system-MAC and a local +discriminator or a complete ESINAME against the bond interface on the PE. + +```{eval-rst} +.. cfgcmd:: set interfaces bonding <interface> evpn es-id <<1-16777215|10-byte ID> +``` + +```{eval-rst} +.. cfgcmd:: set interfaces bonding <interface> evpn es-sys-mac <xx:xx:xx:xx:xx:xx> + + The sys-mac and local discriminator are used for generating a 10-byte, Type-3 + Ethernet Segment ID. ESINAME is a 10-byte, Type-0 Ethernet Segment ID - + "00:AA:BB:CC:DD:EE:FF:GG:HH:II". + + Type-1 (EAD-per-ES and EAD-per-EVI) routes are used to advertise the locally + attached ESs and to learn off remote ESs in the network. Local Type-2/MAC-IP + routes are also advertised with a destination ESI allowing for MAC-IP syncing + between Ethernet Segment peers. Reference: RFC 7432, RFC 8365 + + EVPN-MH is intended as a replacement for MLAG or Anycast VTEPs. In multihoming + each PE has an unique VTEP address which requires the introduction of a new + dataplane construct, MAC-ECMP. Here a MAC/FDB entry can point to a list of + remote PEs/VTEPs. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces bonding <interface> evpn es-df-pref <1-65535> + + Type-4 (ESR) routes are used for Designated Forwarder (DF) election. + DFs forward BUM traffic received via the overlay network. This + implementation uses a preference based DF election specified by + draft-ietf-bess-evpn-pref-df. + + The DF preference is configurable per-ES. + + BUM traffic is rxed via the overlay by all PEs attached to a server but + only the DF can forward the de-capsulated traffic to the access port. + To accommodate that non-DF filters are installed in the dataplane to drop + the traffic. + + Similarly traffic received from ES peers via the overlay cannot be forwarded + to the server. This is split-horizon-filtering with local bias. +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-evpn-uplink.txt + :var0: bonding + :var1: bond0 +``` + +## Example + +The following configuration on VyOS applies to all following 3rd party vendors. +It creates a bond with two links and VLAN 10, 100 on the bonded interfaces with +a per VIF IPv4 address. + +```none +# Create bonding interface bond0 with 802.3ad LACP +set interfaces bonding bond0 hash-policy 'layer2' +set interfaces bonding bond0 mode '802.3ad' + +# Add the required vlans and IPv4 addresses on them +set interfaces bonding bond0 vif 10 address 192.168.0.1/24 +set interfaces bonding bond0 vif 100 address 10.10.10.1/24 + +# Add the member interfaces to the bonding interface +set interfaces bonding bond0 member interface eth1 +set interfaces bonding bond0 member interface eth2 +``` + +:::{note} +If you happen to run this in a virtual environment like by EVE-NG +you need to ensure your VyOS NIC is set to use the e1000 driver. Using the +default `virtio-net-pci` or the `vmxnet3` driver will not work. ICMP +messages will not be properly processed. They are visible on the virtual wire +but will not make it fully up the networking stack. + +You can check your NIC driver by issuing {opcmd}`show interfaces ethernet +eth0 physical | grep -i driver` +::: + +### Cisco Catalyst + +Assign member interfaces to PortChannel + +```none +interface GigabitEthernet1/0/23 + description VyOS eth1 + channel-group 1 mode active +! +interface GigabitEthernet1/0/24 + description VyOS eth2 + channel-group 1 mode active +! +``` + +A new interface becomes present `Port-channel1`, all configuration like +allowed VLAN interfaces, STP will happen here. + +```none +interface Port-channel1 + description LACP Channel for VyOS + switchport trunk encapsulation dot1q + switchport trunk allowed vlan 10,100 + switchport mode trunk + spanning-tree portfast trunk +! +``` + +### Juniper EX Switch + +For a headstart you can use the below example on how to build a bond with two +interfaces from VyOS to a Juniper EX Switch system. + +```none +# Create aggregated ethernet device with 802.3ad LACP and port speeds of 10gbit/s +set interfaces ae0 aggregated-ether-options link-speed 10g +set interfaces ae0 aggregated-ether-options lacp active + +# Create layer 2 on the aggregated ethernet device with trunking for our vlans +set interfaces ae0 unit 0 family ethernet-switching port-mode trunk + +# Add the required vlans to the device +set interfaces ae0 unit 0 family ethernet-switching vlan members 10 +set interfaces ae0 unit 0 family ethernet-switching vlan members 100 + +# Add the two interfaces to the aggregated ethernet device, in this setup both +# ports are on the same switch (switch 0, module 1, port 0 and 1) +set interfaces xe-0/1/0 ether-options 802.3ad ae0 +set interfaces xe-0/1/1 ether-options 802.3ad ae0 + +# But this can also be done with multiple switches in a stack, a virtual +# chassis on Juniper (switch 0 and switch 1, module 1, port 0 on both switches) +set interfaces xe-0/1/0 ether-options 802.3ad ae0 +set interfaces xe-1/1/0 ether-options 802.3ad ae0 +``` + +### Aruba/HP + +For a headstart you can use the below example on how to build a +bond,port-channel with two interfaces from VyOS to a Aruba/HP 2510G switch. + +```none +# Create trunk with 2 member interfaces (interface 1 and 2) and LACP +trunk 1-2 Trk1 LACP + +# Add the required vlans to the trunk +vlan 10 tagged Trk1 +vlan 100 tagged Trk1 +``` + +### Arista EOS + +When utilizing VyOS in an environment with Arista gear you can use this blue +print as an initial setup to get an LACP bond / port-channel operational between +those two devices. + +Lets assume the following topology: + +:::{figure} /_static/images/vyos_arista_bond_lacp.png +:alt: VyOS Arista EOS setup +::: + +**R1** + +> ```none +> interfaces { +> bonding bond10 { +> hash-policy layer3+4 +> member { +> interface eth1 +> interface eth2 +> } +> mode 802.3ad +> vif 100 { +> address 192.0.2.1/30 +> address 2001:db8::1/64 +> } +> } +> ``` + +**R2** + +> ```none +> interfaces { +> bonding bond10 { +> hash-policy layer3+4 +> member { +> interface eth1 +> interface eth2 +> } +> mode 802.3ad +> vif 100 { +> address 192.0.2.2/30 +> address 2001:db8::2/64 +> } +> } +> ``` + +**SW1** + +> ```none +> ! +> vlan 100 +> name FOO +> ! +> interface Port-Channel10 +> switchport trunk allowed vlan 100 +> switchport mode trunk +> spanning-tree portfast +> ! +> interface Port-Channel20 +> switchport mode trunk +> no spanning-tree portfast auto +> spanning-tree portfast network +> ! +> interface Ethernet1 +> channel-group 10 mode active +> ! +> interface Ethernet2 +> channel-group 10 mode active +> ! +> interface Ethernet3 +> channel-group 20 mode active +> ! +> interface Ethernet4 +> channel-group 20 mode active +> ! +> ``` + +**SW2** + +> ```none +> ! +> vlan 100 +> name FOO +> ! +> interface Port-Channel10 +> switchport trunk allowed vlan 100 +> switchport mode trunk +> spanning-tree portfast +> ! +> interface Port-Channel20 +> switchport mode trunk +> no spanning-tree portfast auto +> spanning-tree portfast network +> ! +> interface Ethernet1 +> channel-group 10 mode active +> ! +> interface Ethernet2 +> channel-group 10 mode active +> ! +> interface Ethernet3 +> channel-group 20 mode active +> ! +> interface Ethernet4 +> channel-group 20 mode active +> ! +> ``` + +:::{note} +When using EVE-NG to lab this environment ensure you are using e1000 +as the desired driver for your VyOS network interfaces. When using the +regular virtio network driver no LACP PDUs will be sent by VyOS thus the +port-channel will never become active! +::: + +## Operation + +```{eval-rst} +.. opcmd:: show interfaces bonding + + Show brief interface information. + + .. code-block:: none + + vyos@vyos:~$ show 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 + +``` + +```{eval-rst} +.. opcmd:: show interfaces bonding <interface> + + Show detailed information on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces bonding bond5 + bond5: <NO-CARRIER,BROADCAST,MULTICAST,MASTER,UP> mtu 1500 qdisc noqueue state DOWN group default qlen 1000 + link/ether 00:50:56:bf:ef:aa brd ff:ff:ff:ff:ff:ff + inet6 fe80::e862:26ff:fe72:2dac/64 scope link tentative + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 0 0 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 0 0 0 0 0 0 +``` + +```{eval-rst} +.. opcmd:: show interfaces bonding <interface> detail + + Show detailed information about the underlaying physical links on given + bond `<interface>`. + + .. code-block:: none + + vyos@vyos:~$ show interfaces bonding bond5 detail + Ethernet Channel Bonding Driver: v3.7.1 (April 27, 2011) + + Bonding Mode: IEEE 802.3ad Dynamic link aggregation + Transmit Hash Policy: layer2 (0) + MII Status: down + MII Polling Interval (ms): 100 + Up Delay (ms): 0 + Down Delay (ms): 0 + + 802.3ad info + LACP rate: slow + Min links: 0 + Aggregator selection policy (ad_select): stable + + Slave Interface: eth1 + MII Status: down + Speed: Unknown + Duplex: Unknown + Link Failure Count: 0 + Permanent HW addr: 00:50:56:bf:ef:aa + Slave queue ID: 0 + Aggregator ID: 1 + Actor Churn State: churned + Partner Churn State: churned + Actor Churned Count: 1 + Partner Churned Count: 1 + + Slave Interface: eth2 + MII Status: down + Speed: Unknown + Duplex: Unknown + Link Failure Count: 0 + Permanent HW addr: 00:50:56:bf:19:26 + Slave queue ID: 0 + Aggregator ID: 2 + Actor Churn State: churned + Partner Churn State: churned + Actor Churned Count: 1 + Partner Churned Count: 1 +``` diff --git a/docs/configuration/interfaces/md-bridge.md b/docs/configuration/interfaces/md-bridge.md new file mode 100644 index 00000000..409412c1 --- /dev/null +++ b/docs/configuration/interfaces/md-bridge.md @@ -0,0 +1,367 @@ +--- +lastproofread: '2021-06-30' +--- + +(bridge-interface)= + +# Bridge + +A Bridge is a way to connect two Ethernet segments together in a +protocol independent way. Packets are forwarded based on Ethernet +address, rather than IP address (like a router). Since forwarding is +done at Layer 2, all protocols can go transparently through a bridge. +The Linux bridge code implements a subset of the ANSI/IEEE 802.1d +standard. + +:::{note} +Spanning Tree Protocol is not enabled by default in VyOS. +{ref}`stp` can be easily enabled if needed. +::: + +## Configuration + +### Common interface configuration + +```{eval-rst} +.. cmdincludemd:: /_include/interface-common-with-dhcp.txt + :var0: bridge + :var1: br0 +``` + +### Member Interfaces + +```{eval-rst} +.. cfgcmd:: set interfaces bridge <interface> member interface <member> + + Assign `<member>` interface to bridge `<interface>`. A completion + helper will help you with all allowed interfaces which can be + bridged. This includes {ref}`ethernet-interface`, + {ref}`bond-interface`, {ref}`l2tpv3-interface`, {ref}`openvpn`, + {ref}`vxlan-interface`, {ref}`wireless-interface`, + {ref}`tunnel-interface` and {ref}`geneve-interface`. + +``` + +```{eval-rst} +.. cfgcmd:: set interfaces bridge <interface> member interface <member> + priority <priority> + + Configure individual bridge port `<priority>`. + + Each bridge has a relative priority and cost. Each interface is + associated with a port (number) in the STP code. Each has a priority + and a cost, that is used to decide which is the shortest path to + forward a packet. The lowest cost path is always used unless the + other path is down. If you have multiple bridges and interfaces then + you may need to adjust the priorities to achieve optimum + performance. + +``` + +```{eval-rst} +.. cfgcmd:: set interfaces bridge <interface> member interface <member> + cost <cost> + + Path `<cost>` value for Spanning Tree Protocol. Each interface in a + bridge could have a different speed and this value is used when + deciding which link to use. Faster interfaces should have lower + costs. +``` + +### Bridge Options + +```{eval-rst} +.. cfgcmd:: set interfaces bridge <interface> aging <time> + + MAC address aging `<time`> in seconds (default: 300). +``` + +```{eval-rst} +.. cfgcmd:: set interfaces bridge <interface> max-age <time> + + Bridge maximum aging `<time>` in seconds (default: 20). + + If an another bridge in the spanning tree does not send out a hello + packet for a long period of time, it is assumed to be dead. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces bridge <interface> igmp querier + + Enable IGMP and MLD querier. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces bridge <interface> igmp snooping + + Enable IGMP and MLD snooping. +``` + +(stp)= + +#### STP Parameter + +{abbr}`STP (Spanning Tree Protocol)` is a network protocol that builds a +loop-free logical topology for Ethernet networks. The basic function of +STP is to prevent bridge loops and the broadcast radiation that results +from them. Spanning tree also allows a network design to include backup +links providing fault tolerance if an active link fails. + +```{eval-rst} +.. cfgcmd:: set interfaces bridge <interface> stp + + Enable spanning tree protocol. STP is disabled by default. + +``` + +```{eval-rst} +.. cfgcmd:: set interfaces bridge <interface> forwarding-delay <delay> + + Spanning Tree Protocol forwarding `<delay>` in seconds (default: 15). + + The forwarding delay time is the time spent in each of the listening and + learning states before the Forwarding state is entered. This delay is + so that when a new bridge comes onto a busy network it looks at some + traffic before participating. + +``` + +```{eval-rst} +.. cfgcmd:: set interfaces bridge <interface> hello-time <interval> + + Spanning Tree Protocol hello advertisement `<interval>` in seconds + (default: 2). + + Periodically, a hello packet is sent out by the Root Bridge and the + Designated Bridges. Hello packets are used to communicate information + about the topology throughout the entire Bridged Local Area Network. +``` + +### VLAN + +#### Enable VLAN-Aware Bridge + +```{eval-rst} +.. cfgcmd:: set interfaces bridge <interface> enable-vlan + + To activate the VLAN aware bridge, you must activate this setting to use VLAN + settings for the bridge +``` + +```{eval-rst} +.. cfgcmd:: set interfaces bridge <interface> protocol <802.1ad|802.1q> + + Define used ethertype of bridge interface. + + Ethertype ``0x8100`` is used for ``802.1q`` and ethertype ``0x88a8`` is used + for ``802.1ad``. + + The default is ``802.1q``. +``` + +#### VLAN Options + +:::{note} +It is not valid to use the `vif 1` option for VLAN aware bridges +because VLAN aware bridges assume that all unlabeled packets belong to +the default VLAN 1 member and that the VLAN ID of the bridge's parent +interface is always 1 +::: + +```{eval-rst} +.. cmdincludemd:: /_include/interface-vlan-8021q.txt + :var0: bridge + :var1: br0 +``` + +```{eval-rst} +.. cfgcmd:: set interfaces bridge <interface> member interface <member> + native-vlan <vlan-id> + + Set the native VLAN ID flag of the interface. When a data packet without a + VLAN tag enters the port, the data packet will be forced to add a tag of a + specific vlan id. When the vlan id flag flows out, the tag of the vlan id + will be stripped + + Example: Set `eth0` member port to be native VLAN 2 + + .. code-block:: none + + set interfaces bridge br1 member interface eth0 native-vlan 2 +``` + +```{eval-rst} +.. cfgcmd:: set interfaces bridge <interface> member interface <member> + allowed-vlan <vlan-id> + + Allows specific VLAN IDs to pass through the bridge member interface. This + can either be an individual VLAN id or a range of VLAN ids delimited by a + hyphen. + + Example: Set `eth0` member port to be allowed VLAN 4 + + .. code-block:: none + + set interfaces bridge br1 member interface eth0 allowed-vlan 4 + + Example: Set `eth0` member port to be allowed VLAN 6-8 + + .. code-block:: none + + set interfaces bridge br1 member interface eth0 allowed-vlan 6-8 +``` + +### Port Mirror (SPAN) + +```{eval-rst} +.. cmdincludemd:: ../../_include/interface-mirror.txt + :var0: bridge + :var1: br1 + :var2: eth3 +``` + +## Examples + +### Create a basic bridge + +Creating a bridge interface is very simple. In this example, we will +have: + +- A bridge named `br100` +- Member interfaces `eth1` and VLAN 10 on interface `eth2` +- Enable STP +- Bridge answers on IP address 192.0.2.1/24 and 2001:db8::ffff/64 + +```none +set interfaces bridge br100 address 192.0.2.1/24 +set interfaces bridge br100 address 2001:db8::ffff/64 +set interfaces bridge br100 member interface eth1 +set interfaces bridge br100 member interface eth2.10 +set interfaces bridge br100 stp +``` + +This results in the active configuration: + +```none +vyos@vyos# show interfaces bridge br100 + address 192.0.2.1/24 + address 2001:db8::ffff/64 + member { + interface eth1 { + } + interface eth2.10 { + } + } + stp +``` + +### Using VLAN aware Bridge + +An example of creating a VLAN-aware bridge is as follows: + +- A bridge named `br100` +- The member interface `eth1` is a trunk that allows VLAN 10 to pass +- VLAN 10 on member interface `eth2` (ACCESS mode) +- Enable STP +- Bridge answers on IP address 192.0.2.1/24 and 2001:db8::ffff/64 + +```none +set interfaces bridge br100 enable-vlan +set interfaces bridge br100 member interface eth1 allowed-vlan 10 +set interfaces bridge br100 member interface eth2 native-vlan 10 +set interfaces bridge br100 vif 10 address 192.0.2.1/24 +set interfaces bridge br100 vif 10 address 2001:db8::ffff/64 +set interfaces bridge br100 stp +``` + +This results in the active configuration: + +```none +vyos@vyos# show interfaces bridge br100 + enable-vlan + member { + interface eth1 { + allowed-vlan 10 + } + interface eth2 { + native-vlan 10 + } + } + stp + vif 10 { + address 192.0.2.1/24 + address 2001:db8::ffff/64 + } +``` + +### Using the operation mode command to view Bridge Information + +```{eval-rst} +.. opcmd:: show bridge + + The `show bridge` operational command can be used to display + configured bridges: + + .. code-block:: none + + vyos@vyos:~$ show bridge + 3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br0 state forwarding + priority 32 cost 100 + 4: eth2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br0 state forwarding + priority 32 cost 100 +``` + +```{eval-rst} +.. opcmd:: show bridge <name> fdb + + Show bridge `<name>` fdb displays the current forwarding table: + + .. code-block:: none + + vyos@vyos:~$ show bridge br0 fdb + 50:00:00:08:00:01 dev eth1 vlan 20 master br0 permanent + 50:00:00:08:00:01 dev eth1 vlan 10 master br0 permanent + 50:00:00:08:00:01 dev eth1 master br0 permanent + 33:33:00:00:00:01 dev eth1 self permanent + 33:33:00:00:00:02 dev eth1 self permanent + 01:00:5e:00:00:01 dev eth1 self permanent + 50:00:00:08:00:02 dev eth2 vlan 20 master br0 permanent + 50:00:00:08:00:02 dev eth2 vlan 10 master br0 permanent + 50:00:00:08:00:02 dev eth2 master br0 permanent + 33:33:00:00:00:01 dev eth2 self permanent + 33:33:00:00:00:02 dev eth2 self permanent + 01:00:5e:00:00:01 dev eth2 self permanent + 33:33:00:00:00:01 dev br0 self permanent + 33:33:00:00:00:02 dev br0 self permanent + 33:33:ff:08:00:01 dev br0 self permanent + 01:00:5e:00:00:6a dev br0 self permanent + 33:33:00:00:00:6a dev br0 self permanent + 01:00:5e:00:00:01 dev br0 self permanent + 33:33:ff:00:00:00 dev br0 self permanent +``` + +```{eval-rst} +.. opcmd:: show bridge <name> mdb + + Show bridge `<name>` mdb displays the current multicast group membership + table.The table is populated by IGMP and MLD snooping in the bridge driver + automatically. + + .. code-block:: none + + vyos@vyos:~$ show bridge br0 mdb + dev br0 port br0 grp ff02::1:ff00:0 temp vid 1 + dev br0 port br0 grp ff02::2 temp vid 1 + dev br0 port br0 grp ff02::1:ff08:1 temp vid 1 + dev br0 port br0 grp ff02::6a temp vid 1 +``` + +% opcmd: show bridge <name> macs +% +% Show bridge Media Access Control (MAC) address table +% +% .. code-block:: none +% +% vyos@vyos:~$ show bridge br100 macs +% port no mac addr is local? ageing timer +% 1 00:53:29:44:3b:19 yes 0.00 diff --git a/docs/configuration/interfaces/md-dummy.md b/docs/configuration/interfaces/md-dummy.md new file mode 100644 index 00000000..246c3e7d --- /dev/null +++ b/docs/configuration/interfaces/md-dummy.md @@ -0,0 +1,94 @@ +--- +lastproofread: '2023-01-20' +--- + +(dummy-interface)= + +# Dummy + +The dummy interface is really a little exotic, but rather useful nevertheless. +Dummy interfaces are much like the {ref}`loopback-interface` interface, except +you can have as many as you want. + +:::{note} +Dummy interfaces can be used as interfaces that always stay up (in +the same fashion to loopbacks in Cisco IOS), or for testing purposes. +::: + +:::{hint} +On systems with multiple redundant uplinks and routes, +it's a good idea to use a dedicated address for management and dynamic routing protocols. +However, assigning that address to a physical link is risky: +if that link goes down, that address will become inaccessible. +A common solution is to assign the management address to a loopback or a dummy interface +and advertise that address via all physical links, so that it's reachable +through any of them. Since in Linux-based systems, there can be only one loopback interface, +it's better to use a dummy interface for that purpose, since they can be added, removed, +and taken up and down independently. +::: + +## Configuration + +### Common interface configuration + +```{eval-rst} +.. cmdincludemd:: /_include/interface-address.txt + :var0: dummy + :var1: dum0 +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-description.txt + :var0: dummy + :var1: dum0 +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-disable.txt + :var0: dummy + :var1: dum0 +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-vrf.txt + :var0: dummy + :var1: dum0 +``` + +## Operation + +```{eval-rst} +.. opcmd:: show interfaces dummy + + Show brief interface information. + + .. code-block:: none + + vyos@vyos:~$ show interfaces dummy + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + dum0 172.18.254.201/32 u/u +``` + +```{eval-rst} +.. opcmd:: show interfaces dummy <interface> + + Show detailed information on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces dummy dum0 + dum0: <BROADCAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc noqueue state UNKNOWN group default qlen 1000 + link/ether 26:7c:8e:bc:fc:f5 brd ff:ff:ff:ff:ff:ff + inet 172.18.254.201/32 scope global dum0 + valid_lft forever preferred_lft forever + inet6 fe80::247c:8eff:febc:fcf5/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 0 0 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 1369707 4267 0 0 0 0 + +``` diff --git a/docs/configuration/interfaces/md-ethernet.md b/docs/configuration/interfaces/md-ethernet.md new file mode 100644 index 00000000..66d388ea --- /dev/null +++ b/docs/configuration/interfaces/md-ethernet.md @@ -0,0 +1,324 @@ +--- +lastproofread: '2023-01-20' +--- + +(ethernet-interface)= + +# Ethernet + +This will be the most widely used interface on a router carrying traffic to the +real world. + +## Configuration + +### Common interface configuration + +```{eval-rst} +.. cmdincludemd:: /_include/interface-common-with-dhcp.txt + :var0: ethernet + :var1: eth0 +``` + +### Ethernet options + +```{eval-rst} +.. cfgcmd:: set interfaces ethernet <interface> duplex <auto | full | half> + + Configure physical interface duplex setting. + + * auto - interface duplex setting is auto-negotiated + * full - always use full-duplex + * half - always use half-duplex + + VyOS default will be `auto`. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces ethernet <interface> speed <auto | 10 | 100 | 1000 | + 2500 | 5000 | 10000 | 25000 | 40000 | 50000 | 100000> + + Configure physical interface speed setting. + + * auto - interface speed is auto-negotiated + * 10 - 10 MBit/s + * 100 - 100 MBit/s + * 1000 - 1 GBit/s + * 2500 - 2.5 GBit/s + * 5000 - 5 GBit/s + * 10000 - 10 GBit/s + * 25000 - 25 GBit/s + * 40000 - 40 GBit/s + * 50000 - 50 GBit/s + * 100000 - 100 GBit/s + + VyOS default will be `auto`. +``` + +```{eval-rst} +.. cfgcmd:: set interface ethernet <interface> ring-buffer rx <value> +``` + +```{eval-rst} +.. cfgcmd:: set interface ethernet <interface> ring-buffer tx <value> + + Configures the ring buffer size of the interface. + + The supported values for a specific interface can be obtained + with: `ethtool -g <interface>` + +``` + +#### Offloading + +```{eval-rst} +.. cfgcmd:: set interfaces ethernet <interface> offload <gro | gso | lro | rps | + sg | tso> + + Enable different types of hardware offloading on the given NIC. + + {abbr}`LRO (Large Receive Offload)` is a technique designed to boost the + efficiency of how your computer's network interface card (NIC) processes + incoming network traffic. Typically, network data arrives in smaller chunks + called packets. Processing each packet individually consumes CPU (central + processing unit) resources. Lots of small packets can lead to a performance + bottleneck. Instead of handing the CPU each packet as it comes in, LRO + instructs the NIC to combine multiple incoming packets into a single, larger + packet. This larger packet is then passed to the CPU for processing. + + .. note:: Under some circumstances, LRO is known to modify the packet headers + of forwarded traffic, which breaks the end-to-end principle of computer + networking. LRO is also only able to offload TCP segments encapsulated in + IPv4 packets. Due to these limitations, it is recommended to use GRO + (Generic Receive Offload) where possible. More information on the + limitations of LRO can be found here: https://lwn.net/Articles/358910/ + + {abbr}`GSO (Generic Segmentation Offload)` is a pure software offload that is + meant to deal with cases where device drivers cannot perform the offloads + described above. What occurs in GSO is that a given skbuff will have its data + broken out over multiple skbuffs that have been resized to match the MSS + provided via skb_shinfo()->gso_size. + + Before enabling any hardware segmentation offload a corresponding software + offload is required in GSO. Otherwise it becomes possible for a frame to be + re-routed between devices and end up being unable to be transmitted. + + {abbr}`GRO (Generic receive offload)` is the complement to GSO. Ideally any + frame assembled by GRO should be segmented to create an identical sequence of + frames using GSO, and any sequence of frames segmented by GSO should be able + to be reassembled back to the original by GRO. The only exception to this is + IPv4 ID in the case that the DF bit is set for a given IP header. If the + value of the IPv4 ID is not sequentially incrementing it will be altered so + that it is when a frame assembled via GRO is segmented via GSO. + + {abbr}`RPS (Receive Packet Steering)` is logically a software implementation + of {abbr}`RSS (Receive Side Scaling)`. Being in software, it is necessarily + called later in the datapath. Whereas RSS selects the queue and hence CPU that + will run the hardware interrupt handler, RPS selects the CPU to perform + protocol processing above the interrupt handler. This is accomplished by + placing the packet on the desired CPU's backlog queue and waking up the CPU + for processing. RPS has some advantages over RSS: + + - it can be used with any NIC + - software filters can easily be added to hash over new protocols + - it does not increase hardware device interrupt rate, although it does + introduce inter-processor interrupts (IPIs) + + .. note:: In order to use TSO/LRO with VMXNET3 adapters, the SG offloading + option must also be enabled. +``` + +#### Authentication (EAPoL) + +```{eval-rst} +.. cmdincludemd:: /_include/interface-eapol.txt + :var0: ethernet + :var1: eth0 +``` + +#### EVPN Multihoming + +Uplink/Core tracking. + +```{eval-rst} +.. cmdincludemd:: /_include/interface-evpn-uplink.txt + :var0: ethernet + :var1: eth0 +``` + +### VLAN + +#### Regular VLANs (802.1q) + +```{eval-rst} +.. cmdincludemd:: /_include/interface-vlan-8021q.txt + :var0: ethernet + :var1: eth0 +``` + +#### QinQ (802.1ad) + +```{eval-rst} +.. cmdincludemd:: /_include/interface-vlan-8021ad.txt + :var0: ethernet + :var1: eth0 +``` + +### Port Mirror (SPAN) + +```{eval-rst} +.. cmdincludemd:: ../../_include/interface-mirror.txt + :var0: ethernet + :var1: eth1 + :var2: eth3 +``` + +## Operation + +```{eval-rst} +.. opcmd:: show interfaces ethernet + + Show brief interface information. + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 172.18.201.10/24 u/u LAN + eth1 172.18.202.11/24 u/u WAN + eth2 - u/D +``` + +```{eval-rst} +.. opcmd:: show interfaces ethernet <interface> + + Show detailed information on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 + eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 + link/ether 00:50:44:00:f5:c9 brd ff:ff:ff:ff:ff:ff + inet6 fe80::250:44ff:fe00:f5c9/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 56735451 179841 0 0 0 142380 + TX: bytes packets errors dropped carrier collisions + 5601460 62595 0 0 0 0 +``` + + +```{eval-rst} +.. opcmd:: show interfaces ethernet <interface> physical + + Show information about physical `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 physical + Settings for eth0: + Supported ports: [ TP ] + Supported link modes: 1000baseT/Full + 10000baseT/Full + Supported pause frame use: No + Supports auto-negotiation: No + Supported FEC modes: Not reported + Advertised link modes: Not reported + Advertised pause frame use: No + Advertised auto-negotiation: No + Advertised FEC modes: Not reported + Speed: 10000Mb/s + Duplex: Full + Port: Twisted Pair + PHYAD: 0 + Transceiver: internal + Auto-negotiation: off + MDI-X: Unknown + Supports Wake-on: uag + Wake-on: d + Link detected: yes + driver: vmxnet3 + version: 1.4.16.0-k-NAPI + firmware-version: + expansion-rom-version: + bus-info: 0000:0b:00.0 + supports-statistics: yes + supports-test: no + supports-eeprom-access: no + supports-register-dump: yes + supports-priv-flags: no +``` + + +```{eval-rst} +.. opcmd:: show interfaces ethernet <interface> physical offload + + Show available offloading functions on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 physical offload + rx-checksumming on + tx-checksumming on + tx-checksum-ip-generic on + scatter-gather off + tx-scatter-gather off + tcp-segmentation-offload off + tx-tcp-segmentation off + tx-tcp-mangleid-segmentation off + tx-tcp6-segmentation off + udp-fragmentation-offload off + generic-segmentation-offload off + generic-receive-offload off + large-receive-offload off + rx-vlan-offload on + tx-vlan-offload on + ntuple-filters off + receive-hashing on + tx-gre-segmentation on + tx-gre-csum-segmentation on + tx-udp_tnl-segmentation on + tx-udp_tnl-csum-segmentation on + tx-gso-partial on + tx-nocache-copy off + rx-all off +``` + +```{eval-rst} +.. opcmd:: show interfaces ethernet <interface> transceiver + + Show transceiver information from plugin modules, e.g SFP+, QSFP + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth5 transceiver + Identifier : 0x03 (SFP) + Extended identifier : 0x04 (GBIC/SFP defined by 2-wire interface ID) + Connector : 0x07 (LC) + Transceiver codes : 0x00 0x00 0x00 0x01 0x00 0x00 0x00 0x00 0x00 + Transceiver type : Ethernet: 1000BASE-SX + Encoding : 0x01 (8B/10B) + BR, Nominal : 1300MBd + Rate identifier : 0x00 (unspecified) + Length (SMF,km) : 0km + Length (SMF) : 0m + Length (50um) : 550m + Length (62.5um) : 270m + Length (Copper) : 0m + Length (OM3) : 0m + Laser wavelength : 850nm + Vendor name : CISCO-FINISAR + Vendor OUI : 00:90:65 + Vendor PN : FTRJ-8519-7D-CS4 + Vendor rev : A + Option values : 0x00 0x1a + Option : RX_LOS implemented + Option : TX_FAULT implemented + Option : TX_DISABLE implemented + BR margin, max : 0% + BR margin, min : 0% + Vendor SN : FNS092xxxxx + Date code : 0506xx +``` diff --git a/docs/configuration/interfaces/md-geneve.md b/docs/configuration/interfaces/md-geneve.md new file mode 100644 index 00000000..5c561fb8 --- /dev/null +++ b/docs/configuration/interfaces/md-geneve.md @@ -0,0 +1,101 @@ +--- +lastproofread: '2023-01-20' +--- + +(geneve-interface)= + +# GENEVE + +{abbr}`GENEVE (Generic Network Virtualization Encapsulation)` supports all of +the capabilities of {abbr}`VXLAN (Virtual Extensible LAN)`, {abbr}`NVGRE +(Network Virtualization using Generic Routing Encapsulation)`, and {abbr}`STT +(Stateless Transport Tunneling)` and was designed to overcome their perceived +limitations. Many believe GENEVE could eventually replace these earlier formats +entirely. + +GENEVE is designed to support network virtualization use cases, where tunnels +are typically established to act as a backplane between the virtual switches +residing in hypervisors, physical switches, or middleboxes or other appliances. +An arbitrary IP network can be used as an underlay although Clos networks - A +technique for composing network fabrics larger than a single switch while +maintaining non-blocking bandwidth across connection points. ECMP is used to +divide traffic across the multiple links and switches that constitute the +fabric. Sometimes termed "leaf and spine" or "fat tree" topologies. + +Geneve Header: + +```none ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +|Ver| Opt Len |O|C| Rsvd. | Protocol Type | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Virtual Network Identifier (VNI) | Reserved | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Variable Length Options | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +``` + +## Configuration + +### Common interface configuration + +```{eval-rst} +.. cmdincludemd:: /_include/interface-address.txt + :var0: geneve + :var1: gnv0 +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-description.txt + :var0: geneve + :var1: gnv0 +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-disable.txt + :var0: geneve + :var1: gnv0 +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-mac.txt + :var0: geneve + :var1: gnv0 +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-mtu.txt + :var0: geneve + :var1: gnv0 +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-ip.txt + :var0: geneve + :var1: gnv0 +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-ipv6.txt + :var0: geneve + :var1: gnv0 +``` + +### GENEVE options + +```{eval-rst} +.. cfgcmd:: set interfaces geneve gnv0 remote <address> + + Configure GENEVE tunnel far end/remote tunnel endpoint. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces geneve gnv0 vni <vni> + + {abbr}`VNI (Virtual Network Identifier)` is an identifier for a unique + element of a virtual network. In many situations this may represent an L2 + segment, however, the control plane defines the forwarding semantics of + decapsulated packets. The VNI MAY be used as part of ECMP forwarding + decisions or MAY be used as a mechanism to distinguish between overlapping + address spaces contained in the encapsulated packet when load balancing + across CPUs. +``` diff --git a/docs/configuration/interfaces/md-index.md b/docs/configuration/interfaces/md-index.md new file mode 100644 index 00000000..39546bae --- /dev/null +++ b/docs/configuration/interfaces/md-index.md @@ -0,0 +1,28 @@ +# Interfaces + +```{eval-rst} +.. toctree:: + :maxdepth: 1 + :includehidden: + + bonding + bridge + dummy + ethernet + geneve + l2tpv3 + loopback + macsec + openvpn + wireguard + pppoe + pseudo-ethernet + sstp-client + tunnel + virtual-ethernet + vti + vxlan + wireless + wwan + +``` diff --git a/docs/configuration/interfaces/md-l2tpv3.md b/docs/configuration/interfaces/md-l2tpv3.md new file mode 100644 index 00000000..4a4acd91 --- /dev/null +++ b/docs/configuration/interfaces/md-l2tpv3.md @@ -0,0 +1,198 @@ +--- +lastproofread: '2023-01-20' +--- + +```{include} /_include/need_improvement.txt +``` + +(l2tpv3-interface)= + +# L2TPv3 + +Layer 2 Tunnelling Protocol Version 3 is an IETF standard related to L2TP that +can be used as an alternative protocol to {ref}`mpls` for encapsulation of +multiprotocol Layer 2 communications traffic over IP networks. Like L2TP, +L2TPv3 provides a pseudo-wire service but is scaled to fit carrier requirements. + +L2TPv3 can be regarded as being to MPLS what IP is to ATM: a simplified version +of the same concept, with much of the same benefit achieved at a fraction of the +effort, at the cost of losing some technical features considered less important +in the market. + +In the case of L2TPv3, the features lost are teletraffic engineering features +considered important in MPLS. However, there is no reason these features could +not be re-engineered in or on top of L2TPv3 in later products. + +The protocol overhead of L2TPv3 is also significantly bigger than MPLS. + +L2TPv3 is described in {rfc}`3931`. + +## Configuration + +### Common interface configuration + +```{eval-rst} +.. cmdincludemd:: /_include/interface-common-without-dhcp.txt + :var0: l2tpv3 + :var1: l2tpeth0 +``` + +### L2TPv3 options + +```{eval-rst} +.. cfgcmd:: set interfaces l2tpv3 <interface> encapsulation <udp | ip> + + Set the encapsulation type of the tunnel. Valid values for encapsulation are: + udp, ip. + + This defaults to UDP +``` + +```{eval-rst} +.. cfgcmd:: set interfaces l2tpv3 <interface> source-address <address> + + Set the IP address of the local interface to be used for the tunnel. + + This address must be the address of a local interface. It may be specified as + an IPv4 address or an IPv6 address. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces l2tpv3 <interface> remote <address> + + Set the IP address of the remote peer. It may be specified as + an IPv4 address or an IPv6 address. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces l2tpv3 <interface> session-id <id> + + Set the session id, which is a 32-bit integer value. Uniquely identifies the + session being created. The value used must match the peer_session_id value + being used at the peer. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces l2tpv3 <interface> peer-session-id <id> + + Set the peer-session-id, which is a 32-bit integer value assigned to the + session by the peer. The value used must match the session_id value being + used at the peer. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces l2tpv3 <interface> tunnel-id <id> + + Set the tunnel id, which is a 32-bit integer value. Uniquely identifies the + tunnel into which the session will be created. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces l2tpv3 <interface> peer-tunnel-id <id> + + Set the tunnel id, which is a 32-bit integer value. Uniquely identifies the + tunnel into which the session will be created. +``` + +## Example + +### Over IP + +```none +# show interfaces l2tpv3 +l2tpv3 l2tpeth10 { + address 192.168.37.1/27 + encapsulation ip + source-address 192.0.2.1 + peer-session-id 100 + peer-tunnel-id 200 + remote 203.0.113.24 + session-id 100 + tunnel-id 200 +} +``` + +The inverse configuration has to be applied to the remote side. + +### Over UDP + +UDP mode works better with NAT: + +- Set source-address to your local IP (LAN). +- Add a forwarding rule matching UDP port on your internet router. + +```none +# show interfaces l2tpv3 +l2tpv3 l2tpeth10 { + address 192.168.37.1/27 + destination-port 9001 + encapsulation udp + source-address 192.0.2.1 + peer-session-id 100 + peer-tunnel-id 200 + remote 203.0.113.24 + session-id 100 + source-port 9000 + tunnel-id 200 +} +``` + +To create more than one tunnel, use distinct UDP ports. + +### 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: + +```none +set vpn ipsec authentication psk <pre-shared-name> id '%any' +set vpn ipsec authentication psk <pre-shared-name> secret <pre-shared-key> +set vpn ipsec interface <VPN-interface> +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 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 <connection-name> authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer <connection-name> connection-type 'initiate' +set vpn ipsec site-to-site peer <connection-name> ike-group 'test-IKE-1' +set vpn ipsec site-to-site peer <connection-name> ikev2-reauth 'inherit' +set vpn ipsec site-to-site peer <connection-name> local-address <local-ip> +set vpn ipsec site-to-site peer <connection-name> tunnel 1 esp-group 'test-ESP-1' +set vpn ipsec site-to-site peer <connection-name> tunnel 1 protocol 'l2tp' +``` + +Bridge: + +```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 bridge br0 member interface eth0 +set interfaces ethernet eth0 description 'L2 VPN Physical port' +``` + +L2TPv3: + +```none +set interfaces bridge br0 member interface 'l2tpeth0' +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 source-address <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 <peer-ip> +set interfaces l2tpv3 l2tpeth0 session-id '110' +set interfaces l2tpv3 l2tpeth0 source-port '5000' +set interfaces l2tpv3 l2tpeth0 tunnel-id '10' +``` diff --git a/docs/configuration/interfaces/md-loopback.md b/docs/configuration/interfaces/md-loopback.md new file mode 100644 index 00000000..37da5399 --- /dev/null +++ b/docs/configuration/interfaces/md-loopback.md @@ -0,0 +1,80 @@ +--- +lastproofread: '2023-01-20' +--- + +(loopback-interface)= + +# Loopback + +The loopback networking interface is a virtual network device implemented +entirely in software. All traffic sent to it "loops back" and just targets +services on your local machine. + +:::{note} +There can only be one loopback `lo` interface on the system. If +you need multiple interfaces, please use the {ref}`dummy-interface` +interface type. +::: + +:::{hint} +A loopback interface is always up, thus it could be used for +management traffic or as source/destination for and {abbr}`IGP (Interior +Gateway Protocol)` like {ref}`routing-bgp` so your internal BGP link is not +dependent on physical link states and multiple routes can be chosen to the +destination. A {ref}`dummy-interface` Interface should always be preferred +over a {ref}`loopback-interface` interface. +::: + +## Configuration + +### Common interface configuration + +```{eval-rst} +.. cmdincludemd:: /_include/interface-address.txt + :var0: loopback + :var1: lo +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-description.txt + :var0: loopback + :var1: lo +``` + +## Operation + +```{eval-rst} +.. opcmd:: show interfaces loopback + + Show brief interface information. + + .. code-block:: none + + vyos@vyos:~$ show interfaces loopback + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + lo 127.0.0.1/8 u/u + ::1/128 +``` + +```{eval-rst} +.. opcmd:: show interfaces loopback lo + + Show detailed information on the given loopback interface `lo`. + + .. code-block:: none + + vyos@vyos:~$ show interfaces loopback lo + lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000 + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 + inet 127.0.0.1/8 scope host lo + valid_lft forever preferred_lft forever + inet6 ::1/128 scope host + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 300 6 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 300 6 0 0 0 0 +``` diff --git a/docs/configuration/interfaces/md-macsec.md b/docs/configuration/interfaces/md-macsec.md new file mode 100644 index 00000000..c3cd2595 --- /dev/null +++ b/docs/configuration/interfaces/md-macsec.md @@ -0,0 +1,305 @@ +--- +lastproofread: '2023-01-20' +--- + +(macsec-interface)= + +# MACsec + +MACsec is an IEEE standard (IEEE 802.1AE) for MAC security, introduced in 2006. +It defines a way to establish a protocol independent connection between two +hosts with data confidentiality, authenticity and/or integrity, using +GCM-AES-128. MACsec operates on the Ethernet layer and as such is a layer 2 +protocol, which means it's designed to secure traffic within a layer 2 network, +including DHCP or ARP requests. It does not compete with other security +solutions such as IPsec (layer 3) or TLS (layer 4), as all those solutions are +used for their own specific use cases. + +## Configuration + +### Common interface configuration + +```{eval-rst} +.. cmdincludemd:: /_include/interface-common-with-dhcp.txt + :var0: macsec + :var1: macsec0 +``` + +### MACsec options + +```{eval-rst} +.. cfgcmd:: set interfaces macsec <interface> security cipher <gcm-aes-128|gcm-aes-256> + + Select cipher suite used for cryptographic operations. This setting is + mandatory. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces macsec <interface> security encrypt + + MACsec only provides authentication by default, encryption is optional. This + command will enable encryption for all outgoing packets. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces macsec <interface> source-interface <physical-source> + + A physical interface is required to connect this MACsec instance to. Traffic + leaving this interface will now be authenticated/encrypted. +``` + +#### Static Keys + +Static {abbr}`SAK (Secure Authentication Key)` mode can be configured manually on each +device wishing to use MACsec. Keys must be set statically on all devices for traffic +to flow properly. Key rotation is dependent on the administrator updating all keys +manually across connected devices. Static SAK mode can not be used with MKA. + +```{eval-rst} +.. cfgcmd:: set interfaces macsec <interface> security static key <key> + + Set the device's transmit (TX) key. This key must be a hex string that is 16-bytes + (GCM-AES-128) or 32-bytes (GCM-AES-256). +``` + +```{eval-rst} +.. cfgcmd:: set interfaces macsec <interface> security static peer <peer> mac <mac address> + + Set the peer's MAC address +``` + +```{eval-rst} +.. cfgcmd:: set interfaces macsec <interface> security static peer <peer> key <key> + + Set the peer's key used to receive (RX) traffic +``` + +```{eval-rst} +.. cfgcmd:: set interfaces macsec <interface> security static peer <peer> disable + + Disable the peer configuration +``` + +#### Key Management + +{abbr}`MKA (MACsec Key Agreement protocol)` is used to synchronize keys between +individual peers. + +```{eval-rst} +.. cfgcmd:: set interfaces macsec <interface> security mka cak <key> + + IEEE 802.1X/MACsec pre-shared key mode. This allows configuring MACsec with + a pre-shared key using a {abbr}`CAK (MACsec connectivity association key)` and + {abbr}`CKN (MACsec connectivity association name)` pair. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces macsec <interface> security mka ckn <key> + + {abbr}`CKN (MACsec connectivity association name)` key +``` + +```{eval-rst} +.. cfgcmd:: set interfaces macsec <interface> security mka priority <priority> + + The peer with lower priority will become the key server and start + distributing SAKs. +``` + +#### Replay protection + +```{eval-rst} +.. cfgcmd:: set interfaces macsec <interface> security replay-window <window> + + IEEE 802.1X/MACsec replay protection window. This determines a window in which + replay is tolerated, to allow receipt of frames that have been misordered by + the network. + + - ``0``: No replay window, strict check + - ``1-4294967295``: Number of packets that could be misordered +``` + +## Operation + +```{eval-rst} +.. opcmd:: run generate macsec mka cak <gcm-aes-128|gcm-aes-256> + + Generate {abbr}`MKA (MACsec Key Agreement protocol)` CAK key 128 or 256 bits. + + .. code-block:: none + + vyos@vyos:~$ generate macsec mka cak gcm-aes-128 + 20693b6e08bfa482703a563898c9e3ad +``` + +```{eval-rst} +.. opcmd:: run generate macsec mka ckn + + Generate {abbr}`MKA (MACsec Key Agreement protocol)` CAK key. + + .. code-block:: none + + vyos@vyos:~$ generate macsec mka ckn + 88737efef314ee319b2cbf30210a5f164957d884672c143aefdc0f5f6bc49eb2 +``` + +```{eval-rst} +.. opcmd:: show interfaces macsec + + List all MACsec interfaces. + + .. code-block:: none + + vyos@vyos:~$ show interfaces macsec + 17: macsec1: protect on validate strict sc off sa off encrypt on send_sci on end_station off scb off replay off + cipher suite: GCM-AES-128, using ICV length 16 + TXSC: 005056bfefaa0001 on SA 0 + 20: macsec0: protect on validate strict sc off sa off encrypt off send_sci on end_station off scb off replay off + cipher suite: GCM-AES-128, using ICV length 16 + TXSC: 005056bfefaa0001 on SA 0 +``` + +```{eval-rst} +.. opcmd:: show interfaces macsec <interface> + + Show specific MACsec interface information + + .. code-block:: none + + vyos@vyos:~$ show interfaces macsec macsec1 + 17: macsec1: protect on validate strict sc off sa off encrypt on send_sci on end_station off scb off replay off + cipher suite: GCM-AES-128, using ICV length 16 + TXSC: 005056bfefaa0001 on SA 0 +``` + +## Examples + +- Two routers connected both via eth1 through an untrusted switch +- R1 has 192.0.2.1/24 & 2001:db8::1/64 +- R2 has 192.0.2.2/24 & 2001:db8::2/64 + +**R1** + +```none +set interfaces macsec macsec1 address '192.0.2.1/24' +set interfaces macsec macsec1 address '2001:db8::1/64' +set interfaces macsec macsec1 security cipher 'gcm-aes-128' +set interfaces macsec macsec1 security encrypt +set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4' +set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836' +set interfaces macsec macsec1 source-interface 'eth1' +``` + +**R2** + +```none +set interfaces macsec macsec1 address '192.0.2.2/24' +set interfaces macsec macsec1 address '2001:db8::2/64' +set interfaces macsec macsec1 security cipher 'gcm-aes-128' +set interfaces macsec macsec1 security encrypt +set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4' +set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836' +set interfaces macsec macsec1 source-interface 'eth1' +``` + +Pinging (IPv6) the other host and intercepting the traffic in `eth1` will +show you the content is encrypted. + +```none +17:35:44.586668 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150: + 0x0000: 2c00 0000 000a 0050 56bf efaa 0001 d9fb ,......PV....... + 0x0010: 920a 8b8d 68ed 9609 29dd e767 25a4 4466 ....h...)..g%.Df + 0x0020: 5293 487b 9990 8517 3b15 22c7 ea5c ac83 R.H{....;."..\.. + 0x0030: 4c6e 13cf 0743 f917 2c4e 694e 87d1 0f09 Ln...C..,NiN.... + 0x0040: 0f77 5d53 ed75 cfe1 54df 0e5a c766 93cb .w]S.u..T..Z.f.. + 0x0050: c4f2 6e23 f200 6dfe 3216 c858 dcaa a73b ..n#..m.2..X...; + 0x0060: 4dd1 9358 d9e4 ed0e 072f 1acc 31c4 f669 M..X...../..1..i + 0x0070: e93a 9f38 8a62 17c6 2857 6ac5 ec11 8b0e .:.8.b..(Wj..... + 0x0080: 6b30 92a5 7ccc 720b k0..|.r. +``` + +Disabling the encryption on the link by removing `security encrypt` will show +the unencrypted but authenticated content. + +```none +17:37:00.746155 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150: + 0x0000: 2000 0000 0009 0050 56bf efaa 0001 86dd .......PV....... + 0x0010: 6009 86f3 0040 3a40 2001 0db8 0000 0000 `....@:@........ + 0x0020: 0000 0000 0000 0001 2001 0db8 0000 0000 ................ + 0x0030: 0000 0000 0000 0002 8100 d977 0f30 0003 ...........w.0.. + 0x0040: 1ca0 c65e 0000 0000 8d93 0b00 0000 0000 ...^............ + 0x0050: 1011 1213 1415 1617 1819 1a1b 1c1d 1e1f ................ + 0x0060: 2021 2223 2425 2627 2829 2a2b 2c2d 2e2f .!"#$%&'()*+,-./ + 0x0070: 3031 3233 3435 3637 87d5 eed3 3a39 d52b 01234567....:9.+ + 0x0080: a282 c842 5254 ef28 ...BRT.( +``` + +**R1 Static Key** + +```none +set interfaces macsec macsec1 address '192.0.2.1/24' +set interfaces macsec macsec1 address '2001:db8::1/64' +set interfaces macsec macsec1 security cipher 'gcm-aes-128' +set interfaces macsec macsec1 security encrypt +set interfaces macsec macsec1 security static key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' +set interfaces macsec macsec1 security static peer R2 mac 00:11:22:33:44:02 +set interfaces macsec macsec1 security static peer R2 key 'eadcc0aa9cf203f3ce651b332bd6e6c7' +set interfaces macsec macsec1 source-interface 'eth1' +``` + +**R2 Static Key** + +```none +set interfaces macsec macsec1 address '192.0.2.2/24' +set interfaces macsec macsec1 address '2001:db8::2/64' +set interfaces macsec macsec1 security cipher 'gcm-aes-128' +set interfaces macsec macsec1 security encrypt +set interfaces macsec macsec1 security static key 'eadcc0aa9cf203f3ce651b332bd6e6c7' +set interfaces macsec macsec1 security static peer R2 mac 00:11:22:33:44:01 +set interfaces macsec macsec1 security static peer R2 key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' +set interfaces macsec macsec1 source-interface 'eth1' +``` + +## MACsec over wan + +MACsec is an interesting alternative to existing tunneling solutions that +protects layer 2 by performing integrity, origin authentication, and optionally +encryption. The typical use case is to use MACsec between hosts and access +switches, between two hosts, or between two switches. in this example below, +we use VXLAN and MACsec to secure the tunnel. + +**R1 MACsec01** + +```none +set interfaces macsec macsec1 address '192.0.2.1/24' +set interfaces macsec macsec1 address '2001:db8::1/64' +set interfaces macsec macsec1 security cipher 'gcm-aes-128' +set interfaces macsec macsec1 security encrypt +set interfaces macsec macsec1 security static key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' +set interfaces macsec macsec1 security static peer SEC02 key 'eadcc0aa9cf203f3ce651b332bd6e6c7' +set interfaces macsec macsec1 security static peer SEC02 mac '00:11:22:33:44:02' +set interfaces macsec macsec1 source-interface 'vxlan1' +set interfaces vxlan vxlan1 mac '00:11:22:33:44:01' +set interfaces vxlan vxlan1 remote '10.1.3.3' +set interfaces vxlan vxlan1 source-address '172.16.100.1' +set interfaces vxlan vxlan1 vni '10' +set protocols static route 10.1.3.3/32 next-hop 172.16.100.2 +``` + +**R2 MACsec02** + +```none +set interfaces macsec macsec1 address '192.0.2.2/24' +set interfaces macsec macsec1 address '2001:db8::2/64' +set interfaces macsec macsec1 security cipher 'gcm-aes-128' +set interfaces macsec macsec1 security encrypt +set interfaces macsec macsec1 security static key 'eadcc0aa9cf203f3ce651b332bd6e6c7' +set interfaces macsec macsec1 security static peer SEC01 key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' +set interfaces macsec macsec1 security static peer SEC01 mac '00:11:22:33:44:01' +set interfaces macsec macsec1 source-interface 'vxlan1' +set interfaces vxlan vxlan1 mac '00:11:22:33:44:02' +set interfaces vxlan vxlan1 remote '10.1.2.2' +set interfaces vxlan vxlan1 source-address '172.16.100.2' +set interfaces vxlan vxlan1 vni '10' +set protocols static route 10.1.2.2/32 next-hop 172.16.100.1 +``` diff --git a/docs/configuration/interfaces/md-openvpn.md b/docs/configuration/interfaces/md-openvpn.md new file mode 100644 index 00000000..926cb42c --- /dev/null +++ b/docs/configuration/interfaces/md-openvpn.md @@ -0,0 +1,867 @@ +--- +lastproofread: '2021-07-05' +--- + +(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`. + +## Site-to-Site + +:::{figure} /_static/images/openvpn_site2site_diagram.jpg +::: + +OpenVPN is popular for client-server setups, but its site-to-site mode +remains a relatively obscure feature, and many router appliances +still don't support it. However, it's very useful for quickly setting up +tunnels between routers. + +As of VyOS 1.4, OpenVPN site-to-site mode can use either pre-shared keys or x.509 certificates. + +The pre-shared key mode is deprecated and will be removed from future OpenVPN versions, +so VyOS will have to remove support for that option as well. The reason is that using pre-shared keys +is significantly less secure than using TLS. + +We'll configure OpenVPN using self-signed certificates, and then discuss the legacy +pre-shared key mode. + +In both cases, we will use the following settings: + +- The public IP address of the local side of the VPN will be 198.51.100.10. +- The public IP address of the remote side of the VPN 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. +- The local site will have a subnet of 10.0.0.0/16. +- The remote site will have a subnet of 10.1.0.0/16. +- 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. + +### Setting up certificates + +Setting up a full-blown PKI with a CA certificate would arguably defeat the purpose +of site-to-site OpenVPN, since its main goal is supposed to be configuration simplicity, +compared to server setups that need to support multiple clients. + +However, since VyOS 1.4, it is possible to verify self-signed certificates using +certificate fingerprints. + +On both sides, you need to generate a self-signed certificate, preferrably using the "ec" (elliptic curve) type. +You can generate them by executing command `run generate pki certificate self-signed install <name>` in the configuration mode. +Once the command is complete, it will add the certificate to the configuration session, to the `pki` subtree. +You can then review the proposed changes and commit them. + +```none +vyos@vyos# run generate pki certificate self-signed install openvpn-local +Enter private key type: [rsa, dsa, ec] (Default: rsa) ec +Enter private key bits: (Default: 256) +Enter country code: (Default: GB) +Enter state: (Default: Some-State) +Enter locality: (Default: Some-City) +Enter organization name: (Default: VyOS) +Enter common name: (Default: vyos.io) +Do you want to configure Subject Alternative Names? [y/N] +Enter how many days certificate will be valid: (Default: 365) +Enter certificate type: (client, server) (Default: server) +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +[edit] + +vyos@vyos# compare +[pki] ++ certificate openvpn-local { ++ certificate "MIICJTCCAcugAwIBAgIUMXLfRNJ5iOjk/ uAZqUe4phW8MdgwCgYIKoZIzj0EAwIwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA5MDcyMTQzMTNaFw0yNDA5MDYyMTQzMTNaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxEDAOBgNVBAMMB3Z5b3MuaW8wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASp7D0vE3SKSAWAzr/lw9Eq9Q89r247AJR6ec/GT26AIcVA1bsongV1YaWvRwzTPC/yi5pkzV/PcT/WU7JQIyMWo3UwczAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDATAdBgNVHQ4EFgQUBrAxRdFppdG/UBRdo7qNyHutaTQwHwYDVR0jBBgwFoAUBrAxRdFppdG/UBRdo7qNyHutaTQwCgYIKoZIzj0EAwIDSAAwRQIhAI2+8C92z9wTcTWkQ/goRxs10EBC+h78O+vgo9k97z5iAiBSeqfaVr5taQTS31+McGTAK3cYWNTg0DlOBI8aKO2oRg==" ++ private { ++ key "MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgtOeEb0dMb5P/2Exi09WWvk6Cvz0oOBoDuP68ZimS2LShRANCAASp7D0vE3SKSAWAzr/lw9Eq9Q89r247AJR6ec/GT26AIcVA1bsongV1YaWvRwzTPC/yi5pkzV/PcT/WU7JQIyMW" ++ } ++ } + +[edit] + +vyos@vyos# commit +``` + +You do **not** need to copy the certificate to the other router. Instead, you need to retrieve its SHA-256 fingerprint. +OpenVPN only supports SHA-256 fingerprints at the moment, so you need to use the following command: + +```none +vyos@vyos# run show pki certificate openvpn-local fingerprint sha256 +5C:B8:09:64:8B:59:51:DC:F4:DF:2C:12:5C:B7:03:D1:68:94:D7:5B:62:C2:E1:83:79:F1:F0:68:B2:81:26:79 +``` + +Note: certificate names don't matter, we use 'openvpn-local' and 'openvpn-remote' but they can be arbitrary. + +Repeat the procedure on the other router. + +### Setting up OpenVPN + +Local Configuration: + +```none +Configure the tunnel: + +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 '203.0.113.11' # Public IP of the other side +set interfaces openvpn vtun1 local-port '1195' +set interfaces openvpn vtun1 remote-port '1195' +set interfaces openvpn vtun1 local-address '10.255.1.1' # Local IP of vtun interface +set interfaces openvpn vtun1 remote-address '10.255.1.2' # Remote IP of vtun interface +set interfaces openvpn vtun1 tls certificate 'openvpn-local' # The self-signed certificate +set interfaces openvpn vtun1 tls peer-fingerprint <remote cert fingerprint> # The output of 'run show pki certificate <name> fingerprint sha256 + on the remote rout +``` + +Remote Configuration: + +```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' # Pub IP of other site +set interfaces openvpn vtun1 local-port '1195' +set interfaces openvpn vtun1 remote-port '1195' +set interfaces openvpn vtun1 local-address '10.255.1.2' # Local IP of vtun interface +set interfaces openvpn vtun1 remote-address '10.255.1.1' # Remote IP of vtun interface +set interfaces openvpn vtun1 tls certificate 'openvpn-remote' # The self-signed certificate +set interfaces openvpn vtun1 tls peer-fingerprint <local cert fingerprint> # The output of 'run show pki certificate <name> fingerprint sha256 + on the local router +``` + +### Pre-shared keys + +Until VyOS 1.4, the only option for site-to-site OpenVPN without PKI was to use pre-shared keys. +That option is still available but it is deprecated and will be removed in the future. +However, if you need to set up a tunnel to an older VyOS version or a system with older OpenVPN, +you need to still need to know how to use it. + +First, you need to generate a key by running `run generate pki openvpn shared-secret install <name>` from configuration mode. +You can use any name, we will use `s2s`. + +```none +vyos@local# run generate pki openvpn shared-secret install s2s +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +[edit] +vyos@local# compare +[pki openvpn shared-secret] ++ s2s { ++ key "7c73046a9da91e874d31c7ad894a32688cda054bde157c64270f28eceebc0bb2f44dbb70335fad45148b0456aaa78cb34a34c0958eeed4f75e75fd99ff519ef940f7029a316c436d2366a2b0fb8ea1d1c792a65f67d10a461af83ef4530adc25d1c872de6d9c7d5f338223d1f3b66dc3311bbbddc0e05228c47b91c817c721aadc7ed18f0662df52ad14f898904372679e3d9697d062b0869d12de47ceb2e626fa12e1926a3119be37dd29c9b0ad81997230f4038926900d5edb78522d2940cfe207f8e2b948e0d459fa137ebb18064ac5982b28dd1899020b4f2b082a20d5d4eb65710fbb1e62b5e061df39620267eab429d3eedd9a1ae85957457c8e4655f3" ++ version "1" ++ } + +[edit] + +vyos@local# commit +[edit] +``` + +Then you need to install the key on the remote router: + +```none +vyos@remote# set pki openvpn shared-secret s2s key <generated key string> +``` + +Then you need to set the key in your OpenVPN interface settings: + +```none +set interfaces openvpn vtun1 shared-secret-key s2s +``` + +### Firewall Exceptions + +For the OpenVPN traffic to pass through the WAN interface, you must create a +firewall exception. + +```none +set firewall name OUTSIDE_LOCAL rule 10 action accept +set firewall name OUTSIDE_LOCAL rule 10 description 'Allow established/related' +set firewall name OUTSIDE_LOCAL rule 10 state established enable +set firewall name OUTSIDE_LOCAL rule 10 state related enable +set firewall name OUTSIDE_LOCAL rule 20 action accept +set firewall name OUTSIDE_LOCAL rule 20 description OpenVPN_IN +set firewall name OUTSIDE_LOCAL rule 20 destination port 1195 +set firewall name OUTSIDE_LOCAL rule 20 log enable +set firewall name OUTSIDE_LOCAL rule 20 protocol udp +set firewall name OUTSIDE_LOCAL rule 20 source +``` + +You should also ensure that the OUTISDE_LOCAL firewall group is applied to the +WAN interface and a direction (local). + +```none +set firewall interface eth0 local name 'OUTSIDE-LOCAL' +``` + +Static Routing: + +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: + +```none +set protocols static route 10.1.0.0/16 interface vtun1 +``` + +Remote Configuration: + +```none +set protocols static route 10.0.0.0/16 interface vtun1 +``` + +The configurations above will default to using 256-bit AES in GCM mode +for encryption (if both sides support NCP) and SHA-1 for HMAC authentication. +SHA-1 is considered weak, but other hashing algorithms are available, as are +encryption algorithms: + +For Encryption: + +This sets the cipher when NCP (Negotiable Crypto Parameters) is disabled or +OpenVPN version < 2.4.0. + +```none +vyos@vyos# set interfaces openvpn vtun1 encryption cipher +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 CBC + aes128gcm AES algorithm with 128-bit key GCM + aes192 AES algorithm with 192-bit key CBC + aes192gcm AES algorithm with 192-bit key GCM + aes256 AES algorithm with 256-bit key CBC + aes256gcm AES algorithm with 256-bit key GCM +``` + +This sets the accepted ciphers to use when version => 2.4.0 and NCP is +enabled (which is the default). Default NCP cipher for versions >= 2.4.0 is +aes256gcm. The first cipher in this list is what server pushes to clients. + +```none +vyos@vyos# set int open vtun0 encryption ncp-ciphers +Possible completions: + des DES algorithm + 3des DES algorithm with triple encryption + aes128 AES algorithm with 128-bit key CBC + aes128gcm AES algorithm with 128-bit key GCM + aes192 AES algorithm with 192-bit key CBC + aes192gcm AES algorithm with 192-bit key GCM + aes256 AES algorithm with 256-bit key CBC + aes256gcm AES algorithm with 256-bit key GCM +``` + +For Hashing: + +```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. + +Firewall policy can also be applied to the tunnel interface for `local`, `in`, +and `out` directions and functions 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. + +## Server + +Multi-client server is the most popular OpenVPN mode on routers. It always uses +x.509 authentication and therefore requires a PKI setup. Refer this topic +{ref}`configuration/pki/index:pki` to generate 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. +::: + +```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 generate, add and specify the names of the cryptographic materials. +Each of the install command should be applied to the configuration and commited +before using under the openvpn interface configuration. + +```none +run generate pki ca install ca-1 # Follow the instructions to generate CA cert. +Configure mode commands to install: +set pki ca ca-1 certificate 'generated_cert_string' +set pki ca ca-1 private key 'generated_private_key' + +run generate pki certificate sign ca-1 install srv-1 # Follow the instructions to generate server cert. +Configure mode commands to install: +set pki certificate srv-1 certificate 'generated_server_cert' +set pki certificate srv-1 private key 'generated_private_key' + +run generate pki dh install dh-1 # Follow the instructions to generate set of + Diffie-Hellman parameters. +Generating parameters... +Configure mode commands to install DH parameters: +set pki dh dh-1 parameters 'generated_dh_params_set' + +set interfaces openvpn vtun10 tls ca-certificate ca-1 +set interfaces openvpn vtun10 tls certificate srv-1 +set interfaces openvpn vtun10 tls dh-params dh-1 +``` + +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 our router, we will use a push-route option for +installing that route on clients. + +```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`: +::: + +```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: + +```none +set protocols static route 10.23.0.0/20 interface vtun10 +``` + +Additionally, each client needs a copy of ca cert and its own client key and +cert files. The files are plaintext so they may be copied either manually from the CLI. +Client key and cert files should be signed with the proper ca cert and generated on the +server side. + +HQ's router requires the following steps to generate crypto materials for the Branch 1: + +```none +run generate pki certificate sign ca-1 install branch-1 # Follow the instructions to generate client + cert for Branch 1 +Configure mode commands to install: +``` + +Branch 1's router might have the following lines: + +```none +set pki ca ca-1 certificate 'generated_cert_string' # CA cert generated on HQ router +set pki certificate branch-1 certificate 'generated_branch_cert' # Client cert generated and signed on HQ router +set pki certificate branch-1 private key 'generated_private_key' # Client cert key generated on HQ router + +set interfaces openvpn vtun10 tls ca-cert ca-1 +set interfaces openvpn vtun10 tls certificate branch-1 +``` + +### Client Authentication + +#### LDAP + +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 + +```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 this: + +```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 + +```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: + +```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: + +```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 "--verify-client-cert none" + openvpn-option --comp-lzo + openvpn-option --persist-key + openvpn-option --persist-tun + server { + domain-name example.com + max-connections 5 + name-server 203.0.113.0.10 + name-server 198.51.100.3 + subnet 172.18.100.128/29 + } + tls { + ca-certificate ca.crt + certificate server.crt + dh-params dh1024.pem + } + } +``` + +## 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. + +(openvpn-client-server)= + +### Configuration + +#### Server Side + +```none +set interfaces openvpn vtun10 encryption cipher '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 ca-1 +set interfaces openvpn vtun10 tls certificate srv-1 +set interfaces openvpn vtun10 tls crypt-key srv-1 +set interfaces openvpn vtun10 tls dh-params dh-1 +set interfaces openvpn vtun10 use-lzo-compression +``` + +(openvpn-client-client)= + +#### Client Side + +```none +set interfaces openvpn vtun10 encryption cipher '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 ca-1 +set interfaces openvpn vtun10 tls certificate client-1 +set interfaces openvpn vtun10 tls crypt-key client-1 +set interfaces openvpn vtun10 use-lzo-compression +``` + +### Options + +We do not have CLI nodes for every single OpenVPN option. If an option is +missing, a feature request should be opened at [Phabricator] so all users can +benefit from it (see {ref}`issues_features`). + +If you are a hacker or want to try on your own we support passing raw OpenVPN +options to OpenVPN. + +```{eval-rst} +.. cfgcmd:: 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. + +```{eval-rst} +.. cfgcmd:: set interfaces openvpn vtun10 openvpn-option + 'push "keepalive 1 10"' +``` + +Will add `push "keepalive 1 10"` to the generated OpenVPN config file. + +:::{note} +Sometimes option lines in the generated OpenVPN configuration require +quotes. This is done through a hack on our config generator. You can pass +quotes using the `"` statement. +::: + +### Server bridge + +In Ethernet bridging configurations, OpenVPN's server mode can be set as a +'bridge' where the VPN tunnel encapsulates entire Ethernet frames +(up to 1514 bytes) instead of just IP packets (up to 1500 bytes). This setup +allows clients to transmit Layer 2 frames through the OpenVPN tunnel. Below, +we outline a basic configuration to achieve this: + +Server Side: + +```none +set interfaces bridge br10 member interface eth1.10 +set interfaces bridge br10 member interface vtun10 +set interfaces openvpn vtun10 device-type 'tap' +set interfaces openvpn vtun10 encryption data-ciphers 'aes192' +set interfaces openvpn vtun10 hash 'sha256'' +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 server bridge gateway '10.10.0.1' +set interfaces openvpn vtun10 server bridge start '10.10.0.100' +set interfaces openvpn vtun10 server bridge stop '10.10.0.200' +set interfaces openvpn vtun10 server bridge subnet-mask '255.255.255.0' +set interfaces openvpn vtun10 server topology 'subnet' +set interfaces openvpn vtun10 tls ca-certificate 'ca-1' +set interfaces openvpn vtun10 tls certificate 'srv-1' +set interfaces openvpn vtun10 tls dh-params 'srv-1' +``` + +Client Side : + +```none +set interfaces openvpn vtun10 device-type 'tap' +set interfaces openvpn vtun10 encryption data-ciphers 'aes192' +set interfaces openvpn vtun10 hash 'sha256'' +set interfaces openvpn vtun10 mode 'client' +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-certificate 'ca-1' +set interfaces openvpn vtun10 tls certificate 'client-1' +``` + +## Multi-factor Authentication + +VyOS supports multi-factor authentication (MFA) or two-factor authentication +using Time-based One-Time Password (TOTP). Compatible with Google Authenticator +software token, other software tokens. + +### MFA TOTP options + +```{eval-rst} +.. cfgcmd:: set interfaces openvpn <interface> server mfa totp challenge <enable | disable> + + If set to enable, openvpn-otp will expect password as result of challenge/ + response protocol. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces openvpn <interface> server mfa totp digits <1-65535> + + Configure number of digits to use for totp hash (default: 6) +``` + +```{eval-rst} +.. cfgcmd:: set interfaces openvpn <interface> server mfa totp drift <1-65535> + + Configure time drift in seconds (default: 0) +``` + +```{eval-rst} +.. cfgcmd:: set interfaces openvpn <interface> server mfa totp slop <1-65535> + + Configure maximum allowed clock slop in seconds (default: 180) +``` + +```{eval-rst} +.. cfgcmd:: set interfaces openvpn <interface> server mfa totp step <1-65535> + + Configure step value for totp in seconds (default: 30) +``` + +### Example + +```none +set interfaces openvpn vtun20 encryption cipher 'aes256' +set interfaces openvpn vtun20 hash 'sha512' +set interfaces openvpn vtun20 mode 'server' +set interfaces openvpn vtun20 persistent-tunnel +set interfaces openvpn vtun20 server client user1 +set interfaces openvpn vtun20 server mfa totp challenge 'disable' +set interfaces openvpn vtun20 server subnet '10.10.2.0/24' +set interfaces openvpn vtun20 server topology 'subnet' +set interfaces openvpn vtun20 tls ca-certificate 'openvpn_vtun20' +set interfaces openvpn vtun20 tls certificate 'openvpn_vtun20' +set interfaces openvpn vtun20 tls dh-params 'dh-pem' +``` + +For every client in the openvpn server configuration a totp secret is created. +To display the authentication information, use the command: + +```{eval-rst} +.. cfgcmd:: show interfaces openvpn <interface> user <username> mfa <qrcode|secret|uri> +``` + +An example: + +```none +vyos@vyos:~$ sh interfaces openvpn vtun20 user user1 mfa qrcode +█████████████████████████████████████ +█████████████████████████████████████ +████ ▄▄▄▄▄ █▀▄▀ ▀▀▄▀ ▀▀▄ █ ▄▄▄▄▄ ████ +████ █ █ █▀▀▄ █▀▀▀█▀██ █ █ █ ████ +████ █▄▄▄█ █▀█ ▄ █▀▀ █▄▄▄█ █▄▄▄█ ████ +████▄▄▄▄▄▄▄█▄█ █ █ ▀ █▄▀▄█▄▄▄▄▄▄▄████ +████▄▄ ▄ █▄▄ ▄▀▄█▄ ▄▀▄█ ▄▄▀ ▀▄█ ▀████ +████ ▀██▄▄▄█▄ ██ █▄▄▄▄ █▄▀█ █ █▀█████ +████ ▄█▀▀▄▄ ▄█▀ ▀▄ ▄▄▀▄█▀▀▀ ▄▄▀████ +████▄█ ▀▄▄▄▀ ▀ ▄█ ▄ █▄█▀ █▀ █▀█████ +████▀█▀ ▀ ▄█▀▄▀▀█▄██▄█▀▀ ▀ ▀ ▄█▀████ +████ ██▄▄▀▄▄█ ██ ▀█ ▄█ ▀▄█ █▀██▀████ +████▄███▄█▄█ ▀█▄ ██▄▄▄█▀ ▄▄▄ █ ▀ ████ +████ ▄▄▄▄▄ █▄█▀▄ ▀▄ ▀█▀ █▄█ ██▀█████ +████ █ █ █ ▄█▀█▀▀▄ ▄▀▀▄▄▄▄▄▄ ████ +████ █▄▄▄█ █ ▄ ▀ █▄▄▄██▄▀█▄▀▄█▄ █████ +████▄▄▄▄▄▄▄█▄██▄█▄▄▄▄▄█▄█▄█▄██▄██████ +█████████████████████████████████████ +█████████████████████████████████████ +``` + +Use the QR code to add the user account in Google authenticator application and +on client side, use the OTP number as password. + +## OpenVPN Data Channel Offload (DCO) + +OpenVPN Data Channel Offload (DCO) enables significant performance enhancement +in encrypted OpenVPN data processing. By minimizing context switching for each +packet, DCO effectively reduces overhead. This optimization is achieved by +keeping most data handling tasks within the kernel, avoiding frequent switches +between kernel and user space for encryption and packet handling. + +As a result, the processing of each packet becomes more efficient, potentially +leveraging hardware encryption offloading support available in the kernel. + +:::{note} +OpenVPN DCO is not full OpenVPN features supported , is currently +considered experimental. Furthermore, there are certain OpenVPN features and +use cases that remain incompatible with DCO. To get a comprehensive +understanding of the limitations associated with DCO, refer to the list of +known limitations in the documentation. + +<https://community.openvpn.net/openvpn/wiki/DataChannelOffload/Features> +::: + +### Enabling OpenVPN DCO + +DCO support is a per-tunnel option and it is not automatically enabled by +default for new or upgraded tunnels. Existing tunnels will continue to function +as they have in the past. + +DCO can be enabled for both new and existing tunnels,VyOS adds an option in each +tunnel configuration where we can enable this function .The current best +practice is to create a new tunnel with DCO to minimize the chance of problems +with existing clients. + +```{eval-rst} +.. cfgcmd:: set interfaces openvpn <name> offload dco + + Enable OpenVPN Data Channel Offload feature by loading the appropriate kernel + module. + + Disabled by default - no kernel module loaded. + + .. note:: Enable this feature causes an interface reset. + +``` + +### Troubleshooting + +VyOS provides some operational commands on OpenVPN. + +#### Check status + +The following commands let you check tunnel status. + +```{eval-rst} +.. opcmd:: show openvpn client + + Use this command to check the tunnel status for OpenVPN client interfaces. +``` + +```{eval-rst} +.. opcmd:: show openvpn server + + Use this command to check the tunnel status for OpenVPN server interfaces. +``` + +```{eval-rst} +.. opcmd:: show openvpn site-to-site + + Use this command to check the tunnel status for OpenVPN site-to-site + interfaces. + +``` + +#### Reset OpenVPN + +The following commands let you reset OpenVPN. + +```{eval-rst} +.. opcmd:: reset openvpn client <text> + + Use this command to reset the specified OpenVPN client. +``` + +```{eval-rst} +.. opcmd:: reset openvpn interface <interface> + + Use this command to reset the OpenVPN process on a specific interface. + + +``` + +```{include} /_include/common-references.txt +``` diff --git a/docs/configuration/interfaces/md-pppoe.md b/docs/configuration/interfaces/md-pppoe.md new file mode 100644 index 00000000..25e017f4 --- /dev/null +++ b/docs/configuration/interfaces/md-pppoe.md @@ -0,0 +1,443 @@ +--- +lastproofread: '2022-07-27' +--- + +(pppoe-interface)= + +# PPPoE + +{abbr}`PPPoE (Point-to-Point Protocol over Ethernet)` is a network protocol +for encapsulating PPP frames inside Ethernet frames. It appeared in 1999, +in the context of the boom of DSL as the solution for tunneling packets +over the DSL connection to the {abbr}`ISPs (Internet Service Providers)` +IP network, and from there to the rest of the Internet. A 2005 networking +book noted that "Most DSL providers use PPPoE, which provides authentication, +encryption, and compression." Typical use of PPPoE involves leveraging the +PPP facilities for authenticating the user with a username and password, +predominately via the PAP protocol and less often via CHAP. + +## Operating Modes + +VyOS supports setting up PPPoE in two different ways to a PPPoE internet +connection. This is because most ISPs provide a modem that is also a wireless +router. + +### Home Users + +In this method, the DSL Modem/Router connects to the ISP for you with your +credentials preprogrammed into the device. This gives you an {rfc}`1918` +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. + +### Business Users + +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 Transceiver 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. + +## Configuration + +### Common interface configuration + +```{eval-rst} +.. cmdincludemd:: /_include/interface-description.txt + :var0: pppoe + :var1: pppoe0 +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-disable.txt + :var0: pppoe + :var1: pppoe0 +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-mtu.txt + :var0: pppoe + :var1: pppoe0 +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-vrf.txt + :var0: pppoe + :var1: pppoe0 +``` + +### PPPoE options + +```{eval-rst} +.. cfgcmd:: set interfaces pppoe <interface> access-concentrator <name> + + Use this command to restrict the PPPoE session on a given access + concentrator. Normally, a host sends a PPPoE initiation packet to start the + PPPoE discovery process, a number of access concentrators respond with offer + packets and the host selects one of the responding access concentrators to + serve this session. + + This command allows you to select a specific access concentrator when you + know the access concentrators `<name>`. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces pppoe <interface> authentication username <username> + + Use this command to set the username for authenticating with a remote PPPoE + endpoint. Authentication is optional from the system's point of view but + most service providers require it. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces pppoe <interface> authentication password <password> + + Use this command to set the password for authenticating with a remote PPPoE + endpoint. Authentication is optional from the system's point of view but + most service providers require it. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces pppoe <interface> connect-on-demand + + When set the interface is enabled for "dial-on-demand". + + Use this command to instruct the system to establish a PPPoE connection + automatically once traffic passes through the interface. A disabled on-demand + connection is established at boot time and remains up. If the link fails for + any reason, the link is brought back up immediately. + + Enabled on-demand PPPoE connections bring up the link only when traffic needs + to pass this link. If the link fails for any reason, the link is brought + back up automatically once traffic passes the interface again. If you + configure an on-demand PPPoE connection, you must also configure the idle + timeout period, after which an idle PPPoE link will be disconnected. A + non-zero idle timeout will never disconnect the link after it first came up. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces pppoe <interface> no-default-route + + Only request an address from the PPPoE server but do not install any default + route. + + Example: + + .. code-block:: none + + set interfaces pppoe pppoe0 no-default-route + + .. note:: This command got added in VyOS 1.4 and inverts the logic from the old + ``default-route`` CLI option. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces pppoe <interface> default-route-distance <distance> + + Set the distance for the default gateway sent by the PPPoE server. + + Example: + + .. code-block:: none + + set interfaces pppoe pppoe0 default-route-distance 220 +``` + +```{eval-rst} +.. cfgcmd:: set interfaces pppoe <interface> mru <mru> + + Set the {abbr}`MRU (Maximum Receive Unit)` to `mru`. PPPd will ask the peer to + send packets of no more than `mru` bytes. The value of `mru` must be between 128 + and 16384. + + A value of 296 works well on very slow links (40 bytes for TCP/IP header + 256 + bytes of data). + + The default is 1492. + + .. note:: When using the IPv6 protocol, MRU must be at least 1280 bytes. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces pppoe <interface> idle-timeout <time> + + Use this command to set the idle timeout interval to be used with on-demand + PPPoE sessions. When an on-demand connection is established, the link is + brought up only when traffic is sent and is disabled when the link is idle + for the interval specified. + + If this parameter is not set or 0, an on-demand link will not be taken down + when it is idle and after the initial establishment of the connection. It + will stay up forever. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces pppoe <interface> holdoff <time> + + Use this command to set re-dial delay time to be used with persist PPPoE + sessions. When the PPPoE session is terminated by peer, and on-demand + option is not set, the router will attempt to re-establish the PPPoE link. + + If this parameter is not set, the default holdoff time is 30 seconds. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces pppoe <interface> local-address <address> + + Use this command to set the IP address of the local endpoint of a PPPoE + session. If it is not set it will be negotiated. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces pppoe <interface> no-peer-dns + + Use this command to not install advertised DNS nameservers into the local + system. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces pppoe <interface> remote-address <address> + + Use this command to set the IP address of the remote endpoint of a PPPoE + session. If it is not set it will be negotiated. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces pppoe <interface> service-name <name> + + Use this command to specify a service name by which the local PPPoE interface + can select access concentrators to connect with. It will connect to any + access concentrator if not set. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces pppoe <interface> source-interface <source-interface> + + Use this command to link the PPPoE connection to a physical interface. Each + PPPoE connection must be established over a physical interface. Interfaces + can be regular Ethernet interfaces, VIFs or bonding interfaces/VIFs. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces pppoe <interface> ip adjust-mss <mss | clamp-mss-to-pmtu> + + 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'. + + .. note:: This command was introduced in VyOS 1.4 - it was previously called: + ``set firewall options interface <name> adjust-mss <value>`` + + .. hint:: MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting in + 1452 bytes on a 1492 byte MTU. + + Instead of a numerical MSS value `clamp-mss-to-pmtu` can be used to + automatically set the proper value. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces pppoe <interface> ip disable-forwarding + + Configure interface-specific Host/Router behaviour. If set, the interface will + switch to host mode and IPv6 forwarding will be disabled on this interface. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces pppoe <interface> ip source-validation <strict | loose | disable> + + Enable policy for source validation by reversed path, as specified in + {rfc}`3704`. Current recommended practice in {rfc}`3704` is to enable strict + mode to prevent IP spoofing from DDos attacks. If using asymmetric routing + or other complicated routing, then loose mode is recommended. + + - strict: Each incoming packet is tested against the FIB and if the interface + is not the best reverse path the packet check will fail. By default failed + packets are discarded. + + - loose: Each incoming packet's source address is also tested against the FIB + and if the source address is not reachable via any interface the packet + check will fail. + + - disable: No source validation +``` + +#### IPv6 + +```{eval-rst} +.. cfgcmd:: set interfaces pppoe <interface> ipv6 address autoconf + + Use this command to enable acquisition of IPv6 address using stateless + autoconfig (SLAAC). +``` + +```{eval-rst} +.. cfgcmd:: set interfaces pppoe <interface> ipv6 adjust-mss <mss | clamp-mss-to-pmtu> + + 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'. + + .. note:: This command was introduced in VyOS 1.4 - it was previously called: + ``set firewall options interface <name> adjust-mss <value>`` + + .. hint:: MSS value = MTU - 40 (IPv6 header) - 20 (TCP header), resulting in + 1432 bytes on a 1492 byte MTU. + + Instead of a numerical MSS value `clamp-mss-to-pmtu` can be used to + automatically set the proper value. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces pppoe <interface> ipv6 disable-forwarding + + Configure interface-specific Host/Router behaviour. If set, the interface will + switch to host mode and IPv6 forwarding will be disabled on this interface. +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-dhcpv6-prefix-delegation.txt + :var0: pppoe + :var1: pppoe0 +``` + +## Operation + +```{eval-rst} +.. opcmd:: show interfaces pppoe <interface> + + Show detailed information on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces pppoe pppoe0 + pppoe0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1492 qdisc pfifo_fast state UNKNOWN group default qlen 3 + link/ppp + inet 192.0.2.1 peer 192.0.2.255/32 scope global pppoe0 + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 7002658233 5064967 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 533822843 1620173 0 0 0 0 +``` + +```{eval-rst} +.. opcmd:: show interfaces pppoe <interface> queue + + Displays queue information for a PPPoE interface. + + .. code-block:: none + + vyos@vyos:~$ show interfaces pppoe pppoe0 queue + qdisc pfifo_fast 0: root refcnt 2 bands 3 priomap 1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1 + Sent 534625359 bytes 1626761 pkt (dropped 62, overlimits 0 requeues 0) + backlog 0b 0p requeues 0 +``` + +### Connect/Disconnect + +```{eval-rst} +.. opcmd:: disconnect interface <interface> + + Test disconnecting given connection-oriented interface. `<interface>` can be + ``pppoe0`` as the example. +``` + +```{eval-rst} +.. opcmd:: connect interface <interface> + + Test connecting given connection-oriented interface. `<interface>` can be + ``pppoe0`` as the example. +``` + +## Example + +Requirements: + +- Your ISPs modem is connected to port `eth0` of your VyOS box. +- No VLAN tagging required by your ISP. +- You need your PPPoE credentials from your DSL ISP in order to configure + this. The usual username is in the form of <mailto: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 `name-server` option set to `none`, VyOS will ignore the + nameservers your ISP sends you and thus you can fully rely on the ones you + have configured statically. + +:::{note} +Syntax has changed from VyOS 1.2 (crux) and it will be automatically +migrated during an upgrade. + +A default route is automatically installed once the interface is up. +To change this behavior use the `no-default-route` CLI option. +::: + +```none +set interfaces pppoe pppoe0 authentication username 'userid' +set interfaces pppoe pppoe0 authentication password 'secret' +set interfaces pppoe pppoe0 source-interface 'eth0' +``` + +You should add a firewall to your configuration above as well by +assigning it to the pppoe0 itself as shown here: + +```none +set firewall interface pppoe0 in name NET-IN +set firewall interface pppoe0 local name NET-LOCAL +set firewall interface pppoe0 out name NET-OUT +``` + +### VLAN Example + +Some recent ISPs require you to build the PPPoE connection through a VLAN +interface. One of those ISPs is e.g. Deutsche Telekom in Germany. VyOS +can easily create a PPPoE session through an encapsulated VLAN interface. +The following configuration will run your PPPoE connection through VLAN7 +which is the default VLAN for Deutsche Telekom: + +```none +set interfaces pppoe pppoe0 authentication username 'userid' +set interfaces pppoe pppoe0 authentication password 'secret' +set interfaces pppoe pppoe0 source-interface 'eth0.7' +``` + +#### IPv6 DHCPv6-PD Example + + +The following configuration will setup a PPPoE session source from eth1 and +assign a /64 prefix out of a /56 delegation (requested from the ISP) to eth0. +The IPv6 address assigned to eth0 will be \<prefix>::1/64. If you do not know +the prefix size delegated to you, start with sla-len 0. + +In addition we setup IPv6 {abbr}`RA (Router Advertisements)` to make the +prefix known on the eth0 link. + + +```none +set interfaces pppoe pppoe0 authentication username vyos +set interfaces pppoe pppoe0 authentication password vyos +set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth0 address '1' +set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth0 sla-id '0' +set interfaces pppoe pppoe0 dhcpv6-options pd 0 length '56' +set interfaces pppoe pppoe0 ipv6 address autoconf +set interfaces pppoe pppoe0 source-interface eth1 + +set service router-advert interface eth0 prefix ::/64 +``` diff --git a/docs/configuration/interfaces/md-pseudo-ethernet.md b/docs/configuration/interfaces/md-pseudo-ethernet.md new file mode 100644 index 00000000..641bc8fb --- /dev/null +++ b/docs/configuration/interfaces/md-pseudo-ethernet.md @@ -0,0 +1,68 @@ +--- +lastproofread: '2023-01-26' +--- + +(pseudo-ethernet-interface)= + +# MACVLAN - Pseudo Ethernet + +Pseudo-Ethernet or MACVLAN interfaces can be seen as subinterfaces to regular +ethernet interfaces. Each and every subinterface is created a different media +access control (MAC) address, for a single physical Ethernet port. Pseudo- +Ethernet interfaces have most of their application in virtualized environments, + +By using Pseudo-Ethernet interfaces there will be less system overhead compared +to running a traditional bridging approach. Pseudo-Ethernet interfaces can also +be used to workaround the general limit of 4096 virtual LANs (VLANs) per +physical Ethernet port, since that limit is with respect to a single MAC +address. + +Every Virtual Ethernet interfaces behaves like a real Ethernet interface. They +can have IPv4/IPv6 addresses configured, or can request addresses by DHCP/ +DHCPv6 and are associated/mapped with a real ethernet port. This also makes +Pseudo-Ethernet interfaces interesting for testing purposes. A Pseudo-Ethernet +device will inherit characteristics (speed, duplex, ...) from its physical +parent (the so called link) interface. + +Once created in the system, Pseudo-Ethernet interfaces can be referenced in +the exact same way as other Ethernet interfaces. Notes about using Pseudo- +Ethernet interfaces: + +- Pseudo-Ethernet interfaces can not be reached from your internal host. This + means that you can not try to ping a Pseudo-Ethernet interface from the host + system on which it is defined. The ping will be lost. +- Loopbacks occurs at the IP level the same way as for other interfaces, + ethernet frames are not forwarded between Pseudo-Ethernet interfaces. +- Pseudo-Ethernet interfaces may not work in environments which expect a + {abbr}`NIC (Network Interface Card)` to only have a single address. This + applies to: + \- VMware machines using default settings + \- Network switches with security settings allowing only a single MAC address + \- xDSL modems that try to learn the MAC address of the NIC + +## Configuration + +### Common interface configuration + +```{eval-rst} +.. cmdincludemd:: /_include/interface-common-with-dhcp.txt + :var0: pseudo-ethernet + :var1: peth0 +``` + +### Pseudo Ethernet/MACVLAN options + +```{eval-rst} +.. cfgcmd:: set interfaces pseudo-ethernet <interface> source-interface <ethX> + + Specifies the physical `<ethX>` Ethernet interface associated with a Pseudo + Ethernet `<interface>`. +``` + +### VLAN + +```{eval-rst} +.. cmdincludemd:: /_include/interface-vlan-8021q.txt + :var0: pseudo-ethernet + :var1: peth0 +``` diff --git a/docs/configuration/interfaces/md-sstp-client.md b/docs/configuration/interfaces/md-sstp-client.md new file mode 100644 index 00000000..b2c79537 --- /dev/null +++ b/docs/configuration/interfaces/md-sstp-client.md @@ -0,0 +1,173 @@ +--- +lastproofread: '2022-12-11' +--- + +(sstp-client-interface)= + +# SSTP Client + +{abbr}`SSTP (Secure Socket Tunneling Protocol)` is a form of {abbr}`VTP (Virtual +Private Network)` tunnel that provides a mechanism to transport PPP traffic +through an SSL/TLS channel. SSL/TLS provides transport-level security with key +negotiation, encryption and traffic integrity checking. The use of SSL/TLS over +TCP port 443 (by default, port can be changed) allows SSTP to pass through +virtually all firewalls and proxy servers except for authenticated web proxies. + +:::{note} +VyOS also comes with a build in SSTP server, see {ref}`sstp`. +::: + +## Configuration + +### Common interface configuration + +```{eval-rst} +.. cmdincludemd:: /_include/interface-description.txt + :var0: sstpc + :var1: sstpc0 +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-disable.txt + :var0: sstpc + :var1: sstpc0 +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-mtu.txt + :var0: sstpc + :var1: sstpc0 +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-vrf.txt + :var0: sstpc + :var1: sstpc0 +``` + +### SSTP Client Options + +```{eval-rst} +.. cfgcmd:: set interfaces sstpc <interface> no-default-route + + Only request an address from the SSTP server but do not install any default + route. + + Example: + + .. code-block:: none + + set interfaces sstpc sstpc0 no-default-route + + .. note:: This command got added in VyOS 1.4 and inverts the logic from the old + ``default-route`` CLI option. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces sstpc <interface> default-route-distance <distance> + + Set the distance for the default gateway sent by the SSTP server. + + Example: + + .. code-block:: none + + set interfaces sstpc sstpc0 default-route-distance 220 +``` + +```{eval-rst} +.. cfgcmd:: set interfaces sstpc <interface> no-peer-dns + + Use this command to not install advertised DNS nameservers into the local + system. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces sstpc <interface> server <address> + + SSTP remote server to connect to. Can be either an IP address or FQDN. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces sstpc <interface> ip adjust-mss <mss | clamp-mss-to-pmtu> + + 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'. + + .. note:: This command was introduced in VyOS 1.4 - it was previously called: + ``set firewall options interface <name> adjust-mss <value>`` + + .. hint:: MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting in + 1452 bytes on a 1492 byte MTU. + + Instead of a numerical MSS value `clamp-mss-to-pmtu` can be used to + automatically set the proper value. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces sstpc <interface> ip disable-forwarding + + Configure interface-specific Host/Router behaviour. If set, the interface will + switch to host mode and IPv6 forwarding will be disabled on this interface. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces sstpc <interface> ip source-validation <strict | loose | disable> + + Enable policy for source validation by reversed path, as specified in + {rfc}`3704`. Current recommended practice in {rfc}`3704` is to enable strict + mode to prevent IP spoofing from DDos attacks. If using asymmetric routing + or other complicated routing, then loose mode is recommended. + + - strict: Each incoming packet is tested against the FIB and if the interface + is not the best reverse path the packet check will fail. By default failed + packets are discarded. + + - loose: Each incoming packet's source address is also tested against the FIB + and if the source address is not reachable via any interface the packet + check will fail. + + - disable: No source validation +``` + +## Operation + +```{eval-rst} +.. opcmd:: show interfaces sstpc <interface> + + Show detailed information on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces sstpc sstpc10 + sstpc10: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 3 + link/ppp + inet 192.0.2.5 peer 192.0.2.254/32 scope global sstpc10 + valid_lft forever preferred_lft forever + inet6 fe80::fd53:c7ff:fe8b:144f/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 215 9 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 539 14 0 0 0 0 + +``` + +### Connect/Disconnect + +```{eval-rst} +.. opcmd:: disconnect interface <interface> + + Test disconnecting given connection-oriented interface. `<interface>` can be + ``sstpc0`` as the example. +``` + +```{eval-rst} +.. opcmd:: connect interface <interface> + + Test connecting given connection-oriented interface. `<interface>` can be + ``sstpc0`` as the example. +``` diff --git a/docs/configuration/interfaces/md-tunnel.md b/docs/configuration/interfaces/md-tunnel.md new file mode 100644 index 00000000..7f435f8c --- /dev/null +++ b/docs/configuration/interfaces/md-tunnel.md @@ -0,0 +1,281 @@ +--- +lastproofread: '2023-01-26' +--- + +(tunnel-interface)= + +# Tunnel + +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. + +## Common interface configuration + +```{eval-rst} +.. cmdincludemd:: /_include/interface-address.txt + :var0: tunnel + :var1: tun0 +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-common-without-mac.txt + :var0: tunnel + :var1: tun0 +``` + +## IPIP + +This is one of the simplest types of tunnels, as defined by {rfc}`2003`. +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: + +```none +set interfaces tunnel tun0 encapsulation ipip +set interfaces tunnel tun0 source-address 192.0.2.10 +set interfaces tunnel tun0 remote 203.0.113.20 +set interfaces tunnel tun0 address 192.168.100.200/24 +``` + +## 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 :rfc:2473\`. + +It's not likely that anyone will need it any time soon, but it does exist. + +An example: + +```none +set interfaces tunnel tun0 encapsulation ip6ip6 +set interfaces tunnel tun0 source-address 2001:db8:aa::1 +set interfaces tunnel tun0 remote 2001:db8:aa::2 +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: + +```none +set interfaces tunnel tun0 encapsulation ipip6 +set interfaces tunnel tun0 source-address 2001:db8:aa::1 +set interfaces tunnel tun0 remote 2001:db8:aa::2 +set interfaces tunnel tun0 address 192.168.70.80/24 +``` + +## 6in4 (SIT) + +6in4 uses tunneling to encapsulate IPv6 traffic over IPv4 links as defined in +{rfc}`4213`. 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][hurricane electric]. + +An example: + +```none +set interfaces tunnel tun0 encapsulation sit +set interfaces tunnel tun0 source-address 192.0.2.10 +set interfaces tunnel tun0 remote 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 represented by IP +protocol 47. The main benefit of a GRE tunnel is that you are able to carry +multiple protocols inside the same tunnel. GRE also supports multicast traffic +and supports routing protocols that leverage multicast to form neighbor +adjacencies. + +A VyOS GRE tunnel can carry both IPv4 and IPv6 traffic and can also be created +over either IPv4 (gre) or IPv6 (ip6gre). + +### Configuration + +A basic configuration requires a tunnel source (source-address), a tunnel +destination (remote), an encapsulation type (gre), and an address (ipv4/ipv6). +Below is a basic IPv4 only 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:** + +```none +set interfaces tunnel tun100 address '10.0.0.1/30' +set interfaces tunnel tun100 encapsulation 'gre' +set interfaces tunnel tun100 source-address '198.51.100.2' +set interfaces tunnel tun100 remote '203.0.113.10' +``` + +**Cisco IOS Router:** + +```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 +``` + +Here is a second example of a dual-stack tunnel over IPv6 between a VyOS router +and a Linux host using systemd-networkd. + +**VyOS Router:** + +```none +set interfaces tunnel tun101 address '2001:db8:feed:beef::1/126' +set interfaces tunnel tun101 address '192.168.5.1/30' +set interfaces tunnel tun101 encapsulation 'ip6gre' +set interfaces tunnel tun101 source-address '2001:db8:babe:face::3afe:3' +set interfaces tunnel tun101 remote '2001:db8:9bb:3ce::5' +``` + +**Linux systemd-networkd:** + +This requires two files, one to create the device (XXX.netdev) and one +to configure the network on the device (XXX.network) + +```none +# cat /etc/systemd/network/gre-example.netdev +[NetDev] +Name=gre-example +Kind=ip6gre +MTUBytes=14180 + +[Tunnel] +Remote=2001:db8:babe:face::3afe:3 + + +# cat /etc/systemd/network/gre-example.network +[Match] +Name=gre-example + +[Network] +Address=2001:db8:feed:beef::2/126 + +[Address] +Address=192.168.5.2/30 +``` + +### 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: + +```none +set interfaces tunnel tun0 source-address 192.0.2.10 +set interfaces tunnel tun0 remote 192.0.2.20 +set interfaces tunnel tun0 address 10.40.50.60/24 +set interfaces tunnel tun0 parameters ip key 10 +``` + +```none +set interfaces tunnel tun0 source-address 192.0.2.10 +set interfaces tunnel tun0 remote 192.0.2.20 +set interfaces tunnel tun0 address 172.16.17.18/24 +set interfaces tunnel tun0 parameters ip key 20 +``` + +### GRETAP + +While normal GRE is for layer 3, GRETAP is for layer 2. GRETAP can encapsulate +Ethernet frames, thus it can be bridged with other interfaces to create +datalink layer segments that span multiple remote sites. + +```none +set interfaces bridge br0 member interface eth0 +set interfaces bridge br0 member interface tun0 +set interfaces tunnel tun0 encapsulation gretap +set interfaces tunnel tun0 source-address 198.51.100.2 +set interfaces tunnel tun0 remote 203.0.113.10 +``` + +### 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/destination traffic. + +**1. Confirm IP connectivity between tunnel source-address and remote:** + +```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:** + +```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:** + +```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 +``` + +:::{note} +There is also a GRE over IPv6 encapsulation available, it is +called: `ip6gre`. +::: + +[hurricane electric]: https://tunnelbroker.net/ +[other proposals]: https://www.isc.org/othersoftware/ diff --git a/docs/configuration/interfaces/md-virtual-ethernet.md b/docs/configuration/interfaces/md-virtual-ethernet.md new file mode 100644 index 00000000..13d3fb8f --- /dev/null +++ b/docs/configuration/interfaces/md-virtual-ethernet.md @@ -0,0 +1,118 @@ +--- +lastproofread: '2022-11-25' +--- + +(virtual-ethernet)= + +# Virtual Ethernet + +The veth devices are virtual Ethernet devices. They can act as tunnels between +network namespaces to create a bridge to a physical network device in another +namespace or VRF, but can also be used as standalone network devices. + +:::{note} +veth interfaces need to be created in pairs - it's called the peer name +::: + +## Configuration + +### Common interface configuration + +```{eval-rst} +.. cmdincludemd:: /_include/interface-address-with-dhcp.txt + :var0: virtual-ethernet + :var1: veth0 +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-description.txt + :var0: virtual-ethernet + :var1: veth0 +``` + +### VLAN + +#### Regular VLANs (802.1q) + +```{eval-rst} +.. cmdincludemd:: /_include/interface-vlan-8021q.txt + :var0: virtual-ethernet + :var1: veth0 +``` + +#### QinQ (802.1ad) + +```{eval-rst} +.. cmdincludemd:: /_include/interface-vlan-8021ad.txt + :var0: virtual-ethernet + :var1: veth0 +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-disable.txt + :var0: virtual-ethernet + :var1: veth0 +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-vrf.txt + :var0: virtual-ethernet + :var1: veth0 +``` + +## Operation + +```{eval-rst} +.. opcmd:: show interfaces virtual-ethernet + + Show brief interface information. + + .. code-block:: none + + vyos@vyos:~$ show interfaces virtual-ethernet + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + veth10 100.64.0.0/31 u/u + veth11 100.64.0.1/31 u/u +``` + +```{eval-rst} +.. opcmd:: show interfaces virtual-ethernet <interface> + + Show detailed information on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces virtual-ethernet veth11 + 10: veth11@veth10: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue master red state UP group default qlen 1000 + link/ether b2:7b:df:47:e9:11 brd ff:ff:ff:ff:ff:ff + inet 100.64.0.1/31 scope global veth11 + valid_lft forever preferred_lft forever + inet6 fe80::b07b:dfff:fe47:e911/64 scope link + valid_lft forever preferred_lft forever + + + RX: bytes packets errors dropped overrun mcast + 0 0 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 1369707 4267 0 0 0 0 +``` + +## Example + +Interconnect the global VRF with vrf "red" using the veth10 \<-> veth 11 pair + +```none +set interfaces virtual-ethernet veth10 address '100.64.0.0/31' +set interfaces virtual-ethernet veth10 peer-name 'veth11' +set interfaces virtual-ethernet veth11 address '100.64.0.1/31' +set interfaces virtual-ethernet veth11 peer-name 'veth10' +set interfaces virtual-ethernet veth11 vrf 'red' +set vrf name red table '1000' + +vyos@vyos:~$ ping 100.64.0.1 +PING 100.64.0.1 (100.64.0.1) 56(84) bytes of data. +64 bytes from 100.64.0.1: icmp_seq=1 ttl=64 time=0.080 ms +64 bytes from 100.64.0.1: icmp_seq=2 ttl=64 time=0.119 ms +``` diff --git a/docs/configuration/interfaces/md-vti.md b/docs/configuration/interfaces/md-vti.md new file mode 100644 index 00000000..f516014d --- /dev/null +++ b/docs/configuration/interfaces/md-vti.md @@ -0,0 +1,40 @@ +(vti-interface)= + +# VTI - Virtual Tunnel Interface + +Set Virtual Tunnel Interface + +```none +set interfaces vti vti0 address 192.168.2.249/30 +set interfaces vti vti0 address 2001:db8:2::249/64 +``` + +Results in: + +```none +vyos@vyos# show interfaces vti +vti vti0 { + address 192.168.2.249/30 + address 2001:db8:2::249/64 + description "Description" +} +``` + +:::{warning} +When using site-to-site IPsec with VTI interfaces, +be sure to disable route autoinstall +::: + +```none +set vpn ipsec options disable-route-autoinstall +``` + +More details about the IPsec and VTI issue and option disable-route-autoinstall +<https://blog.vyos.io/vyos-1-dot-2-0-development-news-in-july> + +The root cause of the problem is that for VTI tunnels to work, their traffic +selectors have to be set to 0.0.0.0/0 for traffic to match the tunnel, even +though actual routing decision is made according to netfilter marks. Unless +route insertion is disabled entirely, StrongSWAN thus mistakenly inserts a +default route through the VTI peer address, which makes all traffic routed +to nowhere. diff --git a/docs/configuration/interfaces/md-vxlan.md b/docs/configuration/interfaces/md-vxlan.md new file mode 100644 index 00000000..0eff152c --- /dev/null +++ b/docs/configuration/interfaces/md-vxlan.md @@ -0,0 +1,366 @@ +--- +lastproofread: '2023-01-26' +--- + +(vxlan-interface)= + +# VXLAN + +{abbr}`VXLAN (Virtual Extensible LAN)` is a network virtualization technology +that attempts to address the scalability problems associated with large cloud +computing deployments. It uses a VLAN-like encapsulation technique to +encapsulate OSI layer 2 Ethernet frames within layer 4 UDP datagrams, using +4789 as the default IANA-assigned destination UDP port number. VXLAN +endpoints, which terminate VXLAN tunnels and may be either virtual or physical +switch ports, are known as {abbr}`VTEPs (VXLAN tunnel endpoints)`. + +VXLAN is an evolution of efforts to standardize an overlay encapsulation +protocol. It increases the scalability up to 16 million logical networks and +allows for layer 2 adjacency across IP networks. Multicast or unicast with +head-end replication (HER) is used to flood broadcast, unknown unicast, +and multicast (BUM) traffic. + +The VXLAN specification was originally created by VMware, Arista Networks +and Cisco. Other backers of the VXLAN technology include Huawei, Broadcom, +Citrix, Pica8, Big Switch Networks, Cumulus Networks, Dell EMC, Ericsson, +Mellanox, FreeBSD, OpenBSD, Red Hat, Joyent, and Juniper Networks. + +VXLAN was officially documented by the IETF in {rfc}`7348`. + +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. + +## Configuration + +### Common interface configuration + +```{eval-rst} +.. cmdincludemd:: /_include/interface-common-without-dhcp.txt + :var0: vxlan + :var1: vxlan0 +``` + +### VXLAN specific options + +```{eval-rst} +.. cfgcmd:: set interfaces vxlan <interface> vni <number> + + Each VXLAN segment is identified through a 24-bit segment ID, termed the + {abbr}`VNI (VXLAN Network Identifier (or VXLAN Segment ID))`, This allows + up to 16M VXLAN segments to coexist within the same administrative domain. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces vxlan <interface> port <port> + + Configure port number of remote VXLAN endpoint. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces vxlan <interface> source-address <IP address> + + Source IP address used for VXLAN underlay. This is mandatory when using VXLAN + via L2VPN/EVPN. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces vxlan <interface> gpe + + Enables the Generic Protocol extension (VXLAN-GPE). Currently, this is only + supported together with the external keyword. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces vxlan <interface> parameters external + + Specifies whether an external control plane (e.g. BGP L2VPN/EVPN) or the + internal FDB should be used. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces vxlan <interface> parameters neighbor-suppress + + In order to minimize the flooding of ARP and ND messages in the VXLAN network, + EVPN includes provisions {rfc}`7432#section-10` that allow participating VTEPs + to suppress such messages in case they know the MAC-IP binding and can reply + on behalf of the remote host. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces vxlan <interface> parameters nolearning + + Specifies if unknown source link layer addresses and IP addresses are entered + into the VXLAN device forwarding database. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces vxlan <interface> parameters vni-filter + + Specifies whether the VXLAN device is capable of vni filtering. + + Only works with a VXLAN device with external flag set. + + .. note:: The device can only receive packets with VNIs configured in + the VNI filtering table. +``` + +#### Unicast + +```{eval-rst} +.. cfgcmd:: set interfaces vxlan <interface> remote <address> + + IPv4/IPv6 remote address of the VXLAN tunnel. Alternative to multicast, the + remote IPv4/IPv6 address can set directly. +``` + +#### Multicast + +```{eval-rst} +.. cfgcmd:: set interfaces vxlan <interface> source-interface <interface> + + Interface used for VXLAN underlay. This is mandatory when using VXLAN via + a multicast network. VXLAN traffic will always enter and exit this interface. + +``` + +```{eval-rst} +.. cfgcmd:: set interfaces vxlan <interface> group <address> + + Multicast group address for VXLAN interface. VXLAN tunnels can be built + either via Multicast or via Unicast. + + Both IPv4 and IPv6 multicast is possible. +``` + +## Multicast VXLAN + +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 leaves 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 leaves 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 leaves are +added. + +For optimal scalability, Multicast shouldn't be used at all, but instead use BGP +to signal all connected devices between leaves. Unfortunately, VyOS does not yet +support this. + +## Single VXLAN device (SVD) + +FRR supports a new way of configuring VLAN-to-VNI mappings for EVPN-VXLAN, when +working with the Linux kernel. In this new way, the mapping of a VLAN to a +{abbr}`VNI (VXLAN Network Identifier (or VXLAN Segment ID))` is configured +against a container VXLAN interface which is referred to as a +{abbr}`SVD (Single VXLAN device)`. + +Multiple VLAN to VNI mappings can be configured against the same SVD. This +allows for a significant scaling of the number of VNIs since a separate VXLAN +interface is no longer required for each VNI. + +```{eval-rst} +.. cfgcmd:: set interfaces vxlan <interface> vlan-to-vni <vlan> vni <vni> + + Maps the VNI to the specified VLAN id. The VLAN can then be consumed by + a bridge. + + Sample configuration of SVD with VLAN to VNI mappings is shown below. + + .. code-block:: none + + set interfaces bridge br0 member interface vxlan0 + set interfaces vxlan vxlan0 parameters external + set interfaces vxlan vxlan0 source-interface 'dum0' + set interfaces vxlan vxlan0 vlan-to-vni 10 vni '10010' + set interfaces vxlan vxlan0 vlan-to-vni 11 vni '10011' + set interfaces vxlan vxlan0 vlan-to-vni 30 vni '10030' + set interfaces vxlan vxlan0 vlan-to-vni 31 vni '10031' +``` + +### 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: + +```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:** + +```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 leaves to forward traffic between each +other in a more scalable way. This also requires PIM to be enabled towards the +leaves so that the Spine can learn what multicast groups each Leaf expects +traffic from. + +**Leaf2 configuration:** + +```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 bridge br241 member interface 'eth1.241' +set interfaces bridge br241 member interface 'vxlan241' + +set interfaces vxlan vxlan241 group '239.0.0.241' +set interfaces vxlan vxlan241 source-interface 'eth0' +set interfaces vxlan vxlan241 vni '241' + +! Our seconds vxlan interface +set interfaces bridge br242 address '172.16.242.1/24' +set interfaces bridge br242 member interface 'eth1.242' +set interfaces bridge br242 member interface 'vxlan242' + +set interfaces vxlan vxlan242 group '239.0.0.242' +set interfaces vxlan vxlan242 source-interface 'eth0' +set interfaces vxlan vxlan242 vni '242' +``` + +**Leaf3 configuration:** + +```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 bridge br241 member interface 'eth1.241' +set interfaces bridge br241 member interface 'vxlan241' + +set interfaces vxlan vxlan241 group '239.0.0.241' +set interfaces vxlan vxlan241 source-interface 'eth0' +set interfaces vxlan vxlan241 vni '241' + +! Our seconds vxlan interface +set interfaces bridge br242 address '172.16.242.1/24' +set interfaces bridge br242 member interface 'eth1.242' +set interfaces bridge br242 member interface 'vxlan242' + +set interfaces vxlan vxlan242 group '239.0.0.242' +set interfaces vxlan vxlan242 source-interface '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: + +```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. + +```none +set interfaces bridge br241 member interface 'eth1.241' +set interfaces bridge br241 member interface 'vxlan241' +``` + +Binds eth1.241 and vxlan241 to each other by making them both member +interfaces of the same bridge. + +```none +set interfaces vxlan vxlan241 group '239.0.0.241' +``` + +The multicast-group used by all leaves for this vlan extension. Has to be the +same on all leaves that has this interface. + +```none +set interfaces vxlan vxlan241 source-interface 'eth0' +``` + +Sets the interface to listen for multicast packets on. Could be a loopback, not +yet tested. + +```none +set interfaces vxlan vxlan241 vni '241' +``` + +Sets the unique id for this vxlan-interface. Not sure how it correlates with +multicast-address. + +```none +set interfaces vxlan vxlan241 port 12345 +``` + +The destination port used for creating a VXLAN interface defaults to +4789\. Aconfiguration directive to support a user-specified destination port +to override that behavior is available using the above command. + +## Unicast VXLAN + +Alternative to multicast, the remote IPv4 address of the VXLAN tunnel can be +set directly. Let's change the Multicast example from above: + +```none +# leaf2 and leaf3 +delete interfaces vxlan vxlan241 group '239.0.0.241' +delete interfaces vxlan vxlan241 source-interface '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 4789. +It can be changed with `set interface vxlan <vxlanN> port <port>` diff --git a/docs/configuration/interfaces/md-wireguard.md b/docs/configuration/interfaces/md-wireguard.md new file mode 100644 index 00000000..3f69a7fe --- /dev/null +++ b/docs/configuration/interfaces/md-wireguard.md @@ -0,0 +1,434 @@ +--- +lastproofread: '2023-01-26' +--- + +(wireguard)= + +# WireGuard + +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. + +## Site to Site VPN + +This diagram corresponds with the example site to site configuration below. + +:::{figure} /_static/images/wireguard_site2site_diagram.jpg +::: + +## Keypairs + +WireGuard requires the generation of a keypair, which includes a private key to +decrypt incoming traffic, and a public key for peer(s) to encrypt traffic. + +### Generate Keypair + +```{eval-rst} +.. opcmd:: generate pki wireguard key-pair + + It generates the keypair, which includes the public and private parts. + The key is not stored on the system - only a keypair is generated. + + .. code-block:: none + + vyos@vyos:~$ generate pki wireguard key-pair + Private key: iJJyEARGK52Ls1GYRCcFvPuTj7WyWYDo//BknoDU0XY= + Public key: EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw= +``` + +```{eval-rst} +.. opcmd:: generate pki wireguard key-pair install interface <interface> + + Generates a keypair, which includes the public and private parts, and build + a configuration command to install this key to ``interface``. + + .. code-block:: none + + vyos@vyos:~$ generate pki wireguard key-pair install interface wg10 + "generate" CLI command executed from operational level. + Generated private-key is not stored to CLI, use configure mode commands to install key: + + set interfaces wireguard wg10 private-key '4Krkv8h6NkAYMMaBWI957yYDJDMvj9URTHstdlOcDU0=' + + Corresponding public-key to use on peer system is: 'UxDsYT6EnpTIOKUzvMlw2p0sNOKQvFxEdSVrnNrX1Ro=' + + .. note:: If this command is invoked from configure mode with the ``run`` + prefix the key is automatically installed to the appropriate interface: + + .. code-block:: none + + vyos@vyos# run generate pki wireguard key-pair install interface wg10 + "generate" CLI command executed from config session. + Generated private-key was imported to CLI! + + Use the following command to verify: show interfaces wireguard wg10 + Corresponding public-key to use on peer system is: '7d9KwabjLhHpJiEJeIGd0CBlao/eTwFOh6xyCovTfG8=' + + vyos@vyos# compare + [edit interfaces] + +wireguard wg10 { + + private-key CJweb8FC6BU3Loj4PC2pn5V82cDjIPs7G1saW0ZfLWc= + +} +``` + +```{eval-rst} +.. opcmd:: show interfaces wireguard <interface> public-key + + Retrieve public key portion from configured WIreGuard interface. + + .. code-block:: none + + vyos@vyos:~$ show interfaces wireguard wg01 public-key + EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw= + +``` + +#### Optional + +```{eval-rst} +.. opcmd:: generate pki wireguard preshared-key + + An additional layer of symmetric-key crypto can be used on top of the + asymmetric crypto. + + This is optional. + + .. code-block:: none + + vyos@vyos:~$ generate pki wireguard preshared-key + Pre-shared key: OHH2EwZfMNK+1L6BXbYw3bKCtMrfjpR4mCAEeBlFnRs= + +``` + +```{eval-rst} +.. opcmd:: generate pki wireguard preshared-key install interface <interface> peer <peer> + + An additional layer of symmetric-key crypto can be used on top of the + asymmetric crypto. This command automatically creates for you the required + CLI command to install this PSK for a given peer. + + This is optional. + + .. code-block:: none + + vyos@vyos:~$ generate pki wireguard preshared-key install interface wg10 peer foo + "generate" CLI command executed from operational level. + Generated preshared-key is not stored to CLI, use configure mode commands to install key: + + set interfaces wireguard wg10 peer foo preshared-key '32vQ1w1yFKTna8n7Gu7EimubSe2Y63m8bafz55EG3Ro=' + + Pre-shared key: +LuaZ8W6DjsDFJFX3jJzoNqrsXHhvq08JztM9z8LHCs= + + + .. note:: If this command is invoked from configure mode with the ``run`` + prefix the key is automatically installed to the appropriate interface: + +``` + +## 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 address/port is optional; however, if you act like a server and +endpoints initiate the connections to your system, you need to define a port +your clients can connect to, otherwise the port is randomly chosen and may +make connection difficult with firewall rules, since the port may be different +each time the system is rebooted. + +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 - commands** + +- WireGuard interface itself uses address 10.1.0.1/30 +- We only allow the 192.168.2.0/24 subnet to travel over the tunnel +- Our remote end of the tunnel for peer `to-wg02` is reachable at 192.0.2.1 + port 51820 +- The remote peer `to-wg02` uses XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI= + as its public key portion +- We listen on port 51820 +- We route all traffic for the 192.168.2.0/24 network to interface `wg01` + +```none +set interfaces wireguard wg01 address '10.1.0.1/30' +set interfaces wireguard wg01 description 'VPN-to-wg02' +set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.2.0/24' +set interfaces wireguard wg01 peer to-wg02 address '192.0.2.1' +set interfaces wireguard wg01 peer to-wg02 port '51820' +set interfaces wireguard wg01 peer to-wg02 public-key 'XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI=' +set interfaces wireguard wg01 port '51820' + +set protocols static route 192.168.2.0/24 interface wg01 +``` + +The last step is to define an interface route for 192.168.2.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. + +:::{warning} +You can not assign the same allowed-ips statement to multiple +WireGuard peers. This a design decision. For more information please +check the [WireGuard mailing list]. +::: + +```{eval-rst} +.. cfgcmd:: set interfaces wireguard <interface> private-key <private-key> + + Associates the previously generated private key to a specific WireGuard + interface. The private key can be generate via the command + + {opcmd}`generate pki wireguard key-pair`. + + .. code-block:: none + + set interfaces wireguard wg01 private-key 'iJJyEARGK52Ls1GYRCcFvPuTj7WyWYDo//BknoDU0XY=' + + The command {opcmd}`show interfaces wireguard wg01 public-key` will then show the + public key, which needs to be shared with the peer. +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-per-client-thread.txt + :var0: wireguard + :var1: wg01 +``` + +**remote side - commands** + +```none +set interfaces wireguard wg01 address '10.1.0.2/30' +set interfaces wireguard wg01 description 'VPN-to-wg01' +set interfaces wireguard wg01 peer to-wg01 allowed-ips '192.168.1.0/24' +set interfaces wireguard wg01 peer to-wg01 address '192.0.2.2' +set interfaces wireguard wg01 peer to-wg01 port '51820' +set interfaces wireguard wg01 peer to-wg01 public-key 'EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw=' +set interfaces wireguard wg01 port '51820' +set interfaces wireguard wg01 private-key 'OLTQY3HuK5qWDgVs6fJR093SwPgOmCKkDI1+vJLGoFU=' + +set protocols static route 192.168.1.0/24 interface wg01 +``` + +## Firewall Exceptions + +For the WireGuard traffic to pass through the WAN interface, you must create a +firewall exception. + +```none +set firewall ipv4 name OUTSIDE_LOCAL rule 10 action accept +set firewall ipv4 name OUTSIDE_LOCAL rule 10 description 'Allow established/related' +set firewall ipv4 name OUTSIDE_LOCAL rule 10 state established enable +set firewall ipv4 name OUTSIDE_LOCAL rule 10 state related enable +set firewall ipv4 name OUTSIDE_LOCAL rule 20 action accept +set firewall ipv4 name OUTSIDE_LOCAL rule 20 description WireGuard_IN +set firewall ipv4 name OUTSIDE_LOCAL rule 20 destination port 51820 +set firewall ipv4 name OUTSIDE_LOCAL rule 20 log enable +set firewall ipv4 name OUTSIDE_LOCAL rule 20 protocol udp +``` + +You should also ensure that the OUTISDE_LOCAL firewall group is applied to the +WAN interface and in an input (local) direction. + +```none +set firewall ipv4 input filter rule 10 action jump +set firewall ipv4 input filter rule 10 jump-target 'OUTSIDE_LOCAL' +set firewall ipv4 input filter rule 10 inbound-interface name 'eth0' +``` + +Assure that your firewall rules allow the traffic, in which case you have a +working VPN using WireGuard. + +```none +wg01# ping 192.168.1.1 +PING 192.168.1.1 (192.168.1.1) 56(84) bytes of data. +64 bytes from 192.168.1.1: icmp_seq=1 ttl=64 time=1.16 ms +64 bytes from 192.168.1.1: icmp_seq=2 ttl=64 time=1.77 ms + +wg02# ping 192.168.2.1 +PING 192.168.2.1 (192.168.2.1) 56(84) bytes of data. +64 bytes from 192.168.2.1: icmp_seq=1 ttl=64 time=4.40 ms +64 bytes from 192.168.2.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. This is optional. + +```none +vyos@vyos:~$ generate pki wireguard preshared-key +Pre-shared key: rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc= +``` + +Copy the key, as it is not stored on the local filesystem. Because it +is a symmetric key, only you and your peer should have knowledge of +its content. Make sure you distribute the key in a safe manner, + +```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=' +``` + +## Remote Access "RoadWarrior" Example + +With WireGuard, a Road Warrior VPN config is similar to a site-to-site +VPN. It just lacks the `address` and `port` statements. + +In the following example, the IPs for the remote clients are defined in +the peers. This allows the peers to interact with one another. In +comparison to the site-to-site example the `persistent-keepalive` +flag is set to 15 seconds to assure the connection is kept alive. +This is mainly relevant if one of the peers is behind NAT and can't +be connected to if the connection is lost. To be effective this +value needs to be lower than the UDP timeout. + +```none +wireguard wg01 { + address 10.172.24.1/24 + address 2001:db8:470:22::1/64 + description RoadWarrior + peer MacBook { + allowed-ips 10.172.24.30/32 + allowed-ips 2001:db8:470:22::30/128 + persistent-keepalive 15 + public-key F5MbW7ye7DsoxdOaixjdrudshjjxN5UdNV+pGFHqehc= + } + peer iPhone { + allowed-ips 10.172.24.20/32 + allowed-ips 2001:db8:470:22::20/128 + persistent-keepalive 15 + public-key BknHcLFo8nOo8Dwq2CjaC/TedchKQ0ebxC7GYn7Al00= + } + port 2224 + private-key OLTQY3HuK5qWDgVs6fJR093SwPgOmCKkDI1+vJLGoFU= +} +``` + +The following is the config for the iPhone peer above. It's important to +note that the `AllowedIPs` wildcard setting directs all IPv4 and IPv6 traffic +through the connection. + +```none +[Interface] +PrivateKey = ARAKLSDJsadlkfjasdfiowqeruriowqeuasdf= +Address = 10.172.24.20/24, 2001:db8:470:22::20/64 +DNS = 10.0.0.53, 10.0.0.54 + +[Peer] +PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc= +AllowedIPs = 0.0.0.0/0, ::/0 +Endpoint = 192.0.2.1:2224 +PersistentKeepalive = 25 +``` + +However, split-tunneling can be achieved by specifying the remote subnets. +This ensures that only traffic destined for the remote site is sent over the +tunnel. All other traffic is unaffected. + +```none +[Interface] +PrivateKey = 8Iasdfweirousd1EVGUk5XsT+wYFZ9mhPnQhmjzaJE6Go= +Address = 10.172.24.30/24, 2001:db8:470:22::30/64 + +[Peer] +PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc= +AllowedIPs = 10.172.24.30/24, 2001:db8:470:22::/64 +Endpoint = 192.0.2.1:2224 +PersistentKeepalive = 25 +``` + +## Operational Commands + +### Status + +```{eval-rst} +.. opcmd:: show interfaces wireguard wg01 summary + + Show info about the Wireguard service. + It also shows the latest handshake. + + .. code-block:: none + + vyos@vyos:~$ show interfaces wireguard wg01 summary + interface: wg01 + public key: + private key: (hidden) + listening port: 51820 + + peer: <peer public-key> + endpoint: <peer public IP> + allowed ips: 10.69.69.2/32 + latest handshake: 23 hours, 45 minutes, 26 seconds ago + transfer: 1.26 MiB received, 6.47 MiB sent +``` + +```{eval-rst} +.. opcmd:: show interfaces wireguard + + Get a list of all wireguard interfaces + + .. code-block:: none + + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + wg01 10.0.0.1/24 u/u + +``` + +```{eval-rst} +.. opcmd:: show interfaces wireguard <interface> + + Show general information about specific WireGuard interface + + .. code-block:: none + + vyos@vyos:~$ show interfaces wireguard wg01 + interface: wg01 + address: 10.0.0.1/24 + public key: h1HkYlSuHdJN6Qv4Hz4bBzjGg5WUty+U1L7DJsZy1iE= + private key: (hidden) + listening port: 41751 + + RX: bytes packets errors dropped overrun mcast + 0 0 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 0 0 0 0 0 0 +``` + +## Remote Access "RoadWarrior" clients + +Some users tend to connect their mobile devices using WireGuard to their VyOS +router. To ease deployment one can generate a "per mobile" configuration from +the VyOS CLI. + +:::{warning} +From a security perspective, it is not recommended to let a third +party create and share the private key for a secured connection. +You should create the private portion on your own and only hand out the +public key. Please keep this in mind when using this convenience feature. +::: + +```{eval-rst} +.. opcmd:: generate wireguard client-config <name> interface <interface> server + <ip|fqdn> address <client-ip> + + Using this command, you will create a new client configuration which can + connect to ``interface`` on this router. The public key from the specified + interface is automatically extracted and embedded into the configuration. + + The command also generates a configuration snipped which can be copy/pasted + into the VyOS CLI if needed. The supplied ``<name>`` on the CLI will become + the peer name in the snippet. + + In addition you will specifiy the IP address or FQDN for the client where it + will connect to. The address parameter can be used up to two times and is used + to assign the clients specific IPv4 (/32) or IPv6 (/128) address. + + .. figure:: /_static/images/wireguard_qrcode.jpg + :alt: WireGuard Client QR code +``` + + + +[wireguard mailing list]: https://lists.zx2c4.com/pipermail/wireguard/2018-December/003704.html diff --git a/docs/configuration/interfaces/md-wireless.md b/docs/configuration/interfaces/md-wireless.md new file mode 100644 index 00000000..c8273737 --- /dev/null +++ b/docs/configuration/interfaces/md-wireless.md @@ -0,0 +1,698 @@ +--- +lastproofread: '2023-01-26' +--- + +(wireless-interface)= + +# WLAN/WIFI - Wireless LAN + +{abbr}`WLAN (Wireless LAN)` interface provide 802.11 (a/b/g/n/ac) wireless +support (commonly referred to as Wi-Fi) by means of compatible hardware. If your +hardware supports it, VyOS supports multiple logical wireless interfaces per +physical device. + +There are three modes of operation for a wireless interface: + +- {abbr}`WAP (Wireless Access-Point)` provides network access to connecting + stations if the physical hardware supports acting as a WAP +- A station acts as a Wi-Fi client accessing the network through an available + WAP +- Monitor, the system passively monitors any kind of wireless traffic + +If the system detects an unconfigured wireless device, it will be automatically +added the configuration tree, specifying any detected settings (for example, +its MAC address) and configured to run in monitor mode. + +## Configuration + +### Common interface configuration + +```{eval-rst} +.. cmdincludemd:: /_include/interface-common-with-dhcp.txt + :var0: wireless + :var1: wlan0 +``` + +### Wireless options + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> channel <number> + + Channel number (IEEE 802.11), for 2.4Ghz (802.11 b/g/n) channels range from + 1-14. On 5Ghz (802.11 a/h/j/n/ac) channels available are 0, 34 to 173 +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> country-code <cc> + + Country code (ISO/IEC 3166-1). Used to set regulatory domain. Set as needed + to indicate country in which device is operating. This can limit available + channels and transmit power. + + .. note:: This option is mandatory in Access-Point mode. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> disable-broadcast-ssid + + Send empty SSID in beacons and ignore probe request frames that do not specify + full SSID, i.e., require stations to know SSID. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> expunge-failing-stations + + Disassociate stations based on excessive transmission failures or other + indications of connection loss. + + This depends on the driver capabilities and may not be available with all + drivers. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> isolate-stations + + Client isolation can be used to prevent low-level bridging of frames between + associated stations in the BSS. + + By default, this bridging is allowed. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> max-stations + + Maximum number of stations allowed in station table. New stations will be + rejected after the station table is full. IEEE 802.11 has a limit of 2007 + different association IDs, so this number should not be larger than that. + + This defaults to 2007. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> mgmt-frame-protection + + Management Frame Protection (MFP) according to IEEE 802.11w +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> mode <a | b | g | n | ac> + + Operation mode of wireless radio. + + * ``a`` - 802.11a - 54 Mbits/sec + * ``b`` - 802.11b - 11 Mbits/sec + * ``g`` - 802.11g - 54 Mbits/sec (default) + * ``n`` - 802.11n - 600 Mbits/sec + * ``ac`` - 802.11ac - 1300 Mbits/sec +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> physical-device <device> + + Wireless hardware device used as underlay radio. + + This defaults to phy0. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> reduce-transmit-power <number> + + Add Power Constraint element to Beacon and Probe Response frames. + + This option adds Power Constraint element when applicable and Country element + is added. Power Constraint element is required by Transmit Power Control. + + Valid values are 0..255. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> ssid <ssid> + + SSID to be used in IEEE 802.11 management frames +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> type + <access-point | station | monitor> + + Wireless device type for this interface + + * ``access-point`` - Access-point forwards packets between other nodes + * ``station`` - Connects to another access point + * ``monitor`` - Passively monitor all packets on the frequency/channel +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-per-client-thread.txt + :var0: wireless + :var1: wlan0 +``` + +#### PPDU + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities require-ht +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities require-hvt +``` + +##### HT (High Throughput) capabilities (802.11n) + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities ht 40mhz-incapable + + Device is incapable of 40 MHz, do not advertise. This sets ``[40-INTOLERANT]`` +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities ht auto-powersave + + WMM-PS Unscheduled Automatic Power Save Delivery [U-APSD] +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities ht + channel-set-width <ht20 | ht40+ | ht40-> + + Supported channel width set. + + * ``ht40-`` - Both 20 MHz and 40 MHz with secondary channel below the primary + channel + * ``ht40+`` - Both 20 MHz and 40 MHz with secondary channel above the primary + channel + + .. note:: There are limits on which channels can be used with HT40- and HT40+. + Following table shows the channels that may be available for HT40- and HT40+ + use per IEEE 802.11n Annex J: + + Depending on the location, not all of these channels may be available for + use! + + .. code-block:: none + + freq HT40- HT40+ + 2.4 GHz 5-13 1-7 (1-9 in Europe/Japan) + 5 GHz 40,48,56,64 36,44,52,60 + + .. note:: 40 MHz channels may switch their primary and secondary channels if + needed or creation of 40 MHz channel maybe rejected based on overlapping + BSSes. These changes are done automatically when hostapd is setting up the + 40 MHz channel. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities ht + delayed-block-ack + + Enable HT-delayed Block Ack ``[DELAYED-BA]`` +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities ht dsss-cck-40 + + DSSS/CCK Mode in 40 MHz, this sets ``[DSSS_CCK-40]`` +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities ht greenfield + + This enables the greenfield option which sets the ``[GF]`` option +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities ht ldpc + + Enable LDPC coding capability +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities ht lsig-protection + + Enable L-SIG TXOP protection capability +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities ht max-amsdu + <3839 | 7935> + + Maximum A-MSDU length 3839 (default) or 7935 octets +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities ht + short-gi <20 | 40> + + Short GI capabilities for 20 and 40 MHz +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities ht + smps <static | dynamic> + + Spatial Multiplexing Power Save (SMPS) settings +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities ht stbc rx <num> + + Enable receiving PPDU using STBC (Space Time Block Coding) +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities ht stbc tx + + Enable sending PPDU using STBC (Space Time Block Coding) +``` + +##### VHT (Very High Throughput) capabilities (802.11ac) + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities vht antenna-count + + Number of antennas on this card +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities vht + antenna-pattern-fixed + + Set if antenna pattern does not change during the lifetime of an association +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities vht beamform + <single-user-beamformer | single-user-beamformee | multi-user-beamformer | + multi-user-beamformee> + + Beamforming capabilities: + + * ``single-user-beamformer`` - Support for operation as single user beamformer + * ``single-user-beamformee`` - Support for operation as single user beamformee + * ``multi-user-beamformer`` - Support for operation as single user beamformer + * ``multi-user-beamformee`` - Support for operation as single user beamformer +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities vht + center-channel-freq <freq-1 | freq-2> <number> + + VHT operating channel center frequency - center freq 1 + (for use with 80, 80+80 and 160 modes) + + VHT operating channel center frequency - center freq 2 + (for use with the 80+80 mode) + + <number> must be from 34 - 173. For 80 MHz channels it should be channel + 6. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities vht + channel-set-width <0 | 1 | 2 | 3> + + * ``0`` - 20 or 40 MHz channel width (default) + * ``1`` - 80 MHz channel width + * ``2`` - 160 MHz channel width + * ``3`` - 80+80 MHz channel width +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities vht ldpc + + Enable LDPC (Low Density Parity Check) coding capability +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities vht link-adaptation + + VHT link adaptation capabilities +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities vht + max-mpdu <value> + + Increase Maximum MPDU length to 7991 or 11454 octets (default 3895 octets) +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities vht + max-mpdu-exp <value> + + Set the maximum length of A-MPDU pre-EOF padding that the station can receive +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities vht + short-gi <80 | 160> + + Short GI capabilities +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities vht stbc rx <num> + + Enable receiving PPDU using STBC (Space Time Block Coding) +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities vht stbc tx + + Enable sending PPDU using STBC (Space Time Block Coding) +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities vht tx-powersave + + Enable VHT TXOP Power Save Mode +``` + +```{eval-rst} +.. cfgcmd:: set interfaces wireless <interface> capabilities vht vht-cf + + Station supports receiving VHT variant HT Control field +``` + +### Wireless options (Station/Client) + +The example creates a wireless station (commonly referred to as Wi-Fi client) +that accesses the network through the WAP defined in the above example. The +default physical device (`phy0`) is used. + +```none +set interfaces wireless wlan0 type station +set interfaces wireless wlan0 address dhcp +set interfaces wireless wlan0 country-code de +set interfaces wireless wlan0 ssid Test +set interfaces wireless wlan0 security wpa passphrase '12345678' +``` + +Resulting in + +```none +interfaces { + [...] + wireless wlan0 { + address dhcp + country-code de + security { + wpa { + passphrase "12345678" + } + } + ssid TEST + type station + } +``` + +### Security + +{abbr}`WPA (Wi-Fi Protected Access)` and WPA2 Enterprise in combination with +802.1x based authentication can be used to authenticate users or computers +in a domain. + +The wireless client (supplicant) authenticates against the RADIUS server +(authentication server) using an {abbr}`EAP (Extensible Authentication +Protocol)` method configured on the RADIUS server. The WAP (also referred +to as authenticator) role is to send all authentication messages between the +supplicant and the configured authentication server, thus the RADIUS server +is responsible for authenticating the users. + +The WAP in this example has the following characteristics: + +- IP address `192.168.2.1/24` +- Network ID (SSID) `Enterprise-TEST` +- WPA passphrase `12345678` +- Use 802.11n protocol +- Wireless channel `1` +- RADIUS server at `192.168.3.10` with shared-secret `VyOSPassword` + +```none +set interfaces wireless wlan0 address '192.168.2.1/24' +set interfaces wireless wlan0 country-code de +set interfaces wireless wlan0 type access-point +set interfaces wireless wlan0 channel 1 +set interfaces wireless wlan0 mode n +set interfaces wireless wlan0 ssid 'TEST' +set interfaces wireless wlan0 security wpa mode wpa2 +set interfaces wireless wlan0 security wpa cipher CCMP +set interfaces wireless wlan0 security wpa radius server 192.168.3.10 key 'VyOSPassword' +set interfaces wireless wlan0 security wpa radius server 192.168.3.10 port 1812 +``` + +Resulting in + +```none +interfaces { + [...] + wireless wlan0 { + address 192.168.2.1/24 + country-code de + channel 1 + mode n + security { + wpa { + cipher CCMP + mode wpa2 + radius { + server 192.168.3.10 { + key 'VyOSPassword' + port 1812 + } + } + } + } + ssid "Enterprise-TEST" + type access-point + } +} +``` + +### VLAN + +#### Regular VLANs (802.1q) + +```{eval-rst} +.. cmdincludemd:: /_include/interface-vlan-8021q.txt + :var0: wireless + :var1: wlan0 +``` + +#### QinQ (802.1ad) + +```{eval-rst} +.. cmdincludemd:: /_include/interface-vlan-8021ad.txt + :var0: wireless + :var1: wlan0 +``` + +## Operation + +```{eval-rst} +.. opcmd:: show interfaces wireless info +``` + +Use this command to view operational status and wireless-specific information +about all wireless interfaces. + +```none +vyos@vyos:~$ show interfaces wireless info +Interface Type SSID Channel +wlan0 access-point VyOS-TEST-0 1 +``` + +```{eval-rst} +.. opcmd:: show interfaces wireless detail +``` + +Use this command to view operational status and details wireless-specific +information about all wireless interfaces. + +```none +vyos@vyos:~$ show interfaces wireless detail +wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 + link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff + inet xxx.xxx.99.254/24 scope global wlan0 + valid_lft forever preferred_lft forever + inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 66072 282 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 83413 430 0 0 0 0 + +wlan1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 + link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff + inet xxx.xxx.100.254/24 scope global wlan0 + valid_lft forever preferred_lft forever + inet6 fe80::xxxx:xxxx:ffff:2ed3/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 166072 5282 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 183413 5430 0 0 0 0 +``` + +```{eval-rst} +.. opcmd:: show interfaces wireless <wlanX> +``` + +This command shows both status and statistics on the specified wireless +interface. The wireless interface identifier can range from wlan0 to wlan999. + +```none +vyos@vyos:~$ show interfaces wireless wlan0 +wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 + link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff + inet xxx.xxx.99.254/24 scope global wlan0 + valid_lft forever preferred_lft forever + inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 66072 282 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 83413 430 0 0 0 0 +``` + +```{eval-rst} +.. opcmd:: show interfaces wireless <wlanX> brief +``` + +This command gives a brief status overview of a specified wireless interface. +The wireless interface identifier can range from wlan0 to wlan999. + +```none +vyos@vyos:~$ show interfaces wireless wlan0 brief +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +wlan0 192.168.2.254/24 u/u +``` + +```{eval-rst} +.. opcmd:: show interfaces wireless <wlanX> queue +``` + +Use this command to view wireless interface queue information. +The wireless interface identifier can range from wlan0 to wlan999. + +```none +vyos@vyos:~$ show interfaces wireless wlan0 queue +qdisc pfifo_fast 0: root bands 3 priomap 1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1 + Sent 810323 bytes 6016 pkt (dropped 0, overlimits 0 requeues 0) + rate 0bit 0pps backlog 0b 0p requeues 0 +``` + +```{eval-rst} +.. opcmd:: show interfaces wireless <wlanX> scan +``` + +This command is used to retrieve information about WAP within the range of your +wireless interface. This command is useful on wireless interfaces configured +in station mode. + +:::{note} +Scanning is not supported on all wireless drivers and wireless +hardware. Refer to your driver and wireless hardware documentation for +further details. +::: + +```none +vyos@vyos:~$ show interfaces wireless wlan0 scan +Address SSID Channel Signal (dbm) +00:53:3b:88:6e:d8 WLAN-576405 1 -64.00 +00:53:3b:88:6e:da Telekom_FON 1 -64.00 +00:53:00:f2:c2:a4 BabyView_F2C2A4 6 -60.00 +00:53:3b:88:6e:d6 Telekom_FON 100 -72.00 +00:53:3b:88:6e:d4 WLAN-576405 100 -71.00 +00:53:44:a4:96:ec KabelBox-4DC8 56 -81.00 +00:53:d9:7a:67:c2 WLAN-741980 1 -75.00 +00:53:7c:99:ce:76 Vodafone Homespot 1 -86.00 +00:53:44:a4:97:21 KabelBox-4DC8 1 -78.00 +00:53:44:a4:97:21 Vodafone Hotspot 1 -79.00 +00:53:44:a4:97:21 Vodafone Homespot 1 -79.00 +00:53:86:40:30:da Telekom_FON 1 -86.00 +00:53:7c:99:ce:76 Vodafone Hotspot 1 -86.00 +00:53:44:46:d2:0b Vodafone Hotspot 1 -87.00 +``` + +## Examples + +The following example creates a WAP. When configuring multiple WAP interfaces, +you must specify unique IP addresses, channels, Network IDs commonly referred +to as {abbr}`SSID (Service Set Identifier)`, and MAC addresses. + +The WAP in this example has the following characteristics: + +- IP address `192.168.2.1/24` +- Network ID (SSID) `TEST` +- WPA passphrase `12345678` +- Use 802.11n protocol +- Wireless channel `1` + +```none +set interfaces wireless wlan0 address '192.168.2.1/24' +set interfaces wireless wlan0 type access-point +set interfaces wireless wlan0 channel 1 +set interfaces wireless wlan0 mode n +set interfaces wireless wlan0 ssid 'TEST' +set interfaces wireless wlan0 security wpa mode wpa2 +set interfaces wireless wlan0 security wpa cipher CCMP +set interfaces wireless wlan0 security wpa passphrase '12345678' +set interfaces wireless wlan0 country-code de +``` + +Resulting in + +```none +interfaces { + [...] + wireless wlan0 { + address 192.168.2.1/24 + channel 1 + country-code de + mode n + security { + wpa { + cipher CCMP + mode wpa2 + passphrase "12345678" + } + } + ssid "TEST" + type access-point + } +} +system { + [...] + wifi-regulatory-domain DE +} +``` + +To get it to work as an access point with this configuration you will need +to set up a DHCP server to work with that network. You can - of course - also +bridge the Wireless interface with any configured bridge +({ref}`bridge-interface`) on the system. + +(wireless-interface-intel-ax200)= + +### Intel AX200 + +The Intel AX200 card does not work out of the box in AP mode, see +<https://unix.stackexchange.com/questions/598275/intel-ax200-ap-mode>. You can +still put this card into AP mode using the following configuration: + + +```none +set interfaces wireless wlan0 channel '1' +set interfaces wireless wlan0 country-code 'us' +set interfaces wireless wlan0 mode 'n' +set interfaces wireless wlan0 physical-device 'phy0' +set interfaces wireless wlan0 ssid 'VyOS' +set interfaces wireless wlan0 type 'access-point' +``` + diff --git a/docs/configuration/interfaces/md-wwan.md b/docs/configuration/interfaces/md-wwan.md new file mode 100644 index 00000000..ac096259 --- /dev/null +++ b/docs/configuration/interfaces/md-wwan.md @@ -0,0 +1,372 @@ +--- +lastproofread: '2023-01-27' +--- + +(wwan-interface)= + +# WWAN - Wireless Wide-Area-Network + +The Wireless Wide-Area-Network interface provides access (through a wireless +modem/wwan) to wireless networks provided by various cellular providers. + +VyOS uses the `interfaces wwan` subsystem for configuration. + +## Configuration + +### Common interface configuration + +```{eval-rst} +.. cmdincludemd:: /_include/interface-address-with-dhcp.txt + :var0: wwan + :var1: wwan0 +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-description.txt + :var0: wwan + :var1: wwan0 +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-disable.txt + :var0: wwan + :var1: wwan0 +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-disable-link-detect.txt + :var0: wwan + :var1: wwan0 +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-mtu.txt + :var0: wwan + :var1: wwan0 +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-ip.txt + :var0: wwan + :var1: wwan0 +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-ipv6.txt + :var0: wwan + :var1: wwan0 +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-vrf.txt + :var0: wwan + :var1: wwan0 +``` + +**DHCP(v6)** + +```{eval-rst} +.. cmdincludemd:: /_include/interface-dhcp-options.txt + :var0: wwan + :var1: wwan0 +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-dhcpv6-options.txt + :var0: wwan + :var1: wwan0 +``` + +```{eval-rst} +.. cmdincludemd:: /_include/interface-dhcpv6-prefix-delegation.txt + :var0: wwan + :var1: wwan0 +``` + +### WirelessModem (WWAN) options + +```{eval-rst} +.. cfgcmd:: set interfaces wwan <interface> apn <apn> + + Every WWAN connection requires an {abbr}`APN (Access Point Name)` which is + used by the client to dial into the ISPs network. This is a mandatory + parameter. Contact your Service Provider for correct APN. + +``` + +## Operation + +```{eval-rst} +.. opcmd:: show interfaces wwan <interface> + + Show detailed information on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces wwan wwan0 + wwan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 1000 + link/ether 02:c2:f3:00:01:02 brd ff:ff:ff:ff:ff:ff + inet 10.155.144.12/30 brd 10.155.144.15 scope global dynamic wwan0 + valid_lft 7012sec preferred_lft 7012sec + inet6 fe80::c2:f3ff:fe00:0102/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 640 2 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 3229 16 0 0 0 0 +``` + +```{eval-rst} +.. opcmd:: show interfaces wwan <interface> summary + + Show detailed information summary on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces wwan wwan0 summary + -------------------------------- + General | dbus path: /org/freedesktop/ModemManager1/Modem/0 + | device id: 79f4e9cc2e9fc8d4a3b8c8f6327c2e363170194d + -------------------------------- + Hardware | manufacturer: Sierra Wireless, Incorporated + | model: MC7710 + | revision: SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15 + | h/w revision: 1.0 + | supported: gsm-umts, lte + | current: gsm-umts, lte + | equipment id: 358xxxxxxxxxxxx + -------------------------------- + System | device: /sys/devices/pci0000:00/0000:00:13.0/usb3/3-1/3-1.3 + | drivers: qcserial, qmi_wwan + | plugin: Generic + | primary port: cdc-wdm0 + | ports: ttyUSB0 (qcdm), ttyUSB2 (at), cdc-wdm0 (qmi), wwan0 (net) + -------------------------------- + Numbers | own: 4917xxxxxxxx + -------------------------------- + Status | lock: sim-pin2 + | unlock retries: sim-pin (3), sim-pin2 (3), sim-puk (10), sim-puk2 (10) + | state: connected + | power state: on + | access tech: lte + | signal quality: 63% (recent) + -------------------------------- + Modes | supported: allowed: 2g; preferred: none + | allowed: 3g; preferred: none + | allowed: 4g; preferred: none + | allowed: 2g, 3g; preferred: 3g + | allowed: 2g, 3g; preferred: 2g + | allowed: 2g, 4g; preferred: 4g + | allowed: 2g, 4g; preferred: 2g + | allowed: 3g, 4g; preferred: 3g + | allowed: 3g, 4g; preferred: 4g + | allowed: 2g, 3g, 4g; preferred: 4g + | allowed: 2g, 3g, 4g; preferred: 3g + | allowed: 2g, 3g, 4g; preferred: 2g + | current: allowed: 2g, 3g, 4g; preferred: 2g + -------------------------------- + Bands | supported: egsm, dcs, pcs, utran-1, utran-8, eutran-1, eutran-3, + | eutran-7, eutran-8, eutran-20 + | current: egsm, dcs, pcs, utran-1, utran-8, eutran-1, eutran-3, + | eutran-7, eutran-8, eutran-20 + -------------------------------- + IP | supported: ipv4, ipv6, ipv4v6 + -------------------------------- + 3GPP | imei: 358xxxxxxxxxxxx + | operator id: 26201 + | operator name: Telekom.de + | registration: home + -------------------------------- + 3GPP EPS | ue mode of operation: ps-1 + -------------------------------- + SIM | dbus path: /org/freedesktop/ModemManager1/SIM/0 + -------------------------------- + Bearer | dbus path: /org/freedesktop/ModemManager1/Bearer/0 + +``` + +```{eval-rst} +.. opcmd:: show interfaces wwan <interface> capabilities + + Show WWAN module hardware capabilities. + + .. code-block:: none + + vyos@vyos:~$ show interfaces wwan wwan0 capabilities + Max TX channel rate: '50000000' + Max RX channel rate: '100000000' + Data Service: 'simultaneous-cs-ps' + SIM: 'supported' + Networks: 'gsm, umts, lte' + Bands: 'gsm-dcs-1800, gsm-900-extended, gsm-900-primary, gsm-pcs-1900, wcdma-2100, wcdma-900' + LTE bands: '1, 3, 7, 8, 20' +``` + +```{eval-rst} +.. opcmd:: show interfaces wwan <interface> firmware + + Show WWAN module firmware. + + .. code-block:: none + + vyos@vyos:~$ show interfaces wwan wwan0 firmware + Model: MC7710 + Boot version: SWI9200X_03.05.29.03bt r6485 CNSHZ-ED-XP0031 2014/12/02 17:33:08 + AMSS version: SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15 + SKU ID: unknown + Package ID: unknown + Carrier ID: 0 + Config version: unknown + +``` + +```{eval-rst} +.. opcmd:: show interfaces wwan <interface> imei + + Show WWAN module IMEI. + + .. code-block:: none + + vyos@vyos:~$ show interfaces wwan wwan0 imei + ESN: '0' + IMEI: '358xxxxxxxxxxxx' + MEID: 'unknown' +``` + +```{eval-rst} +.. opcmd:: show interfaces wwan <interface> imsi + + Show WWAN module IMSI. + + .. code-block:: none + + vyos@vyos:~$ show interfaces wwan wwan0 imsi + IMSI: '262xxxxxxxxxxxx' +``` + +```{eval-rst} +.. opcmd:: show interfaces wwan <interface> model + + Show WWAN module model. + + .. code-block:: none + + vyos@vyos:~$ show interfaces wwan wwan0 model + Model: 'MC7710' +``` + +```{eval-rst} +.. opcmd:: show interfaces wwan <interface> msisdn + + Show WWAN module MSISDN. + + .. code-block:: none + + vyos@vyos:~$ show interfaces wwan wwan0 msisdn + MSISDN: '4917xxxxxxxx' +``` + +```{eval-rst} +.. opcmd:: show interfaces wwan <interface> revision + + Show WWAN module hardware revision. + + .. code-block:: none + + vyos@vyos:~$ show interfaces wwan wwan0 revision + Revision: 'SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15' +``` + +```{eval-rst} +.. opcmd:: show interfaces wwan <interface> signal + + Show WWAN module signal strength. + + .. code-block:: none + + vyos@vyos:~$ show interfaces wwan wwan0 signal + LTE: + RSSI: '-74 dBm' + RSRQ: '-7 dB' + RSRP: '-100 dBm' + SNR: '13.0 dB' + Radio Interface: 'lte' + Active Band Class: 'eutran-3' + Active Channel: '1300' +``` + +```{eval-rst} +.. opcmd:: show interfaces wwan <interface> sim + + Show WWAN module SIM card information. + + .. code-block:: none + + vyos@vyos:~$ show interfaces wwan wwan0 sim + Provisioning applications: + Primary GW: slot '1', application '1' + Primary 1X: session doesn't exist + Secondary GW: session doesn't exist + Secondary 1X: session doesn't exist + Slot [1]: + Card state: 'present' + UPIN state: 'not-initialized' + UPIN retries: '0' + UPUK retries: '0' + Application [1]: + Application type: 'usim (2)' + Application state: 'ready' + Application ID: + A0:00:00:00:87:10:02:FF:49:94:20:89:03:10:00:00 + Personalization state: 'ready' + UPIN replaces PIN1: 'no' + PIN1 state: 'disabled' + PIN1 retries: '3' + PUK1 retries: '10' + PIN2 state: 'enabled-not-verified' + PIN2 retries: '3' + PUK2 retries: '10' +``` + +## Example + +The following example is based on a Sierra Wireless MC7710 miniPCIe card (only +the form factor in reality it runs UBS) and Deutsche Telekom as ISP. The card +is assembled into a {ref}`pc-engines-apu4`. + +```none +set interfaces wwan wwan0 apn 'internet.telekom' +set interfaces wwan wwan0 address 'dhcp' +``` + +## Supported Modules + +The following hardware modules have been tested successfully in an +{ref}`pc-engines-apu4` board: + +- Sierra Wireless AirPrime MC7304 miniPCIe card (LTE) +- Sierra Wireless AirPrime MC7430 miniPCIe card (LTE) +- Sierra Wireless AirPrime MC7455 miniPCIe card (LTE) +- Sierra Wireless AirPrime MC7710 miniPCIe card (LTE) +- Huawei ME909u-521 miniPCIe card (LTE) +- Huawei ME909s-120 miniPCIe card (LTE) +- HP LT4120 Snapdragon X5 LTE + +## Firmware Update + +All available WWAN cards have a build in, reprogrammable firmware. Most of the +vendors provide a regular update to the firmware used in the baseband chip. + +As VyOS makes use of the QMI interface to connect to the WWAN modem cards, also +the firmware can be reprogrammed. + +To update the firmware, VyOS also ships the `qmi-firmware-update` binary. To +upgrade the firmware of an e.g. Sierra Wireless MC7710 module to the firmware +provided in the file `9999999_9999999_9200_03.05.14.00_00_generic_000.000_001_SPKG_MC.cwe` +use the following command: + +```bash +$ sudo qmi-firmware-update --update -d 1199:68a2 \ + 9999999_9999999_9200_03.05.14.00_00_generic_000.000_001_SPKG_MC.cwe +``` diff --git a/docs/configuration/loadbalancing/md-index.md b/docs/configuration/loadbalancing/md-index.md new file mode 100644 index 00000000..22c34bd8 --- /dev/null +++ b/docs/configuration/loadbalancing/md-index.md @@ -0,0 +1,12 @@ +(load-balancing)= + +# Load-balancing + +```{eval-rst} +.. toctree:: + :maxdepth: 1 + :includehidden: + + wan + reverse-proxy +``` diff --git a/docs/configuration/loadbalancing/md-reverse-proxy.md b/docs/configuration/loadbalancing/md-reverse-proxy.md new file mode 100644 index 00000000..d9719425 --- /dev/null +++ b/docs/configuration/loadbalancing/md-reverse-proxy.md @@ -0,0 +1,485 @@ +# Reverse-proxy + +```{include} /_include/need_improvement.txt +``` + +VyOS reverse-proxy is balancer and proxy server that provides +high-availability, load balancing and proxying for TCP (level 4) +and HTTP-based (level 7) applications. + +## Configuration + +Service configuration is responsible for binding to a specific port, +while the backend configuration determines the type of load balancing +to be applied and specifies the real servers to be utilized. + +### Service + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy service <name> listen-address + <address> + + Set service to bind on IP address, by default listen on any IPv4 and IPv6 +``` + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy service <name> port + <port> + + Create service `<name>` to listen on <port> +``` + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy service <name> mode + <tcp|http> + + Configure service `<name>` mode TCP or HTTP +``` + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy service <name> backend + <name> + + Configure service `<name>` to use the backend <name> +``` + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy service <name> ssl + certificate <name> + + Set SSL certificate <name> for service <name> +``` + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy service <name> + http-response-headers <header-name> value <header-value> + + Set custom HTTP headers to be included in all responses +``` + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy service <name> logging facility + <facility> level <level> + + Specify facility and level for logging. + For an explanation on {ref}`syslog_facilities` and {ref}`syslog_severity_level` + see tables in syslog configuration section. + +``` + +#### Rules + +Rules allow to control and route incoming traffic to specific backend based +on predefined conditions. Rules allow to define matching criteria and +perform action accordingly. + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy service <name> rule <rule> + domain-name <name> + + Match domain name +``` + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy service <name> rule <rule> + ssl <sni> + + SSL match Server Name Indication (SNI) option: + * ``req-ssl-sni`` SSL Server Name Indication (SNI) request match + * ``ssl-fc-sni`` SSL frontend connection Server Name Indication match + * ``ssl-fc-sni-end`` SSL frontend match end of connection Server Name + + Indication +``` + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy service <name> rule <rule> + url-path <match> <url> + + Allows to define URL path matching rules for a specific service. + + With this command, you can specify how the URL path should be matched + against incoming requests. + + The available options for <match> are: + * ``begin`` Matches the beginning of the URL path + * ``end`` Matches the end of the URL path. + * ``exact`` Requires an exactly match of the URL path +``` + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy service <name> rule <rule> + set backend <name> + + Assign a specific backend to a rule +``` + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy service <name> rule <rule> + redirect-location <url> + + Redirect URL to a new location + +``` + +### Backend + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy backend <name> balance + <balance> + + Load-balancing algorithms to be used for distributed requests among the + available servers + + Balance algorithms: + * ``source-address`` Distributes requests based on the source IP address + of the client + * ``round-robin`` Distributes requests in a circular manner, + sequentially sending each request to the next server in line + * ``least-connection`` Distributes requests to the server with the fewest + active connections +``` + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy backend <name> mode + <mode> + + Configure backend `<name>` mode TCP or HTTP +``` + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy backend <name> server + <name> address <x.x.x.x> + + Set the address of the backend server to which the incoming traffic will + be forwarded +``` + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy backend <name> server + <name> port <port> + + Set the address of the backend port +``` + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy backend <name> server + <name> check + + Active health check backend server +``` + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy backend <name> server + <name> send-proxy + + Send a Proxy Protocol version 1 header (text format) +``` + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy backend <name> server + <name> send-proxy-v2 + + Send a Proxy Protocol version 2 header (binary format) +``` + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy backend <name> ssl + ca-certificate <ca-certificate> + + Configure requests to the backend server to use SSL encryption and + authenticate backend against <ca-certificate> +``` + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy backend <name> ssl no-verify + + Configure requests to the backend server to use SSL encryption without + validating server certificate +``` + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy backend <name> + http-response-headers <header-name> value <header-value> + + Set custom HTTP headers to be included in all responses using the backend +``` + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy backend <name> logging facility + <facility> level <level> + + Specify facility and level for logging. + For an explanation on {ref}`syslog_facilities` and {ref}`syslog_severity_level` + see tables in syslog configuration section. + +``` + +### Global + +Global parameters + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy global-parameters max-connections + <num> + + Limit maximum number of connections +``` + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy global-parameters ssl-bind-ciphers + <ciphers> + + Limit allowed cipher algorithms used during SSL/TLS handshake +``` + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy global-parameters tls-version-min + <version> + + Specify the minimum required TLS version 1.2 or 1.3 +``` + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy global-parameters logging + facility <facility> level <level> + + Specify facility and level for logging. + For an explanation on {ref}`syslog_facilities` and {ref}`syslog_severity_level` + see tables in syslog configuration section. +``` + +## Health checks + +### HTTP checks + +For web application providing information about their state HTTP health +checks can be used to determine their availability. + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy backend <name> http-check + + Enables HTTP health checks using OPTION HTTP requests against '/' and + expecting a successful response code in the 200-399 range. +``` + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy backend <name> http-check + method <method> + + Sets the HTTP method to be used, can be either: option, get, post, put +``` + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy backend <name> http-check + uri <path> + + Sets the endpoint to be used for health checks +``` + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy backend <name> http-check + expect <condition> + + Sets the expected result condition for considering a server healthy. + + Some possible examples are: + * ``status 200`` Expecting a 200 response code + * ``status 200-399`` Expecting a non-failure response code + * ``string success`` Expecting the string `success` in the response body + +``` + +### TCP checks + +Health checks can also be configured for TCP mode backends. You can configure +protocol aware checks for a range of Layer 7 protocols: + +```{eval-rst} +.. cfgcmd:: set load-balancing reverse-proxy backend <name> health-check <protocol> + + Available health check protocols: + * ``ldap`` LDAP protocol check. + * ``redis`` Redis protocol check. + * ``mysql`` MySQL protocol check. + * ``pgsql`` PostgreSQL protocol check. + * ``smtp`` SMTP protocol check. +``` + +:::{note} +If you specify a server to be checked but do not configure a +protocol, a basic TCP health check will be attempted. A server shall be +deemed online if it responses to a connection attempt with a valid +`SYN/ACK` packet. +::: + +## Redirect HTTP to HTTPS + +Configure the load-balancing reverse-proxy service for HTTP. + +This configuration listen on port 80 and redirect incoming +requests to HTTPS: + +```none +set load-balancing reverse-proxy service http port '80' +set load-balancing reverse-proxy service http redirect-http-to-https +``` + +The name of the service can be different, in this example it is only for +convenience. + +## Examples + +### Level 4 balancing + +This configuration enables the TCP reverse proxy for the "my-tcp-api" service. +Incoming TCP connections on port 8888 will be load balanced across the backend +servers (srv01 and srv02) using the round-robin load-balancing algorithm. + +```none +set load-balancing reverse-proxy service my-tcp-api backend 'bk-01' +set load-balancing reverse-proxy service my-tcp-api mode 'tcp' +set load-balancing reverse-proxy service my-tcp-api port '8888' + +set load-balancing reverse-proxy backend bk-01 balance 'round-robin' +set load-balancing reverse-proxy backend bk-01 mode 'tcp' + +set load-balancing reverse-proxy backend bk-01 server srv01 address '192.0.2.11' +set load-balancing reverse-proxy backend bk-01 server srv01 port '8881' +set load-balancing reverse-proxy backend bk-01 server srv02 address '192.0.2.12' +set load-balancing reverse-proxy backend bk-01 server srv02 port '8882' +``` + +### Balancing based on domain name + +The following configuration demonstrates how to use VyOS +to achieve load balancing based on the domain name. + +The HTTP service listen on TCP port 80. + +Rule 10 matches requests with the domain name `node1.example.com` forwards +to the backend `bk-api-01` + +Rule 20 matches requests with the domain name `node2.example.com` forwards +to the backend `bk-api-02` + +```none +set load-balancing reverse-proxy service http description 'bind app listen on 443 port' +set load-balancing reverse-proxy service http mode 'tcp' +set load-balancing reverse-proxy service http port '80' + +set load-balancing reverse-proxy service http rule 10 domain-name 'node1.example.com' +set load-balancing reverse-proxy service http rule 10 set backend 'bk-api-01' +set load-balancing reverse-proxy service http rule 20 domain-name 'node2.example.com' +set load-balancing reverse-proxy service http rule 20 set backend 'bk-api-02' + +set load-balancing reverse-proxy backend bk-api-01 description 'My API-1' +set load-balancing reverse-proxy backend bk-api-01 mode 'tcp' +set load-balancing reverse-proxy backend bk-api-01 server api01 address '127.0.0.1' +set load-balancing reverse-proxy backend bk-api-01 server api01 port '4431' +set load-balancing reverse-proxy backend bk-api-02 description 'My API-2' +set load-balancing reverse-proxy backend bk-api-02 mode 'tcp' +set load-balancing reverse-proxy backend bk-api-02 server api01 address '127.0.0.2' +set load-balancing reverse-proxy backend bk-api-02 server api01 port '4432' +``` + +### Terminate SSL + +The following configuration terminates SSL on the router. + +The `http` service is listens on port 80 and force redirects from HTTP to +HTTPS. + +The `https` service listens on port 443 with backend `bk-default` to +handle HTTPS traffic. It uses certificate named `cert` for SSL termination. +HSTS header is set with a 1-year expiry, to tell browsers to always use SSL for site. + +Rule 10 matches requests with the exact URL path `/.well-known/xxx` +and redirects to location `/certs/`. + +Rule 20 matches requests with URL paths ending in `/mail` or exact +path `/email/bar` redirect to location `/postfix/`. + +Additional global parameters are set, including the maximum number +connection limit of 4000 and a minimum TLS version of 1.3. + +```none +set load-balancing reverse-proxy service http description 'Force redirect to HTTPS' +set load-balancing reverse-proxy service http port '80' +set load-balancing reverse-proxy service http redirect-http-to-https + +set load-balancing reverse-proxy service https backend 'bk-default' +set load-balancing reverse-proxy service https description 'listen on 443 port' +set load-balancing reverse-proxy service https mode 'http' +set load-balancing reverse-proxy service https port '443' +set load-balancing reverse-proxy service https ssl certificate 'cert' +set load-balancing reverse-proxy service https http-response-headers Strict-Transport-Security value 'max-age=31536000' + +set load-balancing reverse-proxy service https rule 10 url-path exact '/.well-known/xxx' +set load-balancing reverse-proxy service https rule 10 set redirect-location '/certs/' +set load-balancing reverse-proxy service https rule 20 url-path end '/mail' +set load-balancing reverse-proxy service https rule 20 url-path exact '/email/bar' +set load-balancing reverse-proxy service https rule 20 set redirect-location '/postfix/' + +set load-balancing reverse-proxy backend bk-default description 'Default backend' +set load-balancing reverse-proxy backend bk-default mode 'http' +set load-balancing reverse-proxy backend bk-default server sr01 address '192.0.2.23' +set load-balancing reverse-proxy backend bk-default server sr01 port '80' + +set load-balancing reverse-proxy global-parameters max-connections '4000' +set load-balancing reverse-proxy global-parameters tls-version-min '1.3' +``` + +### SSL Bridging + +The following configuration terminates incoming HTTPS traffic on the router, +then re-encrypts the traffic and sends to the backend server via HTTPS. +This is useful if encryption is required for both legs, but you do not want to +install publicly trusted certificates on each backend server. + +Backend service certificates are checked against the certificate authority +specified in the configuration, which could be an internal CA. + +The `https` service listens on port 443 with backend `bk-bridge-ssl` to +handle HTTPS traffic. It uses certificate named `cert` for SSL termination. + +The `bk-bridge-ssl` backend connects to sr01 server on port 443 via HTTPS +and checks backend server has a valid certificate trusted by CA `cacert` + +```none +set load-balancing reverse-proxy service https backend 'bk-bridge-ssl' +set load-balancing reverse-proxy service https description 'listen on 443 port' +set load-balancing reverse-proxy service https mode 'http' +set load-balancing reverse-proxy service https port '443' +set load-balancing reverse-proxy service https ssl certificate 'cert' + +set load-balancing reverse-proxy backend bk-bridge-ssl description 'SSL backend' +set load-balancing reverse-proxy backend bk-bridge-ssl mode 'http' +set load-balancing reverse-proxy backend bk-bridge-ssl ssl ca-certificate 'cacert' +set load-balancing reverse-proxy backend bk-bridge-ssl server sr01 address '192.0.2.23' +set load-balancing reverse-proxy backend bk-bridge-ssl server sr01 port '443' +``` + +### Balancing with HTTP health checks + +This configuration enables HTTP health checks on backend servers. + +```none +set load-balancing reverse-proxy service my-tcp-api backend 'bk-01' +set load-balancing reverse-proxy service my-tcp-api mode 'tcp' +set load-balancing reverse-proxy service my-tcp-api port '8888' + +set load-balancing reverse-proxy backend bk-01 balance 'round-robin' +set load-balancing reverse-proxy backend bk-01 mode 'tcp' + +set load-balancing reverse-proxy backend bk-01 http-check method 'get' +set load-balancing reverse-proxy backend bk-01 http-check uri '/health' +set load-balancing reverse-proxy backend bk-01 http-check expect 'status 200' + +set load-balancing reverse-proxy backend bk-01 server srv01 address '192.0.2.11' +set load-balancing reverse-proxy backend bk-01 server srv01 port '8881' +set load-balancing reverse-proxy backend bk-01 server srv01 check +set load-balancing reverse-proxy backend bk-01 server srv02 address '192.0.2.12' +set load-balancing reverse-proxy backend bk-01 server srv02 port '8882' +set load-balancing reverse-proxy backend bk-01 server srv02 check +``` diff --git a/docs/configuration/loadbalancing/md-wan.md b/docs/configuration/loadbalancing/md-wan.md new file mode 100644 index 00000000..272ba9e9 --- /dev/null +++ b/docs/configuration/loadbalancing/md-wan.md @@ -0,0 +1,300 @@ +--- +lastproofread: '2023-01-27' +--- + +# 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: + +> - an interface with a nexthop +> - one rule with a LAN (inbound-interface) and the WAN (interface). + +Let's assume we have two DHCP WAN interfaces and one LAN (eth2): + +```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 +``` + +:::{note} +WAN Load Balacing should not be used when dynamic routing protocol is +used/needed. This feature creates customized routing tables and firewall +rules, that makes it incompatible to use with routing protocols. +::: + +## 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, it can be a number between 1 and 9999: + +```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 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. + +```none +set load-balancing wan rule 1 interface eth0 weight 2 +set load-balancing wan rule 1 interface eth1 weight 1 +``` + +66% of traffic is routed to eth0, eth1 gets 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: + +```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: + +```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: + +```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: + +```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 the destination, `ipv4-address` can be set to +`dhcp` + +```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. + +```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: + +```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: + +```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 +:align: center +:width: 80% +``` + +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: + +```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: + +```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: + +```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: + +```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 + +```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: + +```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 + +```none +restart wan-load-balance +``` diff --git a/docs/configuration/md-index.md b/docs/configuration/md-index.md new file mode 100644 index 00000000..2b4aae0a --- /dev/null +++ b/docs/configuration/md-index.md @@ -0,0 +1,24 @@ +# Configuration Guide + +The following structure respresent the cli structure. + +```{eval-rst} +.. toctree:: + :maxdepth: 1 + :includehidden: + + container/index + firewall/index + highavailability/index + interfaces/index + loadbalancing/index + nat/index + policy/index + pki/index + protocols/index + service/index + system/index + trafficpolicy/index + vpn/index + vrf/index +``` diff --git a/docs/configuration/nat/md-index.md b/docs/configuration/nat/md-index.md new file mode 100644 index 00000000..bb0668ea --- /dev/null +++ b/docs/configuration/nat/md-index.md @@ -0,0 +1,13 @@ +(nat)= + +# NAT + +```{eval-rst} +.. toctree:: + :maxdepth: 1 + :includehidden: + + nat44 + nat64 + nat66 +``` diff --git a/docs/configuration/nat/md-nat44.md b/docs/configuration/nat/md-nat44.md new file mode 100644 index 00000000..f7357f19 --- /dev/null +++ b/docs/configuration/nat/md-nat44.md @@ -0,0 +1,802 @@ +(nat44)= + +# NAT44 + +{abbr}`NAT (Network Address Translation)` is a common method of +remapping one IP address space into another by modifying network address +information in the IP header of packets while they are in transit across +a traffic routing device. The technique was originally used as a +shortcut to avoid the need to readdress every host when a network was +moved. It has become a popular and essential tool in conserving global +address space in the face of IPv4 address exhaustion. One +Internet-routable IP address of a NAT gateway can be used for an entire +private network. + +IP masquerading is a technique that hides an entire IP address space, +usually consisting of private IP addresses, behind a single IP address +in another, usually public address space. The hidden addresses are +changed into a single (public) IP address as the source address of the +outgoing IP packets so they appear as originating not from the hidden +host but from the routing device itself. Because of the popularity of +this technique to conserve IPv4 address space, the term NAT has become +virtually synonymous with IP masquerading. + +As network address translation modifies the IP address information in +packets, NAT implementations may vary in their specific behavior in +various addressing cases and their effect on network traffic. The +specifics of NAT behavior are not commonly documented by vendors of +equipment containing NAT implementations. + +The computers on an internal network can use any of the addresses set +aside by the {abbr}`IANA (Internet Assigned Numbers Authority)` for +private addressing (see {rfc}`1918`). These reserved IP addresses are +not in use on the Internet, so an external machine will not directly +route to them. The following addresses are reserved for private use: + +- 10.0.0.0 to 10.255.255.255 (CIDR: 10.0.0.0/8) +- 172.16.0.0 to 172.31.255.255 (CIDR: 172.16.0.0/12) +- 192.168.0.0 to 192.168.255.255 (CIDR: 192.168.0.0/16) + +If an ISP deploys a {abbr}`CGN (Carrier-grade NAT)`, and uses +{rfc}`1918` address space to number customer gateways, the risk of +address collision, and therefore routing failures, arises when the +customer network already uses an {rfc}`1918` address space. + +This prompted some ISPs to develop a policy within the {abbr}`ARIN +(American Registry for Internet Numbers)` to allocate new private +address space for CGNs, but ARIN deferred to the IETF before +implementing the policy indicating that the matter was not a typical +allocation issue but a reservation of addresses for technical purposes +(per {rfc}`2860`). + +IETF published {rfc}`6598`, detailing a shared address space for use in +ISP CGN deployments that can handle the same network prefixes occurring +both on inbound and outbound interfaces. ARIN returned address space to +the {abbr}`IANA (Internet Assigned Numbers Authority)` for this +allocation. + +The allocated address block is 100.64.0.0/10. + +Devices evaluating whether an IPv4 address is public must be updated to +recognize the new address space. Allocating more private IPv4 address +space for NAT devices might prolong the transition to IPv6. + +## Overview + +### Different NAT Types + +(source-nat)= + +#### SNAT + +{abbr}`SNAT (Source Network Address Translation)` is the most common +form of {abbr}`NAT (Network Address Translation)` and is typically +referred to simply as NAT. To be more correct, what most people refer +to as {abbr}`NAT (Network Address Translation)` is actually the process +of {abbr}`PAT (Port Address Translation)`, or NAT overload. SNAT is +typically used by internal users/private hosts to access the Internet +\- the source address is translated and thus kept private. + +(destination-nat)= + +#### DNAT + +{abbr}`DNAT (Destination Network Address Translation)` changes the +destination address of packets passing through the router, while +{ref}`source-nat` changes the source address of packets. DNAT is +typically used when an external (public) host needs to initiate a +session with an internal (private) host. A customer needs to access a +private service behind the routers public IP. A connection is +established with the routers public IP address on a well known port and +thus all traffic for this port is rewritten to address the internal +(private) host. + +(bidirectional-nat)= + +#### Bidirectional NAT + +This is a common scenario where both {ref}`source-nat` and +{ref}`destination-nat` are configured at the same time. It's commonly +used when internal (private) hosts need to establish a connection with +external resources and external systems need to access internal +(private) resources. + +### NAT, Routing, Firewall Interaction + +There is a very nice picture/explanation in the Vyatta documentation +which should be rewritten here. + +### NAT Ruleset + +{abbr}`NAT (Network Address Translation)` is configured entirely on a +series of so called `rules`. Rules are numbered and evaluated by the +underlying OS in numerical order! The rule numbers can be changes by +utilizing the {cfgcmd}`rename` and {cfgcmd}`copy` commands. + +:::{note} +Changes to the NAT system only affect newly established +connections. Already established connections are not affected. +::: + +:::{hint} +When designing your NAT ruleset leave some space between +consecutive rules for later extension. Your ruleset could start with +numbers 10, 20, 30. You thus can later extend the ruleset and place +new rules between existing ones. +::: + +Rules will be created for both {ref}`source-nat` and +{ref}`destination-nat`. + +For {ref}`bidirectional-nat` a rule for both {ref}`source-nat` and +{ref}`destination-nat` needs to be created. + +(traffic-filters)= + +### Traffic Filters + +Traffic Filters are used to control which packets will have the defined +NAT rules applied. Five different filters can be applied within a NAT +rule. + +- **outbound-interface** - applicable only to {ref}`source-nat`. It + configures the interface which is used for the outside traffic that + this translation rule applies to. Interface groups, inverted + selection and wildcard, are also supported. + + Examples: + + ```none + set nat source rule 20 outbound-interface name eth0 + set nat source rule 30 outbound-interface name bond1* + set nat source rule 20 outbound-interface name !vtun2 + set nat source rule 20 outbound-interface group GROUP1 + set nat source rule 20 outbound-interface group !GROUP2 + ``` + +- **inbound-interface** - applicable only to {ref}`destination-nat`. It + configures the interface which is used for the inside traffic the + translation rule applies to. Interface groups, inverted + selection and wildcard, are also supported. + + Example: + + ```none + set nat destination rule 20 inbound-interface name eth0 + set nat destination rule 30 inbound-interface name bond1* + set nat destination rule 20 inbound-interface name !vtun2 + set nat destination rule 20 inbound-interface group GROUP1 + set nat destination rule 20 inbound-interface group !GROUP2 + ``` + +- **protocol** - specify which types of protocols this translation rule + applies to. Only packets matching the specified protocol are NATed. + By default this applies to `all` protocols. + + Example: + + - Set SNAT rule 20 to only NAT TCP and UDP packets + - Set DNAT rule 20 to only NAT UDP packets + + ```none + set nat source rule 20 protocol tcp_udp + set nat destination rule 20 protocol udp + ``` + +- **source** - specifies which packets the NAT translation rule applies + to based on the packets source IP address and/or source port. Only + matching packets are considered for NAT. + + Example: + + - Set SNAT rule 20 to only NAT packets arriving from the 192.0.2.0/24 + network + - Set SNAT rule 30 to only NAT packets arriving from the 203.0.113.0/24 + network with a source port of 80 and 443 + + ```none + set nat source rule 20 source address 192.0.2.0/24 + set nat source rule 30 source address 203.0.113.0/24 + set nat source rule 30 source port 80,443 + ``` + +- **destination** - specify which packets the translation will be + applied to, only based on the destination address and/or port number + configured. + + :::{note} + If no destination is specified the rule will match on any + destination address and port. + ::: + + Example: + + - Configure SNAT rule (40) to only NAT packets with a destination + address of 192.0.2.1. + + ```none + set nat source rule 40 destination address 192.0.2.1 + ``` + +### Address Conversion + +Every NAT rule has a translation command defined. The address defined +for the translation is the address used when the address information in +a packet is replaced. + +#### Source Address + +For {ref}`source-nat` rules the packets source address will be replaced +with the address specified in the translation command. A port +translation can also be specified and is part of the translation +address. + +:::{note} +The translation address must be set to one of the available +addresses on the configured `outbound-interface` or it must be set to +`masquerade` which will use the primary IP address of the +`outbound-interface` as its translation address. + +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 +private 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: + +- Define a discrete source IP address of 100.64.0.1 for SNAT rule 20 +- Use address `masquerade` (the interfaces primary address) on rule 30 +- For a large amount of private machines behind the NAT your address + pool might to be bigger. Use any address in the range 100.64.0.10 - + 100.64.0.20 on SNAT rule 40 when doing the translation + +```none +set nat source rule 20 translation address 100.64.0.1 +set nat source rule 30 translation address 'masquerade' +set nat source rule 40 translation address 100.64.0.10-100.64.0.20 +``` + +#### Destination Address + +For {ref}`destination-nat` rules the packets destination address will be +replaced by the specified address in the `translation address` command. + +Example: + +- DNAT rule 10 replaces the destination address of an inbound packet + with 192.0.2.10 + +```none +set nat destination rule 10 translation address 192.0.2.10 +``` + +Also, in {ref}`destination-nat`, redirection to localhost is supported. +The redirect statement is a special form of dnat which always translates +the destination address to the local host’s one. + +Example of redirection: + +```none +set nat destination rule 10 translation redirect port 22 +``` + +### NAT Load Balance + +Advanced configuration can be used in order to apply source or destination NAT, +and within a single rule, be able to define multiple translated addresses, +so NAT balances the translations among them. + +NAT Load Balance uses an algorithm that generates a hash and based on it, then +it applies corresponding translation. This hash can be generated randomly, or +can use data from the ip header: source-address, destination-address, +source-port and/or destination-port. By default, it will generate the hash +randomly. + +When defining the translated address, called `backends`, a `weight` must +be configured. This lets the user define load balance distribution according +to their needs. Them sum of all the weights defined for the backends should +be equal to 100. In oder words, the weight defined for the backend is the +percentage of the connections that will receive such backend. + +```{eval-rst} +.. cfgcmd:: set nat [source | destination] rule <rule> load-balance hash + [source-address | destination-address | source-port | destination-port + | random] +``` + +```{eval-rst} +.. cfgcmd:: set nat [source | destination] rule <rule> load-balance backend + <x.x.x.x> weight <1-100> + +``` + +## Configuration Examples + +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: + +```none +set nat source rule 100 outbound-interface name '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: + +```none +rule 100 { + outbound-interface { + name 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 hyphen between two IP +addresses: + +```none +set nat source rule 100 translation address '203.0.113.32-203.0.113.63' +``` + +(avoidng-leaky-nat)= + +### 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. + +(hairpin-nat-reflection)= + +### Hairpin NAT/NAT Reflection + +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. + +Example: + +- Redirect Microsoft RDP traffic from the outside (WAN, external) world + via {ref}`destination-nat` in rule 100 to the internal, private host + 192.0.2.40. +- Redirect Microsoft RDP traffic from the internal (LAN, private) + network via {ref}`destination-nat` in rule 110 to the internal, + private host 192.0.2.40. We also need a {ref}`source-nat` rule 110 for + the reverse path of the traffic. The internal network 192.0.2.0/24 is + reachable via interface `eth0.10`. + +```none +set nat destination rule 100 description 'Regular destination NAT from external' +set nat destination rule 100 destination port '3389' +set nat destination rule 100 inbound-interface name 'pppoe0' +set nat destination rule 100 protocol 'tcp' +set nat destination rule 100 translation address '192.0.2.40' + +set nat destination rule 110 description 'NAT Reflection: INSIDE' +set nat destination rule 110 destination port '3389' +set nat destination rule 110 inbound-interface name 'eth0.10' +set nat destination rule 110 protocol 'tcp' +set nat destination rule 110 translation address '192.0.2.40' + +set nat source rule 110 description 'NAT Reflection: INSIDE' +set nat source rule 110 destination address '192.0.2.0/24' +set nat source rule 110 outbound-interface name 'eth0.10' +set nat source rule 110 protocol 'tcp' +set nat source rule 110 source address '192.0.2.0/24' +set nat source rule 110 translation address 'masquerade' +``` + +Which results in a configuration of: + +```none +vyos@vyos# show nat + destination { + rule 100 { + description "Regular destination NAT from external" + destination { + port 3389 + } + inbound-interface { + name pppoe0 + } + protocol tcp + translation { + address 192.0.2.40 + } + } + rule 110 { + description "NAT Reflection: INSIDE" + destination { + port 3389 + } + inbound-interface { + name eth0.10 + } + protocol tcp + translation { + address 192.0.2.40 + } + } + } + source { + rule 110 { + description "NAT Reflection: INSIDE" + destination { + address 192.0.2.0/24 + } + outbound-interface { + name eth0.10 + } + protocol tcp + source { + address 192.0.2.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: +<https://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers> + +Our configuration commands would be: + +```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 name '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: + +```none +nat { + destination { + rule 10 { + description "Port Forward: HTTP to 192.168.0.100" + destination { + port 80 + } + inbound-interface { + name 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. + +```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: + +```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. + +Here's an extract of a simple 1-to-1 NAT configuration with one internal +and one external interface: + +```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 name '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 name '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. + +### 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. + +### Load Balance + +Here we provide two examples on how to apply NAT Load Balance. + +First scenario: apply destination NAT for all HTTP traffic comming through +interface eth0, and user 4 backends. First backend should received 30% of +the request, second backend should get 20%, third 15% and the fourth 35% +We will use source and destination address for hash generation. + +```none +set nat destination rule 10 inbound-interface name eth0 +set nat destination rule 10 protocol tcp +set nat destination rule 10 destination port 80 +set nat destination rule 10 load-balance hash source-address +set nat destination rule 10 load-balance hash destination-address +set nat destination rule 10 load-balance backend 198.51.100.101 weight 30 +set nat destination rule 10 load-balance backend 198.51.100.102 weight 20 +set nat destination rule 10 load-balance backend 198.51.100.103 weight 15 +set nat destination rule 10 load-balance backend 198.51.100.104 weight 35 +``` + +Second scenario: apply source NAT for all outgoing connections from +LAN 10.0.0.0/8, using 3 public addresses and equal distribution. +We will generate the hash randomly. + +```none +set nat source rule 10 outbound-interface name eth0 +set nat source rule 10 source address 10.0.0.0/8 +set nat source rule 10 load-balance hash random +set nat source rule 10 load-balance backend 192.0.2.251 weight 33 +set nat source rule 10 load-balance backend 192.0.2.252 weight 33 +set nat source rule 10 load-balance backend 192.0.2.253 weight 34 +``` + +#### 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 +:alt: NAT before VPN Topology +:scale: 100 % + +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: + +```none +set interfaces dummy dum0 address '172.29.41.89/32' +``` + +##### NAT Configuration + +```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 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 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) + +```none +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 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 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. + +```none +set vpn ipsec authentication psk vyos id '203.0.113.46' +set vpn ipsec authentication psk vyos id '198.51.100.243' +set vpn ipsec authentication psk vyos secret 'MYSECRETPASSWORD' +set vpn ipsec site-to-site peer branch authentication local-id '203.0.113.46' +set vpn ipsec site-to-site peer branch authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer branch authentication remote-id '198.51.100.243' +set vpn ipsec site-to-site peer branch connection-type 'initiate' +set vpn ipsec site-to-site peer branch default-esp-group 'my-esp' +set vpn ipsec site-to-site peer branch ike-group 'my-ike' +set vpn ipsec site-to-site peer branch ikev2-reauth 'inherit' +set vpn ipsec site-to-site peer branch local-address '203.0.113.46' +set vpn ipsec site-to-site peer branch remote-address '198.51.100.243' +set vpn ipsec site-to-site peer branch tunnel 0 local prefix '172.29.41.89/32' +set vpn ipsec site-to-site peer branch tunnel 0 remote prefix '172.27.1.0/24' +set vpn ipsec site-to-site peer branch tunnel 1 local prefix '172.29.41.89/32' +set vpn ipsec site-to-site peer branch 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: + +```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. diff --git a/docs/configuration/nat/md-nat64.md b/docs/configuration/nat/md-nat64.md new file mode 100644 index 00000000..7b700707 --- /dev/null +++ b/docs/configuration/nat/md-nat64.md @@ -0,0 +1,72 @@ +(nat64)= + +# NAT64 + +{abbr}`NAT64 (IPv6-to-IPv4 Prefix Translation)` is a critical component in +modern networking, facilitating communication between IPv6 and IPv4 networks. +This documentation outlines the setup, configuration, and usage of the NAT64 +feature in your project. Whether you are transitioning to IPv6 or need to +seamlessly connect IPv4 and IPv6 devices. +NAT64 is a stateful translation mechanism that translates IPv6 addresses to +IPv4 addresses and IPv4 addresses to IPv6 addresses. NAT64 is used to enable +IPv6-only clients to contact IPv4 servers using unicast UDP, TCP, or ICMP. + +## Overview + +### Different NAT Types + +(source-nat64)= + +#### SNAT64 + +{abbr}`SNAT64 (IPv6-to-IPv4 Source Address Translation)` is a stateful +translation mechanism that translates IPv6 addresses to IPv4 addresses. + +`64:ff9b::/96` is the well-known prefix for IPv4-embedded IPv6 addresses. +The prefix is used to represent IPv4 addresses in an IPv6 address format. +The IPv4 address is encoded in the low-order 32 bits of the IPv6 address. +The high-order 32 bits are set to the well-known prefix 64:ff9b::/96. + +## Configuration Examples + +The following examples show how to configure NAT64 on a VyOS router. +The 192.0.2.10 address is used as the IPv4 address for the translation pool. + +NAT64 server configuration: + +```none +set interfaces ethernet eth0 address '192.0.2.1/24' +set interfaces ethernet eth0 address '192.0.2.10/24' +set interfaces ethernet eth0 description 'WAN' +set interfaces ethernet eth1 address '2001:db8::1/64' +set interfaces ethernet eth1 description 'LAN' + +set service dns forwarding allow-from '2001:db8::/64' +set service dns forwarding dns64-prefix '64:ff9b::/96' +set service dns forwarding listen-address '2001:db8::1' + +set nat64 source rule 100 source prefix '64:ff9b::/96' +set nat64 source rule 100 translation pool 10 address '192.0.2.10' +set nat64 source rule 100 translation pool 10 port '1-65535' +``` + +NAT64 client configuration: + +```none +set interfaces ethernet eth1 address '2001:db8::2/64' +set protocols static route6 64:ff9b::/96 next-hop 2001:db8::1 +set system name-server '2001:db8::1' +``` + +Test from the IPv6 only client: + +```none +vyos@r1:~$ ping 64:ff9b::192.0.2.1 count 2 +PING 64:ff9b::192.0.2.1(64:ff9b::c000:201) 56 data bytes +64 bytes from 64:ff9b::c000:201: icmp_seq=1 ttl=63 time=0.351 ms +64 bytes from 64:ff9b::c000:201: icmp_seq=2 ttl=63 time=0.373 ms + +--- 64:ff9b::192.0.2.1 ping statistics --- +2 packets transmitted, 2 received, 0% packet loss, time 1023ms +rtt min/avg/max/mdev = 0.351/0.362/0.373/0.011 ms +``` diff --git a/docs/configuration/nat/md-nat66.md b/docs/configuration/nat/md-nat66.md new file mode 100644 index 00000000..371da24f --- /dev/null +++ b/docs/configuration/nat/md-nat66.md @@ -0,0 +1,227 @@ +(nat66)= + +# NAT66(NPTv6) + +{abbr}`NPTv6 (IPv6-to-IPv6 Network Prefix Translation)` is an address +translation technology based on IPv6 networks, used to convert an IPv6 +address prefix in an IPv6 message into another IPv6 address prefix. +We call this address translation method NAT66. Devices that support the NAT66 +function are called NAT66 devices, which can provide NAT66 source +and destination address translation functions. + +## Overview + +### Different NAT Types + +(source-nat66)= + +#### SNAT66 + +{abbr}`SNPTv6 (Source IPv6-to-IPv6 Network Prefix Translation)` The conversion +function is mainly used in the following scenarios: + +- A single internal network and external network. Use the NAT66 device to + connect a single internal network and public network, and the hosts in + the internal network use IPv6 address prefixes that only support + routing within the local range. When a host in the internal network + accesses the external network, the source IPv6 address prefix in + the message will be converted into a global unicast IPv6 address + prefix by the NAT66 device. +- Redundancy and load sharing. There are multiple NAT66 devices at the edge + of an IPv6 network to another IPv6 network. The path through the NAT66 + device to another IPv6 network forms an equivalent route, and traffic + can be load-shared on these NAT66 devices. In this case, you + can configure the same source address translation rules on these + NAT66 devices, so that any NAT66 device can handle IPv6 traffic between + different sites. +- Multi-homed. In a multi-homed network environment, the NAT66 device + connects to an internal network and simultaneously connects to + different external networks. Address translation can be configured + on each external network side interface of the NAT66 device to + convert the same internal network address into different external + network addresses, and realize the mapping of the same internal + address to multiple external addresses. + +(destination-nat66)= + +#### DNAT66 + +The {abbr}`DNPTv6 (Destination IPv6-to-IPv6 Network Prefix Translation)` +destination address translation function is used in scenarios where the +server in the internal network provides services to the external network, +such as providing Web services or FTP services to the external network. +By configuring the mapping relationship between the internal server +address and the external network address on the external network +side interface of the NAT66 device, external network users can +access the internal network server through the designated +external network address. + +### Prefix Conversion + +#### Source Prefix + +Every SNAT66 rule has a translation command defined. The prefix defined +for the translation is the prefix used when the address information in +a packet is replaced.、 + +The {ref}`source-nat66` rule replaces the source address of the packet +and calculates the converted address using the prefix specified in the rule. + +Example: + +- Convert the address prefix of a single `fc01::/64` network to `fc00::/64` +- Output from `eth0` network interface + +```none +set nat66 source rule 1 outbound-interface 'eth0' +set nat66 source rule 1 source prefix 'fc01::/64' +set nat66 source rule 1 translation address 'fc00::/64' +``` + +#### Destination Prefix + +For the {ref}`destination-nat66` rule, the destination address of +the packet isreplaced by the address calculated from the specified +address or prefix in the `translation address` command + +Example: + +- Convert the address prefix of a single `fc00::/64` network + to `fc01::/64` +- Input from `eth0` network interface + +```none +set nat66 destination rule 1 inbound-interface 'eth0' +set nat66 destination rule 1 destination address 'fc00::/64' +set nat66 destination rule 1 translation address 'fc01::/64' +``` + +## Configuration Examples + +Use the following topology to build a nat66 based isolated +network between internal and external networks (dynamic prefix is +not supported): + +:::{figure} /_static/images/vyos_1_4_nat66_simple.png +:alt: VyOS NAT66 Simple Configure +::: + +R1: + +```none +set interfaces ethernet eth0 ipv6 address autoconf +set interfaces ethernet eth1 address 'fc01::1/64' +set nat66 destination rule 1 destination address 'fc00:470:f1cd:101::/64' +set nat66 destination rule 1 inbound-interface 'eth0' +set nat66 destination rule 1 translation address 'fc01::/64' +set nat66 source rule 1 outbound-interface 'eth0' +set nat66 source rule 1 source prefix 'fc01::/64' +set nat66 source rule 1 translation address 'fc00:470:f1cd:101::/64' +``` + +R2: + +```none +set interfaces bridge br1 address 'fc01::2/64' +set interfaces bridge br1 member interface eth0 +set interfaces bridge br1 member interface eth1 +set protocols static route6 ::/0 next-hop fc01::1 +set service router-advert interface br1 prefix ::/0 +``` + +Use the following topology to translate internal user local addresses (`fc::/7`) +to DHCPv6-PD provided prefixes from an ISP connected to a VyOS HA pair. + +:::{figure} /_static/images/vyos_1_5_nat66_dhcpv6_wdummy.png +:alt: VyOS NAT66 DHCPv6 using a dummy interface +::: + +Configure both routers (a and b) for DHCPv6-PD via dummy interface: + +```none +set interfaces dummy dum1 description 'DHCPv6-PD NPT dummy' +set interfaces bonding bond0 vif 20 dhcpv6-options pd 0 interface dum1 address '0' +set interfaces bonding bond0 vif 20 dhcpv6-options pd 1 interface dum1 address '0' +set interfaces bonding bond0 vif 20 dhcpv6-options pd 2 interface dum1 address '0' +set interfaces bonding bond0 vif 20 dhcpv6-options pd 3 interface dum1 address '0' +set interfaces bonding bond0 vif 20 dhcpv6-options rapid-commit +commit +``` + +Get the DHCPv6-PD prefixes from both routers: + +```none +trae@cr01a-vyos# run show interfaces dummy dum1 br +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +dum1 2001:db8:123:b008::/64 u/u DHCPv6-PD NPT dummy + 2001:db8:123:b00a::/64 + 2001:db8:123:b00b::/64 + 2001:db8:123:b009::/64 + +trae@cr01b-vyos# run show int dummy dum1 brief +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +dum1 2001:db8:123:b00d::/64 u/u DHCPv6-PD NPT dummy + 2001:db8:123:b00c::/64 + 2001:db8:123:b00e::/64 + 2001:db8:123:b00f::/64 +``` + +Configure the A-side router for NPTv6 using the prefixes above: + +```none +set nat66 source rule 10 description 'NPT to VLAN 10' +set nat66 source rule 10 outbound-interface name 'bond0.20' +set nat66 source rule 10 source prefix 'fd52:d62e:8011:a::/64' +set nat66 source rule 10 translation address '2001:db8:123:b008::/64' +set nat66 source rule 20 description 'NPT to VLAN 70' +set nat66 source rule 20 outbound-interface name 'bond0.20' +set nat66 source rule 20 source prefix 'fd52:d62e:8011:46::/64' +set nat66 source rule 20 translation address '2001:db8:123:b009::/64' +set nat66 source rule 30 description 'NPT to VLAN 200' +set nat66 source rule 30 outbound-interface name 'bond0.20' +set nat66 source rule 30 source prefix 'fd52:d62e:8011:c8::/64' +set nat66 source rule 30 translation address '2001:db8:123:b00a::/64' +set nat66 source rule 40 description 'NPT to VLAN 240' +set nat66 source rule 40 outbound-interface name 'bond0.20' +set nat66 source rule 40 source prefix 'fd52:d62e:8011:f0::/64' +set nat66 source rule 40 translation address '2001:db8:123:b00b::/64' +commit +``` + +Configure the B-side router for NPTv6 using the prefixes above: + +```none +set nat66 source rule 10 description 'NPT to VLAN 10' +set nat66 source rule 10 outbound-interface name 'bond0.20' +set nat66 source rule 10 source prefix 'fd52:d62e:8011:a::/64' +set nat66 source rule 10 translation address '2001:db8:123:b00c::/64' +set nat66 source rule 20 description 'NPT to VLAN 70' +set nat66 source rule 20 outbound-interface name 'bond0.20' +set nat66 source rule 20 source prefix 'fd52:d62e:8011:46::/64' +set nat66 source rule 20 translation address '2001:db8:123:b00d::/64' +set nat66 source rule 30 description 'NPT to VLAN 200' +set nat66 source rule 30 outbound-interface name 'bond0.20' +set nat66 source rule 30 source prefix 'fd52:d62e:8011:c8::/64' +set nat66 source rule 30 translation address '2001:db8:123:b00e::/64' +set nat66 source rule 40 description 'NPT to VLAN 240' +set nat66 source rule 40 outbound-interface name 'bond0.20' +set nat66 source rule 40 source prefix 'fd52:d62e:8011:f0::/64' +set nat66 source rule 40 translation address '2001:db8:123:b00f::/64' +commit +``` + +Verify that connections are hitting the rule on both sides: + +```none +trae@cr01a-vyos# run show nat66 source statistics +Rule Packets Bytes Interface +------ --------- ------- ----------- +10 1 104 bond0.20 +20 1 104 bond0.20 +30 8093 669445 bond0.20 +40 2446 216912 bond0.20 +``` diff --git a/docs/configuration/pki/md-index.md b/docs/configuration/pki/md-index.md new file mode 100644 index 00000000..d008daaf --- /dev/null +++ b/docs/configuration/pki/md-index.md @@ -0,0 +1,408 @@ +--- +lastproofread: '2024-01-05' +--- + +```{include} /_include/need_improvement.txt +``` + +(pki)= + +# PKI + +VyOS 1.4 changed the way in how encrytion keys or certificates are stored on the +system. In the pre VyOS 1.4 era, certificates got stored under /config and every +service referenced a file. That made copying a running configuration from system +A to system B a bit harder, as you had to copy the files and their permissions +by hand. + +{vytask}`T3642` describes a new CLI subsystem that serves as a "certstore" to +all services requiring any kind of encryption key(s). In short, public and +private certificates are now stored in PKCS#8 format in the regular VyOS CLI. +Keys can now be added, edited, and deleted using the regular set/edit/delete +CLI commands. + +VyOS not only can now manage certificates issued by 3rd party Certificate +Authorities, it can also act as a CA on its own. You can create your own root +CA and sign keys with it by making use of some simple op-mode commands. + +Don't be afraid that you need to re-do your configuration. Key transformation is +handled, as always, by our migration scripts, so this will be a smooth transition +for you! + +## Key Generation + +### Certificate Authority (CA) + +VyOS now also has the ability to create CAs, keys, Diffie-Hellman and other +keypairs from an easy to access operational level command. + +```{eval-rst} +.. opcmd:: generate pki ca + + Create a new {abbr}`CA (Certificate Authority)` and output the CAs public and + private key on the console. +``` + +```{eval-rst} +.. opcmd:: generate pki ca install <name> + + Create a new {abbr}`CA (Certificate Authority)` and output the CAs public and + private key on the console. + + .. include:: pki_cli_import_help.txt +``` + +```{eval-rst} +.. opcmd:: generate pki ca sign <ca-name> + + Create a new subordinate {abbr}`CA (Certificate Authority)` and sign it using + the private key referenced by `ca-name`. +``` + +```{eval-rst} +.. opcmd:: generate pki ca sign <ca-name> install <name> + + Create a new subordinate {abbr}`CA (Certificate Authority)` and sign it using + the private key referenced by `name`. + + .. include:: pki_cli_import_help.txt +``` + +### Certificates + +```{eval-rst} +.. opcmd:: generate pki certificate + + Create a new public/private keypair and output the certificate on the console. +``` + +```{eval-rst} +.. opcmd:: generate pki certificate install <name> + + Create a new public/private keypair and output the certificate on the console. + + .. include:: pki_cli_import_help.txt +``` + +```{eval-rst} +.. opcmd:: generate pki certificate self-signed + + Create a new self-signed certificate. The public/private is then shown on the + console. +``` + +```{eval-rst} +.. opcmd:: generate pki certificate self-signed install <name> + + Create a new self-signed certificate. The public/private is then shown on the + console. + + .. include:: pki_cli_import_help.txt +``` + +```{eval-rst} +.. opcmd:: generate pki certificate sign <ca-name> + + Create a new public/private keypair which is signed by the CA referenced by + `ca-name`. The signed certificate is then output to the console. +``` + +```{eval-rst} +.. opcmd:: generate pki certificate sign <ca-name> install <name> + + Create a new public/private keypair which is signed by the CA referenced by + `ca-name`. The signed certificate is then output to the console. + + .. include:: pki_cli_import_help.txt +``` + +### Diffie-Hellman parameters + +```{eval-rst} +.. opcmd:: generate pki dh + + Generate a new set of {abbr}`DH (Diffie-Hellman)` parameters. The key size + is requested by the CLI and defaults to 2048 bit. + + The generated parameters are then output to the console. +``` + +```{eval-rst} +.. opcmd:: generate pki dh install <name> + + Generate a new set of {abbr}`DH (Diffie-Hellman)` parameters. The key size + is requested by the CLI and defaults to 2048 bit. + + .. include:: pki_cli_import_help.txt +``` + +### OpenVPN + +```{eval-rst} +.. opcmd:: generate pki openvpn shared-secret + + Genearate a new OpenVPN shared secret. The generated secred is the output to + the console. +``` + +```{eval-rst} +.. opcmd:: generate pki openvpn shared-secret install <name> + + Genearate a new OpenVPN shared secret. The generated secred is the output to + the console. + + .. include:: pki_cli_import_help.txt +``` + +### WireGuard + +```{eval-rst} +.. opcmd:: generate pki wireguard key-pair + + Generate a new WireGuard public/private key portion and output the result to + the console. +``` + +```{eval-rst} +.. opcmd:: generate pki wireguard key-pair install <interface> + + Generate a new WireGuard public/private key portion and output the result to + the console. + + .. note:: In addition to the command above, the output is in a format which can + be used to directly import the key into the VyOS CLI by simply copy-pasting + the output from op-mode into configuration mode. + + ``interface`` is used for the VyOS CLI command to identify the WireGuard + interface where this private key is to be used. +``` + +```{eval-rst} +.. opcmd:: generate pki wireguard pre-shared-key + + Generate a WireGuard pre-shared secret used for peers to communicate. +``` + +```{eval-rst} +.. opcmd:: generate pki wireguard pre-shared-key install <peer> + + Generate a WireGuard pre-shared secret used for peers to communicate. + + .. note:: In addition to the command above, the output is in a format which can + be used to directly import the key into the VyOS CLI by simply copy-pasting + the output from op-mode into configuration mode. + + ``peer`` is used for the VyOS CLI command to identify the WireGuard peer where + this secred is to be used. +``` + +## Key usage (CLI) + +### CA (Certificate Authority) + +```{eval-rst} +.. cfgcmd:: set pki ca <name> certificate + + Add the public CA certificate for the CA named `name` to the VyOS CLI. + + .. note:: When loading the certificate you need to manually strip the + ``-----BEGIN CERTIFICATE-----`` and ``-----END CERTIFICATE-----`` tags. + Also, the certificate/key needs to be presented in a single line without + line breaks (``\n``), this can be done using the following shell command: + + ``$ tail -n +2 ca.pem | head -n -1 | tr -d '\n'`` +``` + +```{eval-rst} +.. cfgcmd:: set pki ca <name> crl + + Certificate revocation list in PEM format. +``` + +```{eval-rst} +.. cfgcmd:: set pki ca <name> description + + A human readable description what this CA is about. +``` + +```{eval-rst} +.. cfgcmd:: set pki ca <name> private key + + Add the CAs private key to the VyOS CLI. This should never leave the system, + and is only required if you use VyOS as your certificate generator as + mentioned above. + + .. note:: When loading the certificate you need to manually strip the + ``-----BEGIN KEY-----`` and ``-----END KEY-----`` tags. Also, the + certificate/key needs to be presented in a single line without line + breaks (``\n``), this can be done using the following shell command: + + ``$ tail -n +2 ca.key | head -n -1 | tr -d '\n'`` +``` + +```{eval-rst} +.. cfgcmd:: set pki ca <name> private password-protected + + Mark the CAs private key as password protected. User is asked for the password + when the key is referenced. +``` + +### Server Certificate + +After we have imported the CA certificate(s) we can now import and add +certificates used by services on this router. + +```{eval-rst} +.. cfgcmd:: set pki certificate <name> certificate + + Add public key portion for the certificate named `name` to the VyOS CLI. + + .. note:: When loading the certificate you need to manually strip the + ``-----BEGIN CERTIFICATE-----`` and ``-----END CERTIFICATE-----`` tags. + Also, the certificate/key needs to be presented in a single line without + line breaks (``\n``), this can be done using the following shell command: + + ``$ tail -n +2 cert.pem | head -n -1 | tr -d '\n'`` +``` + +```{eval-rst} +.. cfgcmd:: set pki certificate <name> description + + A human readable description what this certificate is about. +``` + +```{eval-rst} +.. cfgcmd:: set pki certificate <name> private key + + Add the private key portion of this certificate to the CLI. This should never + leave the system as it is used to decrypt the data. + + .. note:: When loading the certificate you need to manually strip the + ``-----BEGIN KEY-----`` and ``-----END KEY-----`` tags. Also, the + certificate/key needs to be presented in a single line without line + breaks (``\n``), this can be done using the following shell command: + + ``$ tail -n +2 cert.key | head -n -1 | tr -d '\n'`` +``` + +```{eval-rst} +.. cfgcmd:: set pki certificate <name> private password-protected + + Mark the private key as password protected. User is asked for the password + when the key is referenced. +``` + +```{eval-rst} +.. cfgcmd:: set pki certificate <name> revoke + + If CA is present, this certificate will be included in generated CRLs +``` + +#### ACME + +The VyOS PKI subsystem can also be used to automatically retrieve Certificates +using the {abbr}`ACME (Automatic Certificate Management Environment)` protocol. +VyOS 1.4.1 does not store the intermediate certificates from ACME. Which makes +this functionality limited. See {vytask}`T7299`. + +```{eval-rst} +.. cfgcmd:: set pki certificate <name> acme domain-name <name> + + Domain names to apply, multiple domain-names can be specified. + + This is a mandatory option +``` + +```{eval-rst} +.. cfgcmd:: set pki certificate <name> acme email <address> + + Email used for registration and recovery contact. + + This is a mandatory option +``` + +```{eval-rst} +.. cfgcmd:: set pki certificate <name> acme listen-address <address> + + The address the server listens to during http-01 challenge +``` + +```{eval-rst} +.. cfgcmd:: set pki certificate <name> acme rsa-key-size <2048 | 3072 | 4096> + + Size of the RSA key. + + This options defaults to 2048 +``` + +```{eval-rst} +.. cfgcmd:: set pki certificate <name> acme url <url> + + ACME Directory Resource URI. + + This defaults to https://acme-v02.api.letsencrypt.org/directory + + .. note:: During initial deployment we recommend using the staging API + of LetsEncrypt to prevent and blacklisting of your system. The API + endpoint is https://acme-staging-v02.api.letsencrypt.org/directory +``` + +## Operation + +VyOS operational mode commands are not only available for generating keys but +also to display them. + +```{eval-rst} +.. opcmd:: show pki ca + + Show a list of installed {abbr}`CA (Certificate Authority)` certificates. + + .. code-block:: none + + vyos@vyos:~$ show pki ca + Certificate Authorities: + Name Subject Issuer CN Issued Expiry Private Key Parent + -------------- ------------------------------------------------------- ----------------- ------------------- ------------------- ------------- -------------- + DST_Root_CA_X3 CN=ISRG Root X1,O=Internet Security Research Group,C=US CN=DST Root CA X3 2021-01-20 19:14:03 2024-09-30 18:14:03 No N/A + R3 CN=R3,O=Let's Encrypt,C=US CN=ISRG Root X1 2020-09-04 00:00:00 2025-09-15 16:00:00 No DST_Root_CA_X3 + vyos_rw CN=VyOS RW CA,O=VyOS,L=Some-City,ST=Some-State,C=GB CN=VyOS RW CA 2021-07-05 13:46:03 2026-07-04 13:46:03 Yes N/A +``` + +```{eval-rst} +.. opcmd:: show pki ca <name> + + Show only information for specified Certificate Authority. +``` + +```{eval-rst} +.. opcmd:: show pki certificate + + Show a list of installed certificates + + .. code-block:: none + + vyos@vyos:~$ show pki certificate + Certificates: + Name Type Subject CN Issuer CN Issued Expiry Revoked Private Key CA Present + --------- ------ --------------------- ------------- ------------------- ------------------- --------- ------------- ------------- + ac2 Server CN=ac2.vyos.net CN=R3 2021-07-05 07:29:59 2021-10-03 07:29:58 No Yes Yes (R3) + rw_server Server CN=VyOS RW CN=VyOS RW CA 2021-07-05 13:48:02 2022-07-05 13:48:02 No Yes Yes (vyos_rw) +``` + +```{eval-rst} +.. opcmd:: show pki certificate <name> + + Show only information for specified certificate. +``` + +```{eval-rst} +.. opcmd:: show pki crl + + Show a list of installed {abbr}`CRLs (Certificate Revocation List)`. +``` + +```{eval-rst} +.. opcmd:: renew certbot + + Manually trigger certificate renewal. This will be done twice a day. +``` diff --git a/docs/configuration/policy/md-access-list.md b/docs/configuration/policy/md-access-list.md new file mode 100644 index 00000000..c3a92e56 --- /dev/null +++ b/docs/configuration/policy/md-access-list.md @@ -0,0 +1,70 @@ +# Access List Policy + +Filtering is used for both input and output of the routing information. Once +filtering is defined, it can be applied in any direction. VyOS makes filtering +possible using acls and prefix lists. + +Basic filtering can be done using access-list and access-list6. + +## Configuration + +### Access Lists + +```{cfgcmd} set policy access-list \<acl_number\> + +This command creates the new access list policy, where `<acl_number>` must be +a number from 1 to 2699. +``` + +```{cfgcmd} set policy access-list \<acl_number\> description \<text\> + +Set description for the access list. +``` + +```{cfgcmd} set policy access-list \<acl_number\> rule \<1-65535\> action \<permit|deny\> + +This command creates a new rule in the access list and defines an action. +``` + +```{cfgcmd} set policy access-list \<acl_number\> rule \<1-65535\> \<destination|source\> \<any|host|inverse-mask|network\> + +This command defines matching parameters for access list rule. Matching +criteria could be applied to destination or source parameters: + +* any: any IP address to match. +* host: single host IP address to match. +* inverse-match: network/netmask to match (requires network be defined). +* network: network/netmask to match (requires inverse-match be defined). +``` + + +### IPv6 Access List + +Basic filtering could also be applied to IPv6 traffic. + +```{cfgcmd} set policy access-list6 \<text\> + +This command creates the new IPv6 access list, identified by `<text>` +``` + +```{cfgcmd} set policy access-list6 \<text\> description \<text\> + +Set description for the IPv6 access list. +``` + +```{cfgcmd} set policy access-list6 \<text\> rule \<1-65535\> action \<permit|deny\> + +This command creates a new rule in the IPv6 access list and defines an +action. +``` + +```{cfgcmd} set policy access-list6 \<text\> rule \<1-65535\> source \<any|exact-match|network\> + +This command defines matching parameters for IPv6 access list rule. Matching +criteria could be applied to source parameters: + +* any: any IPv6 address to match. +* exact-match: exact match of the network prefixes. +* network: network/netmask to match (requires inverse-match be defined) BUG, +NO invert-match option in access-list6 +```
\ No newline at end of file diff --git a/docs/configuration/policy/md-as-path-list.md b/docs/configuration/policy/md-as-path-list.md new file mode 100644 index 00000000..1fcece91 --- /dev/null +++ b/docs/configuration/policy/md-as-path-list.md @@ -0,0 +1,29 @@ +# BGP - AS Path Policy + +VyOS provides policies commands exclusively for BGP traffic filtering and +manipulation: **as-path-list** is one of them. + +## Configuration + +### policy as-path-list + +```{cfgcmd} set policy as-path-list \<text\> + +Create as-path-policy identified by name `<text>`. +``` +```{cfgcmd} set policy as-path-list \<text\> description \<text\> + +Set description for as-path-list policy. +``` +```{cfgcmd} set policy as-path-list \<text\> rule \<1-65535\> action \<permit|deny\> + +Set action to take on entries matching this rule. +``` +```{cfgcmd} set policy as-path-list \<text\> rule \<1-65535\> description \<text\> + +Set description for rule. +``` +```{cfgcmd} set policy as-path-list \<text\> rule \<1-65535\> regex \<text\> + +Regular expression to match against an AS path. For example "64501 64502". +```
\ No newline at end of file diff --git a/docs/configuration/policy/md-community-list.md b/docs/configuration/policy/md-community-list.md new file mode 100644 index 00000000..beaae149 --- /dev/null +++ b/docs/configuration/policy/md-community-list.md @@ -0,0 +1,40 @@ +# BGP - Community List + +VyOS provides policies commands exclusively for BGP traffic filtering and +manipulation: **community-list** is one of them. + +## Configuration + +### policy community-list + +```{eval-rst} +.. cfgcmd:: set policy community-list <text> + + Creat community-list policy identified by name <text>. +``` + +```{eval-rst} +.. cfgcmd:: set policy community-list <text> description <text> + + Set description for community-list policy. +``` + +```{eval-rst} +.. cfgcmd:: set policy community-list <text> rule <1-65535> action + <permit|deny> + + Set action to take on entries matching this rule. +``` + +```{eval-rst} +.. cfgcmd:: set policy community-list <text> rule <1-65535> description <text> + + Set description for rule. +``` + +```{eval-rst} +.. cfgcmd:: set policy community-list <text> rule <1-65535> regex + <aa:nn|local-AS|no-advertise|no-export|internet|additive> + + Regular expression to match against a community-list. +``` diff --git a/docs/configuration/policy/md-examples.md b/docs/configuration/policy/md-examples.md new file mode 100644 index 00000000..992aa82c --- /dev/null +++ b/docs/configuration/policy/md-examples.md @@ -0,0 +1,203 @@ +# BGP Example + +**Policy definition:** + +```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 system-as 1 +set protocols bgp neighbor 203.0.113.2 address-family ipv4-unicast route-map import 'setmet' +set protocols bgp neighbor 203.0.113.2 address-family ipv4-unicast soft-reconfiguration 'inbound' +``` + +Using 'soft-reconfiguration' we get the policy update without bouncing the +neighbor. + +**Routes learned before routing policy applied:** + +```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 +*> 198.51.100.3/32 203.0.113.2 1 0 2 i < Path + +Total number of prefixes 1 +``` + +**Routes learned after routing policy applied:** + +```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 +*> 198.51.100.3/32 203.0.113.2 1 0 2 2 2 2 i + +Total number of prefixes 1 +vyos@vos1:~$ +``` + +You now see the longer AS path. + +# Transparent Proxy + +The following example will show how VyOS can be used to redirect web +traffic to an external transparent proxy: + +```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: + +```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: + +```none +set policy route FILTER-WEB interface eth1 +``` + +# 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 table used for VLAN 10 (192.168.188.0/24) +- `table 11` Routing table used for VLAN 11 (192.168.189.0/24) +- `main` Routing table used by VyOS and other interfaces not + participating in PBR + +:::{figure} /_static/images/pbr_example_1.png +:alt: PBR multiple uplinks +:scale: 80 % + +Policy-Based Routing with multiple ISP uplinks +(source ./draw.io/pbr_example_1.drawio) +::: + +Add default routes for routing `table 10` and `table 11` + +```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 + +```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 + +```none +set policy route 'PBR' interface eth0.10 +set policy route 'PBR' interface eth0.11 +``` + +**OPTIONAL:** Exclude Inter-VLAN traffic (between VLAN10 and VLAN11) +from PBR + +```none +set firewall group network-group VLANS-GR description 'VLANs networks' +set firewall group network-group VLANS-GR network '192.168.188.0/24' +set firewall group network-group VLANS-GR network '192.168.189.0/24' + +set policy route PBR rule 10 description 'VLAN10 <-> VLAN11 shortcut' +set policy route PBR rule 10 destination group network-group 'VLANS-GR' +set policy route PBR rule 10 set table 'main' +``` + +These commands allow the VLAN10 and VLAN11 hosts to communicate with +each other using the main routing table. + +## Local route + +The following example allows VyOS to use {abbr}`PBR (Policy-Based Routing)` +for traffic, which originated from the router itself. That solution for multiple +ISP's and VyOS router will respond from the same interface that the packet was +received. Also, it used, if we want that one VPN tunnel to be through one +provider, and the second through another. + +- `203.0.113.254` IP addreess on VyOS eth1 from ISP1 +- `192.168.2.254` IP addreess on VyOS eth2 from ISP2 +- `table 10` Routing table used for ISP1 +- `table 11` Routing table used for ISP2 + +```none +set policy local-route rule 101 set table '10' +set policy local-route rule 101 source address '203.0.113.254' +set policy local-route rule 102 set table '11' +set policy local-route rule 102 source address '192.0.2.254' +set protocols static table 10 route 0.0.0.0/0 next-hop '203.0.113.1' +set protocols static table 11 route 0.0.0.0/0 next-hop '192.0.2.2' +``` + +Add multiple source IP in one rule with same priority + +```none +set policy local-route rule 101 set table '10' +set policy local-route rule 101 source address '203.0.113.254' +set policy local-route rule 101 source address '203.0.113.253' +set policy local-route rule 101 source address '198.51.100.0/24' +``` + +# Clamp MSS for a specific IP + +This example shows how to target an MSS clamp (in our example to 1360 bytes) +to a specific destination IP. + +```none +set policy route IP-MSS-CLAMP rule 10 description 'Clamp TCP session MSS to 1360 for 198.51.100.30' +set policy route IP-MSS-CLAMP rule 10 destination address '198.51.100.30/32' +set policy route IP-MSS-CLAMP rule 10 protocol 'tcp' +set policy route IP-MSS-CLAMP rule 10 set tcp-mss '1360' +set policy route IP-MSS-CLAMP rule 10 tcp flags 'SYN' +``` + +To apply this policy to the correct interface, configure it on the +interface the inbound local host will send through to reach our +destined target host (in our example eth1). + +```none +set policy route IP-MSS-CLAMP interface eth1 +``` + +You can view that the policy is being correctly (or incorrectly) utilised +with the following command: + +```none +show policy route statistics +``` diff --git a/docs/configuration/policy/md-extcommunity-list.md b/docs/configuration/policy/md-extcommunity-list.md new file mode 100644 index 00000000..5247c13c --- /dev/null +++ b/docs/configuration/policy/md-extcommunity-list.md @@ -0,0 +1,33 @@ +# BGP - Extended Community List + +VyOS provides policies commands exclusively for BGP traffic filtering and +manipulation: **extcommunity-list** is one of them. + +## Configuration + +### policy extcommunity-list + +```{cfgcmd} set policy extcommunity-list \<text\> + +Creat extcommunity-list policy identified by name \<text\>. +``` +```{cfgcmd} set policy extcommunity-list \<text\> description \<text\> + +Set description for extcommunity-list policy. +``` +```{cfgcmd} set policy extcommunity-list \<text\> rule \<1-65535\> action \<permit|deny\> + +Set action to take on entries matching this rule. +``` +```{cfgcmd} set policy extcommunity-list \<text\> rule \<1-65535\> description \<text\> + +Set description for rule. +``` +```{cfgcmd} set policy extcommunity-list \<text\> rule \<1-65535\> regex \<text\> + +Regular expression to match against an extended community list, where text +could be: +* \<aa:nn:nn\>: Extended community list regular expression. +* \<rt aa:nn:nn\>: Route Target regular expression. +* \<soo aa:nn:nn\>: Site of Origin regular expression. +```
\ No newline at end of file diff --git a/docs/configuration/policy/md-index.md b/docs/configuration/policy/md-index.md new file mode 100644 index 00000000..284459c7 --- /dev/null +++ b/docs/configuration/policy/md-index.md @@ -0,0 +1,53 @@ +\:lastproofread:2021-07-12 + +```{include} /_include/need_improvement.txt +``` + +# Policy + +Policies are used for filtering and traffic management. With policies, network +administrators could filter and treat traffic +according to their needs. + +There could be a wide range of routing policies. Some examples are listed +below: + +- Filter traffic based on source/destination address. +- 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. + +Policies, in VyOS, are implemented using FRR filtering and route maps. Detailed +information of FRR could be found in <http://docs.frrouting.org/> + +## Policy Sections + +```{eval-rst} +.. toctree:: + :maxdepth: 1 + :includehidden: + + access-list + prefix-list + route + route-map + local-route + as-path-list + community-list + extcommunity-list + large-community-list +``` + +## Examples + +Examples of policies usage: + +```{eval-rst} +.. toctree:: + :maxdepth: 1 + :includehidden: + + examples +``` diff --git a/docs/configuration/policy/md-large-community-list.md b/docs/configuration/policy/md-large-community-list.md new file mode 100644 index 00000000..23b9a85a --- /dev/null +++ b/docs/configuration/policy/md-large-community-list.md @@ -0,0 +1,29 @@ +# BGP - Large Community List + +VyOS provides policies commands exclusively for BGP traffic filtering and +manipulation: **large-community-list** is one of them. + +## Configuration + +### policy large-community-list + +```{cfgcmd} set policy large-community-list \<text\> + +Create large-community-list policy identified by name `<text>`. +``` +```{cfgcmd} set policy large-community-list \<text\> description \<text\> + +Set description for large-community-list policy. +``` +```{cfgcmd} set policy large-community-list \<text\> rule \<1-65535\> action \<permit|deny\> + +Set action to take on entries matching this rule. +``` +```{cfgcmd} set policy large-community-list \<text\> rule \<1-65535\> description \<text\> + +Set description for rule. +``` +```{cfgcmd} set policy large-community-list \<text\> rule \<1-65535\> regex \<aa:nn:nn\> + +Regular expression to match against a large community list. +```
\ No newline at end of file diff --git a/docs/configuration/policy/md-local-route.md b/docs/configuration/policy/md-local-route.md new file mode 100644 index 00000000..fb5e2e85 --- /dev/null +++ b/docs/configuration/policy/md-local-route.md @@ -0,0 +1,57 @@ +# Local Route Policy + +Policies for local traffic are defined in this section. + +## Configuration + +### Local Route IPv4 + +```{eval-rst} +.. cfgcmd:: set policy local-route rule <1-32765> set table <1-200|main> + + Set routing table to forward packet to. +``` + +```{eval-rst} +.. cfgcmd:: set policy local-route rule <1-32765> source <x.x.x.x|x.x.x.x/x> + + Set source address or prefix to match. +``` + +```{eval-rst} +.. cfgcmd:: set policy local-route rule <1-32765> destination <x.x.x.x|x.x.x.x/x> + + Set destination address or prefix to match. +``` + +```{eval-rst} +.. cfgcmd:: set policy local-route rule <1-32765> inbound-interface <interface> + + Set inbound interface to match. +``` + +### Local Route IPv6 + +```{eval-rst} +.. cfgcmd:: set policy local-route6 rule <1-32765> set table <1-200|main> + + Set routing table to forward packet to. +``` + +```{eval-rst} +.. cfgcmd:: set policy local-route6 rule <1-32765> source <h:h:h:h:h:h:h:h | h:h:h:h:h:h:h:h/x> + + Set source address or prefix to match. +``` + +```{eval-rst} +.. cfgcmd:: set policy local-route6 rule <1-32765> destination <h:h:h:h:h:h:h:h | h:h:h:h:h:h:h:h/x> + + Set destination address or prefix to match. +``` + +```{eval-rst} +.. cfgcmd:: set policy local-route6 rule <1-32765> inbound-interface <interface> + + Set inbound interface to match. +``` diff --git a/docs/configuration/policy/md-prefix-list.md b/docs/configuration/policy/md-prefix-list.md new file mode 100644 index 00000000..7f3d1c3e --- /dev/null +++ b/docs/configuration/policy/md-prefix-list.md @@ -0,0 +1,143 @@ +# Prefix List Policy + +Prefix lists provides the most powerful prefix based filtering mechanism. In +addition to access-list functionality, ip prefix-list has prefix length range +specification. + +If no ip prefix list is specified, it acts as permit. If ip prefix list is +defined, and no match is found, default deny is applied. + +Prefix filtering can be done using prefix-list and prefix-list6. + +## Configuration + +### Prefix Lists + +```{eval-rst} +.. cfgcmd:: set policy prefix-list <text> + + This command creates the new prefix-list policy, identified by <text>. +``` + +```{eval-rst} +.. cfgcmd:: set policy prefix-list <text> description <text> + + Set description for the prefix-list policy. +``` + +```{eval-rst} +.. cfgcmd:: set policy prefix-list <text> rule <1-65535> action <permit|deny> + + This command creates a new rule in the prefix-list and defines an action. +``` + +```{eval-rst} +.. cfgcmd:: set policy prefix-list <text> rule <1-65535> description <text> + + Set description for rule in the prefix-list. +``` + +```{eval-rst} +.. cfgcmd:: set policy prefix-list <text> rule <1-65535> prefix <x.x.x.x/x> + + Prefix to match against. +``` + +```{eval-rst} +.. cfgcmd:: set policy prefix-list <text> rule <1-65535> ge <0-32> + + Netmask greater than length. +``` + +```{eval-rst} +.. cfgcmd:: set policy prefix-list <text> rule <1-65535> le <0-32> + + Netmask less than length +``` + +### Example: Prefix Lists + +This example creates an IPv4 prefix-list named PL4-EXAMPLE-NAME, defines 3 +rules each with 1 prefix, and matches le (less than/equal to) /32. + +```{eval-rst} +.. cfgcmd:: set policy prefix-list PL4-EXAMPLE-NAME rule 10 action 'permit' +``` + +```{eval-rst} +.. cfgcmd:: set policy prefix-list PL4-EXAMPLE-NAME rule 10 le '32' +``` + +```{eval-rst} +.. cfgcmd:: set policy prefix-list PL4-EXAMPLE-NAME rule 10 prefix '192.0.2.0/24' +``` + +```{eval-rst} +.. cfgcmd:: set policy prefix-list PL4-EXAMPLE-NAME rule 20 action 'permit' +``` + +```{eval-rst} +.. cfgcmd:: set policy prefix-list PL4-EXAMPLE-NAME rule 20 le '32' +``` + +```{eval-rst} +.. cfgcmd:: set policy prefix-list PL4-EXAMPLE-NAME rule 20 prefix '198.51.100.0/24' +``` + +```{eval-rst} +.. cfgcmd:: set policy prefix-list PL4-EXAMPLE-NAME rule 30 action 'permit' +``` + +```{eval-rst} +.. cfgcmd:: set policy prefix-list PL4-EXAMPLE-NAME rule 30 le '32' +``` + +```{eval-rst} +.. cfgcmd:: set policy prefix-list PL4-EXAMPLE-NAME rule 30 prefix '203.0.113.0/24' +``` + +### IPv6 Prefix Lists + +```{eval-rst} +.. cfgcmd:: set policy prefix-list6 <text> + + This command creates the new IPv6 prefix-list policy, identified by <text>. +``` + +```{eval-rst} +.. cfgcmd:: set policy prefix-list6 <text> description <text> + + Set description for the IPv6 prefix-list policy. +``` + +```{eval-rst} +.. cfgcmd:: set policy prefix-list6 <text> rule <1-65535> action <permit|deny> + + This command creates a new rule in the IPv6 prefix-list and defines an + action. +``` + +```{eval-rst} +.. cfgcmd:: set policy prefix-list6 <text> rule <1-65535> description <text> + + Set description for rule in IPv6 prefix-list. +``` + +```{eval-rst} +.. cfgcmd:: set policy prefix-list6 <text> rule <1-65535> prefix + <h:h:h:h:h:h:h:h/x> + + IPv6 prefix. +``` + +```{eval-rst} +.. cfgcmd:: set policy prefix-list6 <text> rule <1-65535> ge <0-128> + + Netmask greater than length. +``` + +```{eval-rst} +.. cfgcmd:: set policy prefix-list6 <text> rule <1-65535> le <0-128> + + Netmask less than length +``` diff --git a/docs/configuration/policy/md-route-map.md b/docs/configuration/policy/md-route-map.md new file mode 100644 index 00000000..43ccd625 --- /dev/null +++ b/docs/configuration/policy/md-route-map.md @@ -0,0 +1,515 @@ +# Route Map Policy + +Route map is a powerfull command, that gives network administrators a very +useful and flexible tool for traffic manipulation. + +## Configuration + +### Route Map + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> + + This command creates a new route-map policy, identified by <text>. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> description <text> + + Set description for the route-map policy. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> action <permit|deny> + + Set action for the route-map policy. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> call <text> + + Call another route-map policy on match. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> continue <1-65535> + + Jump to a different rule in this route-map on a match. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> description <text> + + Set description for the rule in the route-map policy. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> match as-path <text> + + BGP as-path list to match. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> match community + community-list <text> + + BGP community-list to match. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> match community + exact-match + + Set BGP community-list to exactly match. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> match extcommunity + <text> + + BGP extended community to match. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> match interface <text> + + First hop interface of a route to match. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> match ip address + access-list <1-2699> + + IP address of route to match, based on access-list. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> match ip address + prefix-list <text> + + IP address of route to match, based on prefix-list. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> match ip address + prefix-len <0-32> + + IP address of route to match, based on specified prefix-length. + Note that this can be used for kernel routes only. + Do not apply to the routes of dynamic routing protocols (e.g. BGP, + RIP, OSFP), as this can lead to unexpected results.. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> match ip nexthop + access-list <1-2699> + + IP next-hop of route to match, based on access-list. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> match ip nexthop + address <x.x.x.x> + + IP next-hop of route to match, based on ip address. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> match ip nexthop + prefix-len <0-32> + + IP next-hop of route to match, based on prefix length. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> match ip nexthop + prefix-list <text> + + IP next-hop of route to match, based on prefix-list. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> match ip nexthop + type <blackhole> + + IP next-hop of route to match, based on type. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> match ip route-source + access-list <1-2699> + + IP route source of route to match, based on access-list. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> match ip route-source + prefix-list <text> + + IP route source of route to match, based on prefix-list. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> match ipv6 address + access-list <text> + + IPv6 address of route to match, based on IPv6 access-list. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> match ipv6 address + prefix-list <text> + + IPv6 address of route to match, based on IPv6 prefix-list. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> match ipv6 address + prefix-len <0-128> + + IPv6 address of route to match, based on specified prefix-length. + Note that this can be used for kernel routes only. + Do not apply to the routes of dynamic routing protocols (e.g. BGP, + RIP, OSFP), as this can lead to unexpected results.. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> match ipv6 nexthop + <h:h:h:h:h:h:h:h> + + Nexthop IPv6 address to match. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> match large-community + large-community-list <text> + + Match BGP large communities. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> match local-preference + <0-4294967295> + + Match local preference. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> match metric <1-65535> + + Match route metric. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> match origin + <egp|igp|incomplete> + + Boarder Gateway Protocol (BGP) origin code to match. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> match peer <x.x.x.x> + + Peer IP address to match. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> match protocol <protocol> + + Source protocol to match. + * ``babel`` - Babel routing protocol (Babel) + * ``bgp`` - Border Gateway Protocol (BGP) + * ``connected`` - Connected routes (directly attached subnet or host) + * ``isis`` - Intermediate System to Intermediate System (IS-IS) + * ``kernel`` - Kernel routes + * ``ospf`` - Open Shortest Path First (OSPFv2) + * ``ospfv3`` - Open Shortest Path First (IPv6) (OSPFv3) + * ``rip`` - Routing Information Protocol (RIP) + * ``ripng`` - Routing Information Protocol next-generation (IPv6) (RIPng) + * ``static`` - Statically configured routes + * ``table`` - Non-main Kernel Routing Table + * ``vnc`` - Virtual Network Control (VNC) +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> match rpki + <invalid|notfound|valid> + + Match RPKI validation result. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> match source-vrf <text> + + Source VRF to match. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> match tag <1-65535> + + Route tag to match. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> on-match goto <1-65535> + + Exit policy on match: go to rule <1-65535> +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> on-match next + + Exit policy on match: go to next sequence number. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set aggregator <as|ip> + <1-4294967295|x.x.x.x> + + BGP aggregator attribute: AS number or IP address of an aggregation. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set as-path exclude + <1-4294967295 | all> + + Drop AS-NUMBER from the BGP AS path. + + If ``all`` is specified, remove all AS numbers from the AS_PATH of the BGP + path's NLRI. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set as-path prepend + <1-4294967295> + + Prepend the given string of AS numbers to the AS_PATH of the BGP path's NLRI. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set as-path + prepend-last-as <n> + + Prepend the existing last AS number (the leftmost ASN) to the AS_PATH. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set atomic-aggregate + + BGP atomic aggregate attribute. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set community + <add|replace> <community> + + Add or replace BGP community attribute in format ``<0-65535:0-65535>`` + or from well-known community list +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set community none + + Delete all BGP communities +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set community delete + <text> + + Delete BGP communities matching the community-list. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set large-community + <add|replace> <GA:LDP1:LDP2> + + Add or replace BGP large-community attribute in format + ``<0-4294967295:0-4294967295:0-4294967295>`` +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set large-community none + + Delete all BGP large-communities +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set large-community delete + <text> + + Delete BGP communities matching the large-community-list. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set extcommunity bandwidth + <1-25600|cumulative|num-multipaths> + + Set extcommunity bandwidth +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set extcommunity bandwidth-non-transitive + + The link bandwidth extended community is encoded as non-transitive +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set extcommunity rt + <text> + + Set route target value in format ``<0-65535:0-4294967295>`` or ``<IP:0-65535>``. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set extcommunity soo + <text> + + Set site of origin value in format ``<0-65535:0-4294967295>`` or ``<IP:0-65535>``. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set extcommunity none + + Clear all BGP extcommunities. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set distance <0-255> + + Locally significant administrative distance. + +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set ip-next-hop + <x.x.x.x> + + Nexthop IP address. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set ip-next-hop + unchanged + + Set the next-hop as unchanged. Pass through the route-map without + changing its value +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set ip-next-hop + peer-address + + Set the BGP nexthop address to the address of the peer. For an incoming + route-map this means the ip address of our peer is used. For an + outgoing route-map this means the ip address of our self is used to + establish the peering with our neighbor. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set ipv6-next-hop + <global|local> <h:h:h:h:h:h:h:h> + + Nexthop IPv6 address. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set ipv6-next-hop + peer-address + + Set the BGP nexthop address to the address of the peer. For an incoming + route-map this means the ip address of our peer is used. For an + outgoing route-map this means the ip address of our self is used to + establish the peering with our neighbor. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set ipv6-next-hop + prefer-global + + For Incoming and Import Route-maps if we receive a v6 global and v6 LL + address for the route, then prefer to use the global address as the + nexthop. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set local-preference + <0-4294967295> + + Set BGP local preference attribute. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set metric + <+/-metric|0-4294967295|rtt|+rtt|-rtt> + + Set the route metric. When used with BGP, set the BGP attribute MED + to a specific value. Use ``+/-`` to add or subtract the specified value + to/from the existing/MED. Use ``rtt`` to set the MED to the round trip + time or ``+rtt/-rtt`` to add/subtract the round trip time to/from the MED. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set metric-type + <type-1|type-2> + + Set OSPF external metric-type. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set origin + <igp|egp|incomplete> + + Set BGP origin code. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set originator-id + <x.x.x.x> + + Set BGP originator ID attribute. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set src + <x.x.x.x|h:h:h:h:h:h:h:h> + + Set source IP/IPv6 address for route. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set table <1-200> + + Set prefixes to table. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set tag <1-65535> + + Set tag value for routing protocol. +``` + +```{eval-rst} +.. cfgcmd:: set policy route-map <text> rule <1-65535> set weight + <0-4294967295> + + Set BGP weight attribute +``` + +### List of well-known communities + +> - `local-as` - Well-known communities value NO_EXPORT_SUBCONFED 0xFFFFFF03 +> - `no-advertise` - Well-known communities value NO_ADVERTISE 0xFFFFFF02 +> - `no-export` - Well-known communities value NO_EXPORT 0xFFFFFF01 +> - `internet` - Well-known communities value 0 +> - `graceful-shutdown` - Well-known communities value GRACEFUL_SHUTDOWN 0xFFFF0000 +> - `accept-own` - Well-known communities value ACCEPT_OWN 0xFFFF0001 +> - `route-filter-translated-v4` - Well-known communities value ROUTE_FILTER_TRANSLATED_v4 0xFFFF0002 +> - `route-filter-v4` - Well-known communities value ROUTE_FILTER_v4 0xFFFF0003 +> - `route-filter-translated-v6` - Well-known communities value ROUTE_FILTER_TRANSLATED_v6 0xFFFF0004 +> - `route-filter-v6` - Well-known communities value ROUTE_FILTER_v6 0xFFFF0005 +> - `llgr-stale` - Well-known communities value LLGR_STALE 0xFFFF0006 +> - `no-llgr` - Well-known communities value NO_LLGR 0xFFFF0007 +> - `accept-own-nexthop` - Well-known communities value accept-own-nexthop 0xFFFF0008 +> - `blackhole` - Well-known communities value BLACKHOLE 0xFFFF029A +> - `no-peer` - Well-known communities value NOPEER 0xFFFFFF04 diff --git a/docs/configuration/policy/md-route.md b/docs/configuration/policy/md-route.md new file mode 100644 index 00000000..7230c9b4 --- /dev/null +++ b/docs/configuration/policy/md-route.md @@ -0,0 +1,483 @@ +# Route and Route6 Policy + +IPv4 route and IPv6 route policies are defined in this section. These route +policies can then be associated to interfaces. + +## Rule-Sets + +A rule-set is a named collection of rules that can be applied to an interface. +Each rule is numbered, has an action to apply if the rule is matched, and the +ability to specify the criteria to match. Data packets go through the rules +from 1 - 999999, at the first match the action of the rule will be executed. + +```{eval-rst} +.. cfgcmd:: set policy route <name> description <text> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> description <text> + + Provide a rule-set description. +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> default-log +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> default-log + + Option to log packets hitting default-action. +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> description <text> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> description <text> + + Provide a description for each rule. +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> log <enable|disable> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> log <enable|disable> + + Option to enable or disable log matching rule. +``` + +### Matching criteria + +There are a lot of matching criteria options available, both for +`policy route` and `policy route6`. These options are listed +in this section. + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> connection-mark <1-2147483647> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> connection-mark <1-2147483647> + + Set match criteria based on connection mark. +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> source address + <match_criteria> +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> destination address + <match_criteria> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> source address + <match_criteria> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> destination address + <match_criteria> + + Set match criteria based on source or destination ipv4|ipv6 address, where + <match_criteria> could be: +``` + +For ipv4: +: - \<x.x.x.x>: IP address to match. + - \<x.x.x.x/x>: Subnet to match. + - \<x.x.x.x>-\<x.x.x.x>: IP range to match. + - !\<x.x.x.x>: Match everything except the specified address. + - !\<x.x.x.x/x>: Match everything except the specified subnet. + - !\<x.x.x.x>-\<x.x.x.x>: Match everything except the specified range. + +And for ipv6: +: - \<h:h:h:h:h:h:h:h>: IPv6 address to match. + - \<h:h:h:h:h:h:h:h/x>: IPv6 prefix to match. + - \<h:h:h:h:h:h:h:h>-\<h:h:h:h:h:h:h:h>: IPv6 range to match. + - !\<h:h:h:h:h:h:h:h>: Match everything except the specified address. + - !\<h:h:h:h:h:h:h:h/x>: Match everything except the specified prefix. + - !\<h:h:h:h:h:h:h:h>-\<h:h:h:h:h:h:h:h>: Match everything except the + specified range. + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> source group + <address-group|domain-group|mac-group|network-group|port-group> <text> +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> destination group + <address-group|domain-group|mac-group|network-group|port-group> <text> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> source group + <address-group|domain-group|mac-group|network-group|port-group> <text> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> destination group + <address-group|domain-group|mac-group|network-group|port-group> <text> + + Set match criteria based on source or destination groups, where <text> + would be the group name/identifier. Prepend character '!' for inverted + matching criteria. +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> destination port <match_criteria> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> destination port <match_criteria> + + Set match criteria based on destination port, where <match_criteria> could + be: + + * <port name>: Named port (any name in /etc/services, e.g., http). + * <1-65535>: Numbered port. + * <start>-<end>: Numbered port range (e.g., 1001-1005). + + Multiple destination ports can be specified as a comma-separated list. The + whole list can also be "negated" using '!'. For example: + '!22,telnet,http,123,1001-1005' +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> disable +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> disable + + Option to disable rule. +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> dscp <text> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> dscp <text> +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> dscp-exclude <text> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> dscp-exclude <text> + + Match based on dscp value criteria. Multiple values from 0 to 63 + and ranges are supported. +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> fragment + <match-grag|match-non-frag> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> fragment + <match-grag|match-non-frag> + + Set IP fragment match, where: + + * match-frag: Second and further fragments of fragmented packets. + * match-non-frag: Head fragments or unfragmented packets. +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> icmp <code | type> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> icmpv6 <code | type> + + Match based on icmp|icmpv6 code and type. +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> icmp type-name <text> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> icmpv6 type-name <text> + + Match based on icmp|icmpv6 type-name criteria. Use tab for information + about what type-name criteria are supported. +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> ipsec + <match-ipsec|match-none> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> ipsec + <match-ipsec|match-none> + + Set IPSec inbound match criterias, where: + + * match-ipsec: match inbound IPsec packets. + * match-none: match inbound non-IPsec packets. +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> limit burst <0-4294967295> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> limit burst <0-4294967295> + + Set maximum number of packets to alow in excess of rate. +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> limit rate <text> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> limit rate <text> + + Set maximum average matching rate. Format for rate: integer/time_unit, where + time_unit could be any one of second, minute, hour or day.For example + 1/second implies rule to be matched at an average of once per second. +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> protocol + <text | 0-255 | tcp_udp | all > +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> protocol + <text | 0-255 | tcp_udp | all > + + Match a protocol criteria. A protocol number or a name which is defined in: + ``/etc/protocols``. Special names are ``all`` for all protocols and + ``tcp_udp`` for tcp and udp based packets. The ``!`` negates the selected + protocol. +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> packet-length <text> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> packet-length <text> +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> packet-length-exclude <text> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> packet-length-exclude <text> + + Match based on packet length criteria. Multiple values from 1 to 65535 + and ranges are supported. +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> packet-type [broadcast | host + | multicast | other] +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> packet-type [broadcast | host + | multicast | other] + + Match based on packet type criteria. +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> recent time <1-4294967295> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> recent time <1-4294967295> + + Set parameters for matching recently seen sources. This match could be used + by seeting count (source address seen more than <1-255> times) and/or time + (source address seen in the last <0-4294967295> seconds). +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> state + <established | invalid | new | related> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> state + <established | invalid | new | related> + + Set match criteria based on session state. +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> tcp flags <text> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> tcp flags <text> + + Set match criteria based on tcp flags. Allowed values for TCP flags: SYN ACK + FIN RST URG PSH ALL. When specifying more than one flag, flags should be + comma-separated. For example : value of 'SYN,!ACK,!FIN,!RST' will only match + packets with the SYN flag set, and the ACK, FIN and RST flags unset. +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> time monthdays <text> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> time monthdays <text> +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> time startdate <text> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> time startdate <text> +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> time starttime <text> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> time starttime <text> +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> time stopdate <text> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> time stopdate <text> +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> time stoptime <text> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> time stoptime <text> +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> time weekdays <text> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> time weekdays <text> +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> time utc +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> time utc + + Time to match the defined rule. +``` + +```{eval-rst} +.. cfgcmd:: set policy route rule <n> ttl <eq | gt | lt> <0-255> + + Match time to live parameter, where 'eq' stands for 'equal'; 'gt' stands for + 'greater than', and 'lt' stands for 'less than'. +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 rule <n> hop-limit <eq | gt | lt> <0-255> + + Match hop-limit parameter, where 'eq' stands for 'equal'; 'gt' stands for + 'greater than', and 'lt' stands for 'less than'. +``` + +### Actions + +When mathcing all patterns defined in a rule, then different actions can +be made. This includes droping the packet, modifying certain data, or +setting a different routing table. + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> action drop +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> action drop + + Set rule action to drop. +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> set connection-mark + <1-2147483647> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> set connection-mark + <1-2147483647> + + Set a specific connection mark. +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> set dscp <0-63> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> set dscp <0-63> + + Set packet modifications: Packet Differentiated Services Codepoint (DSCP) +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> set mark <1-2147483647> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> set mark <1-2147483647> + + Set a specific packet mark. +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> set table <main | 1-200> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> set table <main | 1-200> + + Set the routing table to forward packet with. +``` + +```{eval-rst} +.. cfgcmd:: set policy route <name> rule <n> set tcp-mss <500-1460> +``` + +```{eval-rst} +.. cfgcmd:: set policy route6 <name> rule <n> set tcp-mss <500-1460> + + Set packet modifications: Explicitly set TCP Maximum segment size value. +``` diff --git a/docs/configuration/protocols/md-babel.md b/docs/configuration/protocols/md-babel.md new file mode 100644 index 00000000..b169e861 --- /dev/null +++ b/docs/configuration/protocols/md-babel.md @@ -0,0 +1,245 @@ +(babel)= + +# Babel + +Babel is a modern routing protocol designed to be robust and efficient +both in ordinary wired networks and in wireless mesh networks. +By default, it uses hop-count on wired networks and a variant of ETX +on wireless links, It can be configured to take radio diversity into account +and to automatically compute a link's latency and include it in the metric. +It is defined in {rfc}`8966`. + +Babel a dual stack protocol. +A single Babel instance is able to perform routing for both IPv4 and IPv6. + +## General Configuration + +VyOS does not have a special command to start the Babel process. +The Babel process starts when the first Babel enabled interface is configured. + +```{eval-rst} +.. cfgcmd:: set protocols babel interface <interface> + + This command specifies a Babel enabled interface by interface name. Both + the sending and receiving of Babel packets will be enabled on the interface + specified in this command. +``` + +## Optional Configuration + +```{eval-rst} +.. cfgcmd:: set protocols babel parameters diversity + + This command enables routing using radio frequency diversity. + This is highly recommended in networks with many wireless nodes. + + .. note:: If you enable this, you will probably want to + set diversity-factor and channel below. +``` + +```{eval-rst} +.. cfgcmd:: set protocols babel parameters diversity-factor <1-256> + + This command sets the multiplicative factor used for diversity routing, + in units of 1/256; lower values cause diversity to play a more important role + in route selection. + The default it 256, which means that diversity plays no role in route + selection; you will probably want to set that to 128 or less on nodes + with multiple independent radios. +``` + +```{eval-rst} +.. cfgcmd:: set protocols babel parameters resend-delay <milliseconds> + + This command specifies the time in milliseconds after which an 'important' + request or update will be resent. The default is 2000 ms. +``` + +```{eval-rst} +.. cfgcmd:: set protocols babel parameters smoothing-half-life <seconds> + + This command specifies the time constant, in seconds, of the smoothing + algorithm used for implementing hysteresis. + Larger values reduce route oscillation at the cost of very slightly increasing + convergence time. The value 0 disables hysteresis, and is suitable for wired + networks. The default is 4 s. +``` + +## Interfaces Configuration + +```{eval-rst} +.. cfgcmd:: set protocols babel interface <interface> type <auto|wired|wireless> + + This command sets the interface type: + + **auto** – automatically determines the interface type. + **wired** – enables optimisations for wired interfaces. + **wireless** – disables a number of optimisations that are only correct + on wired interfaces. Specifying wireless is always correct, + but may cause slower convergence and extra routing traffic. +``` + +```{eval-rst} +.. cfgcmd:: set protocols babel interface <interface> split-horizon <default|disable|enable> + + This command specifies whether to perform split-horizon on the interface. + Specifying no babel split-horizon is always correct, while babel split-horizon + is an optimisation that should only be used on symmetric + and transitive (wired) networks. + + **default** – enable split-horizon on wired interfaces, and disable + split-horizon on wireless interfaces. + **enable** – enable split-horizon on this interfaces. + **disable** – disable split-horizon on this interfaces. +``` + +```{eval-rst} +.. cfgcmd:: set protocols babel interface <interface> hello-interval <milliseconds> + + This command specifies the time in milliseconds between two scheduled hellos. + On wired links, Babel notices a link failure within two hello intervals; + on wireless links, the link quality value is reestimated at every hello + interval. + The default is 4000 ms. +``` + +```{eval-rst} +.. cfgcmd:: set protocols babel interface <interface> update-interval <milliseconds> + + This command specifies the time in milliseconds between two scheduled updates. + Since Babel makes extensive use of triggered updates, + this can be set to fairly high values on links with little packet loss. + The default is 20000 ms. +``` + +```{eval-rst} +.. cfgcmd:: set protocols babel interface <interface> rxcost <1-65534> + + This command specifies the base receive cost for this interface. + For wireless interfaces, it specifies the multiplier used for computing + the ETX reception cost (default 256); + for wired interfaces, it specifies the cost that will be advertised to + neighbours. +``` + +```{eval-rst} +.. cfgcmd:: set protocols babel interface <interface> rtt-decay <1-256> + + This command specifies the decay factor for the exponential moving average + of RTT samples, in units of 1/256. + Higher values discard old samples faster. The default is 42. +``` + +```{eval-rst} +.. cfgcmd:: set protocols babel interface <interface> rtt-min <milliseconds> + + This command specifies the minimum RTT, in milliseconds, + starting from which we increase the cost to a neighbour. + The additional cost is linear in (rtt - rtt-min). The default is 10 ms. +``` + +```{eval-rst} +.. cfgcmd:: set protocols babel interface <interface> rtt-max <milliseconds> + + This command specifies the maximum RTT, in milliseconds, above which + we don't increase the cost to a neighbour. The default is 120 ms. + +``` + +```{eval-rst} +.. cfgcmd:: set protocols babel interface <interface> max-rtt-penalty <milliseconds> + + This command specifies the maximum cost added to a neighbour because of RTT, + i.e. when the RTT is higher or equal than rtt-max. + The default is 150. + Setting it to 0 effectively disables the use of a RTT-based cost. +``` + +```{eval-rst} +.. cfgcmd:: set protocols babel interface <interface> enable-timestamps + + This command enables sending timestamps with each Hello and IHU message + in order to compute RTT values. + It is recommended to enable timestamps on tunnel interfaces. +``` + +```{eval-rst} +.. cfgcmd:: set protocols babel interface <interface> channel <1-254|interfering|noninterfering> + + This command set the channel number that diversity routing uses for this + interface (see diversity option above). + + **1-254** – interfaces with a channel number interfere with + interfering interfaces and interfaces with the same channel number. + **interfering** – interfering interfaces are assumed to interfere with all other channels except + noninterfering channels. + **noninterfering** – noninterfering interfaces are assumed to only interfere + with themselves. +``` + +## Redistribution Configuration + +```{eval-rst} +.. cfgcmd:: set protocols babel redistribute <ipv4|ipv6> <route source> + + This command redistributes routing information from the given route source + to the Babel process. + + IPv4 route source: bgp, connected, eigrp, isis, kernel, nhrp, ospf, rip, static. + + IPv6 route source: bgp, connected, eigrp, isis, kernel, nhrp, ospfv3, ripng, static. +``` + +```{eval-rst} +.. cfgcmd:: set protocols babel distribute-list <ipv4|ipv6> access-list <in|out> <number> + + This command can be used to filter the Babel routes using access lists. + {cfgcmd}`in` and {cfgcmd}`out` this is the direction in which the access + lists are applied. +``` + +```{eval-rst} +.. cfgcmd:: set protocols babel distribute-list <ipv4|ipv6> interface <interface> access-list <in|out> <number> + + This command allows you apply access lists to a chosen interface to + filter the Babel routes. +``` + +```{eval-rst} +.. cfgcmd:: set protocols babel distribute-list <ipv4|ipv6> prefix-list <in|out> <name> + + This command can be used to filter the Babel routes using prefix lists. + {cfgcmd}`in` and {cfgcmd}`out` this is the direction in which the prefix + lists are applied. +``` + +```{eval-rst} +.. cfgcmd:: set protocols babel distribute-list <ipv4|ipv6> interface <interface> prefix-list <in|out> <name> + + This command allows you apply prefix lists to a chosen interface to + filter the Babel routes. +``` + +## Configuration Example + +Simple Babel configuration using 2 nodes and redistributing connected interfaces. + +**Node 1:** + +```none +set interfaces loopback lo address 10.1.1.1/32 +set interfaces loopback lo address fd12:3456:dead:beef::1/128 +set protocols babel interface eth0 type wired +set protocols babel redistribute ipv4 connected +set protocols babel redistribute ipv6 connected +``` + +**Node 2:** + +```none +set interfaces loopback lo address 10.2.2.2/32 +set interfaces loopback lo address fd12:3456:beef:dead::2/128 +set protocols babel interface eth0 type wired +set protocols babel redistribute ipv4 connected +set protocols babel redistribute ipv6 connected +``` diff --git a/docs/configuration/protocols/md-bfd.md b/docs/configuration/protocols/md-bfd.md new file mode 100644 index 00000000..13623e03 --- /dev/null +++ b/docs/configuration/protocols/md-bfd.md @@ -0,0 +1,205 @@ +--- +lastproofread: '2023-01-27' +--- + +```{include} /_include/need_improvement.txt +``` + +(routing-bfd)= + +# BFD + +{abbr}`BFD (Bidirectional Forwarding Detection)` is described and extended by +the following RFCs: {rfc}`5880`, {rfc}`5881` and {rfc}`5883`. + +In the age of very fast networks, a second of unreachability may equal millions of lost packets. +The idea behind BFD is to detect very quickly when a peer is down and take action extremely fast. + +BFD sends lots of small UDP packets very quickly to ensures that the peer is still alive. + +This allows avoiding the timers defined in BGP and OSPF protocol to expires. + +## Configure BFD + +```{cfgcmd} set protocols bfd peer \<address\> + +Set BFD peer IPv4 address or IPv6 address +``` + +```{cfgcmd} set protocols bfd peer \<address\> echo-mode + +Enables the echo transmission mode +``` + +```{cfgcmd} set protocols bfd peer \<address\> multihop + +Allow this BFD peer to not be directly connected +``` + +```{cfgcmd} set protocols bfd peer \<address\> source [address \<address\> | interface \<interface\>] + +Bind listener to specific interface/address, mandatory for IPv6 +``` + +```{cfgcmd} set protocols bfd peer \<address\> interval echo-interval \<10-60000\> + +The minimal echo receive transmission interval that this system is +capable of handling +``` + +```{cfgcmd} set protocols bfd peer \<address\> interval multiplier \<2-255\> + +Remote transmission interval will be multiplied by this value +``` + +```{cfgcmd} set protocols bfd peer \<address\> interval [receive | transmit] \<10-60000\> + +Interval in milliseconds +``` + +```{cfgcmd} set protocols bfd peer \<address\> shutdown + +Disable a BFD peer +``` + +```{cfgcmd} set protocols bfd peer \<address\> minimum-ttl \<1-254\> + +For multi hop sessions only. Configure the minimum expected TTL for an +incoming BFD control packet. + +This feature serves the purpose of thightening the packet validation +requirements to avoid receiving BFD control packets from other sessions. +``` + +### Enable BFD in BGP + +```{cfgcmd} set protocols bgp neighbor \<neighbor\> bfd + +Enable BFD on a single BGP neighbor +``` + +```{cfgcmd} set protocols bgp peer-group \<neighbor\> bfd + +Enable BFD on a BGP peer group +``` + +### Enable BFD in OSPF + +```{cfgcmd} set protocols ospf interface \<interface\> bfd + + Enable BFD for OSPF on an interface + +``` + +```{cfgcmd} set protocols ospfv3 interface \<interface\> bfd + +Enable BFD for OSPFv3 on an interface +``` + +### Enable BFD in ISIS + +```{cfgcmd} set protocols isis \<name\> interface \<interface\> bfd + +Enable BFD for ISIS on an interface + +``` + +## Operational Commands + +```{opcmd} show bfd peers + + Show all BFD peers + + :::{code-block} none + BFD Peers: + peer 198.51.100.33 vrf default interface eth4.100 + ID: 4182341893 + Remote ID: 12678929647 + Status: up + Uptime: 1 month(s), 16 hour(s), 29 minute(s), 38 second(s) + Diagnostics: ok + Remote diagnostics: ok + Local timers: + Receive interval: 300ms + Transmission interval: 300ms + Echo transmission interval: 50ms + Remote timers: + Receive interval: 300ms + Transmission interval: 300ms + Echo transmission interval: 0ms + + peer 198.51.100.55 vrf default interface eth4.101 + ID: 4618932327 + Remote ID: 3312345688 + Status: up + Uptime: 20 hour(s), 16 minute(s), 19 second(s) + Diagnostics: ok + Remote diagnostics: ok + Local timers: + Receive interval: 300ms + Transmission interval: 300ms + Echo transmission interval: 50ms + Remote timers: + Receive interval: 300ms + Transmission interval: 300ms + Echo transmission interval: 0ms + ::: +``` + +## BFD Static Route Monitoring + + +A monitored static route conditions the installation to the RIB on the BFD +session running state: when BFD session is up the route is installed to RIB, +but when the BFD session is down it is removed from the RIB. + + +### Configuration + +```{cfgcmd} set protocols static route \<subnet\> next-hop \<address\> bfd profile \<profile\> + +Configure a static route for \<subnet\> using gateway \<address\> +and use the gateway address as BFD peer destination address. +``` + +```{cfgcmd} set protocols static route \<subnet\> next-hop \<address\> bfd multi-hop source \<address\> profile \<profile\> + +Configure a static route for \<subnet\> using gateway \<address\>, +use source address to identify the peer when is multi-hop session +and the gateway address as BFD peer destination address. +``` + +```{cfgcmd} set protocols static route6 \<subnet\> next-hop \<address\> bfd profile \<profile\> + +Configure a static route for \<subnet\> using gateway \<address\> +and use the gateway address as BFD peer destination address. +``` + +```{cfgcmd} set protocols static route6 \<subnet\> next-hop \<address\> bfd multi-hop source \<address\> profile \<profile\> + +Configure a static route for \<subnet\> using gateway \<address\>, +use source address to identify the peer when is multi-hop session +and the gateway address as BFD peer destination address. +``` + +(bfd-operational-commands)= + +## Operational Commands + +```{opcmd} show bfd static routes + +Showing BFD monitored static routes + +:::{code-block} none +Showing BFD monitored static routes: + + Next hops: + VRF default IPv4 Unicast: + 10.10.13.3/32 peer 192.168.2.3 (status: installed) + 172.16.10.3/32 peer 192.168.10.1 (status: uninstalled) + + VRF default IPv4 Multicast: + + VRF default IPv6 Unicast: +::: +```
\ No newline at end of file diff --git a/docs/configuration/protocols/md-bgp.md b/docs/configuration/protocols/md-bgp.md new file mode 100644 index 00000000..c8f77a6a --- /dev/null +++ b/docs/configuration/protocols/md-bgp.md @@ -0,0 +1,1435 @@ +(routing-bgp)= + +# BGP + +{abbr}`BGP (Border Gateway Protocol)` is one of the Exterior Gateway Protocols +and the de facto standard interdomain routing protocol. The latest BGP version +is 4. BGP-4 is described in {rfc}`1771` and updated by {rfc}`4271`. {rfc}`2858` +adds multiprotocol support to BGP. + +VyOS makes use of {abbr}`FRR (Free Range Routing)` and we would like to thank +them for their effort! + +## Basic Concepts + +(bgp-autonomous-systems)= + +### Autonomous Systems + +From {rfc}`1930`: + +> An AS is a connected group of one or more IP prefixes run by one or more +> network operators which has a SINGLE and CLEARLY DEFINED routing policy. + +Each {abbr}`AS (Autonomous System)` has an identifying number associated with it +called an {abbr}`ASN (Autonomous System Number)`. This is a two octet value +ranging in value from 1 to 65535. The AS numbers 64512 through 65535 are defined +as private AS numbers. Private AS numbers must not be advertised on the global +Internet. The 2-byte AS number range has been exhausted. 4-byte AS numbers are +specified in {rfc}`6793`, and provide a pool of 4294967296 AS numbers. + +The {abbr}`ASN (Autonomous System Number)` is one of the essential elements of +BGP. BGP is a distance vector routing protocol, and the AS-Path framework +provides distance vector metric and loop detection to BGP. + +```{eval-rst} +.. cfgcmd:: set protocols bgp system-as <asn> + + Set local {abbr}`ASN (Autonomous System Number)` that this router represents. + This is a a mandatory option! +``` + +(bgp-address-families)= + +### Address Families + +Multiprotocol extensions enable BGP to carry routing information for multiple +network layer protocols. BGP supports an Address Family Identifier (AFI) for +IPv4 and IPv6. + +(bgp-route-selection)= + +### Route Selection + +The route selection process used by FRR's BGP implementation uses the following +decision criterion, starting at the top of the list and going towards the +bottom until one of the factors can be used. + +01. **Weight check** + + Prefer higher local weight routes to lower routes. + +02. **Local preference check** + + Prefer higher local preference routes to lower. + +03. **Local route check** + + Prefer local routes (statics, aggregates, redistributed) to received routes. + +04. **AS path length check** + + Prefer shortest hop-count AS_PATHs. + +05. **Origin check** + + Prefer the lowest origin type route. That is, prefer IGP origin routes to + EGP, to Incomplete routes. + +06. **MED check** + + Where routes with a MED were received from the same AS, prefer the route + with the lowest MED. + +07. **External check** + + Prefer the route received from an external, eBGP peer over routes received + from other types of peers. + +08. **IGP cost check** + + Prefer the route with the lower IGP cost. + +09. **Multi-path check** + + If multi-pathing is enabled, then check whether the routes not yet + distinguished in preference may be considered equal. If + {cfgcmd}`bgp bestpath as-path multipath-relax` is set, all such routes are + considered equal, otherwise routes received via iBGP with identical AS_PATHs + or routes received from eBGP neighbours in the same AS are considered equal. + +10. **Already-selected external check** + + Where both routes were received from eBGP peers, then prefer the route + which is already selected. Note that this check is not applied if + {cfgcmd}`bgp bestpath compare-routerid` is configured. This check can + prevent some cases of oscillation. + +11. **Router-ID check** + + Prefer the route with the lowest `router-ID`. If the route has an + `ORIGINATOR_ID` attribute, through iBGP reflection, then that router ID is + used, otherwise the `router-ID` of the peer the route was received from is + used. + +12. **Cluster-List length check** + + The route with the shortest cluster-list length is used. The cluster-list + reflects the iBGP reflection path the route has taken. + +13. **Peer address** + + Prefer the route received from the peer with the higher transport layer + address, as a last-resort tie-breaker. + +(bgp-capability-negotiation)= + +### Capability Negotiation + +When adding IPv6 routing information exchange feature to BGP. There were some +proposals. {abbr}`IETF (Internet Engineering Task Force)` +{abbr}`IDR (Inter Domain Routing)` adopted a proposal called Multiprotocol +Extension for BGP. The specification is described in {rfc}`2283`. The protocol +does not define new protocols. It defines new attributes to existing BGP. When +it is used exchanging IPv6 routing information it is called BGP-4+. When it is +used for exchanging multicast routing information it is called MBGP. + +*bgpd* supports Multiprotocol Extension for BGP. So if a remote peer supports +the protocol, *bgpd* can exchange IPv6 and/or multicast routing information. + +Traditional BGP did not have the feature to detect a remote peer's +capabilities, e.g. whether it can handle prefix types other than IPv4 unicast +routes. This was a big problem using Multiprotocol Extension for BGP in an +operational network. {rfc}`2842` adopted a feature called Capability +Negotiation. *bgpd* use this Capability Negotiation to detect the remote peer's +capabilities. If a peer is only configured as an IPv4 unicast neighbor, *bgpd* +does not send these Capability Negotiation packets (at least not unless other +optional BGP features require capability negotiation). + +By default, FRR will bring up peering with minimal common capability for the +both sides. For example, if the local router has unicast and multicast +capabilities and the remote router only has unicast capability the local router +will establish the connection with unicast only capability. When there are no +common capabilities, FRR sends Unsupported Capability error and then resets the +connection. + +## Configuration + +(bgp-router-configuration)= + +### BGP Router Configuration + +First of all you must configure BGP router with the {abbr}`ASN (Autonomous +System Number)`. The AS number is an identifier for the autonomous system. +The BGP protocol uses the AS number for detecting whether the BGP connection +is internal or external. VyOS does not have a special command to start the BGP +process. The BGP process starts when the first neighbor is configured. + +```{eval-rst} +.. cfgcmd:: set protocols bgp system-as <asn> + + Set local autonomous system number that this router represents. This is a + mandatory option! +``` + +#### Peers Configuration + +##### Defining Peers + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> remote-as + <nasn> + + This command creates a new neighbor whose remote-as is <nasn>. The neighbor + address can be an IPv4 address or an IPv6 address or an interface to use + for the connection. The command is applicable for peer and peer group. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> remote-as + internal + + Create a peer as you would when you specify an ASN, except that if the + peers ASN is different than mine as specified under the {cfgcmd}`protocols + bgp <asn>` command the connection will be denied. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> remote-as + external + + Create a peer as you would when you specify an ASN, except that if the + peers ASN is the same as mine as specified under the {cfgcmd}`protocols + bgp <asn>` command the connection will be denied. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> local-role + <role> [strict] + + BGP roles are defined in RFC {rfc}`9234` and provide an easy way to + add route leak prevention, detection and mitigation. The local Role + value is negotiated with the new BGP Role capability which has a + built-in check of the corresponding value. In case of a mismatch the + new OPEN Roles Mismatch Notification <2, 11> would be sent. + The correct Role pairs are: + + Provider - Customer + + Peer - Peer + + RS-Server - RS-Client + + If {cfgcmd}`strict` is set the BGP session won’t become established + until the BGP neighbor sets local Role on its side. This + configuration parameter is defined in RFC {rfc}`9234` and is used to + enforce the corresponding configuration at your counter-parts side. + + Routes that are sent from provider, rs-server, or the peer local-role + (or if received by customer, rs-client, or the peer local-role) will + be marked with a new Only to Customer (OTC) attribute. + + Routes with this attribute can only be sent to your neighbor if your + local-role is provider or rs-server. Routes with this attribute can + be received only if your local-role is customer or rs-client. + + In case of peer-peer relationship routes can be received only if OTC + value is equal to your neighbor AS number. + + All these rules with OTC will help to detect and mitigate route leaks + and happen automatically if local-role is set. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> shutdown + + This command disable the peer or peer group. To reenable the peer use + the delete form of this command. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> description + <text> + + Set description of the peer or peer group. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> update-source + <address|interface> + + Specify the IPv4 source address to use for the BGP session to this neighbor, + may be specified as either an IPv4 address directly or as an interface name. +``` + +(bgp-capability-negotiation-1)= + +##### Capability Negotiation + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> capability + dynamic + + This command would allow the dynamic update of capabilities over an + established BGP session. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> capability + extended-nexthop + + Allow bgp to negotiate the extended-nexthop capability with it’s peer. + If you are peering over a IPv6 Link-Local address then this capability + is turned on automatically. If you are peering over a IPv6 Global Address + then turning on this command will allow BGP to install IPv4 routes with + IPv6 nexthops if you do not have IPv4 configured on interfaces. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> + disable-capability-negotiation + + Suppress sending Capability Negotiation as OPEN message optional + parameter to the peer. This command only affects the peer is + configured other than IPv4 unicast configuration. + + When remote peer does not have capability negotiation feature, + remote peer will not send any capabilities at all. In that case, + bgp configures the peer with configured capabilities. + + You may prefer locally configured capabilities more than the negotiated + capabilities even though remote peer sends capabilities. If the peer is + configured by {cfgcmd}`override-capability`, VyOS ignores received + capabilities then override negotiated capabilities with configured values. + + Additionally you should keep in mind that this feature fundamentally + disables the ability to use widely deployed BGP features. BGP unnumbered, + hostname support, AS4, Addpath, Route Refresh, ORF, Dynamic Capabilities, + and graceful restart. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> + override-capability + + This command allow override the result of Capability Negotiation with + local configuration. Ignore remote peer’s capability value. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> + strict-capability-match + + This command forces strictly compare remote capabilities and local + capabilities. If capabilities are different, send Unsupported Capability + error then reset connection. + + You may want to disable sending Capability Negotiation OPEN message + optional parameter to the peer when remote peer does not implement + Capability Negotiation. Please use {cfgcmd}`disable-capability-negotiation` + command to disable the feature. + +``` + +##### Peer Parameters + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> allowas-in number <number> + + This command accept incoming routes with AS path containing AS + number with the same value as the current system AS. This is + used when you want to use the same AS number in your sites, + but you can’t connect them directly. + + The number parameter (1-10) configures the amount of accepted + occurences of the system AS number in AS path. + + This command is only allowed for eBGP peers. It is not applicable + for peer groups. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> as-override + + This command override AS number of the originating router with + the local AS number. + + Usually this configuration is used in PEs (Provider Edge) to + replace the incoming customer AS number so the connected CE ( + Customer Edge) can use the same AS number as the other customer + sites. This allows customers of the provider network to use the + same AS number across their sites. + + This command is only allowed for eBGP peers. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> attribute-unchanged <as-path|med|next-hop> + + This command specifies attributes to be left unchanged for + advertisements sent to a peer or peer group. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> maximum-prefix <number> + + This command specifies a maximum number of prefixes we can receive + from a given peer. If this number is exceeded, the BGP session + will be destroyed. The number range is 1 to 4294967295. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> nexthop-self + + This command forces the BGP speaker to report itself as the + next hop for an advertised route it advertised to a neighbor. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> remove-private-as + + This command removes the private ASN of routes that are advertised + to the configured peer. It removes only private ASNs on routes + advertised to EBGP peers. + + If the AS-Path for the route has only private ASNs, the private + ASNs are removed. + + If the AS-Path for the route has a private ASN between public + ASNs, it is assumed that this is a design choice, and the + private ASN is not removed. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> soft-reconfiguration inbound + + Changes in BGP policies require the BGP session to be cleared. Clearing has a + large negative impact on network operations. Soft reconfiguration enables you + to generate inbound updates from a neighbor, change and activate BGP policies + without clearing the BGP session. + + This command specifies that route updates received from this neighbor will be + stored unmodified, regardless of the inbound policy. When inbound soft + reconfiguration is enabled, the stored updates are processed by the new + policy configuration to create new inbound updates. + + .. note:: Storage of route updates uses memory. If you enable soft + reconfiguration inbound for multiple neighbors, the amount of memory used + can become significant. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> weight <number> + + This command specifies a default weight value for the neighbor’s + routes. The number range is 1 to 65535. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> + advertisement-interval <seconds> + + This command specifies the minimum route advertisement interval for + the peer. The interval value is 0 to 600 seconds, with the default + advertisement interval being 0. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> + disable-connected-check + + This command allows peerings between directly connected eBGP peers + using loopback addresses without adjusting the default TTL of 1. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> + disable-send-community <extended|standard> + + This command specifies that the community attribute should not be sent + in route updates to a peer. By default community attribute is sent. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> ebgp-multihop + <number> + + This command allows sessions to be established with eBGP neighbors + when they are multiple hops away. When the neighbor is not directly + connected and this knob is not enabled, the session will not establish. + The number of hops range is 1 to 255. This command is mutually + exclusive with {cfgcmd}`ttl-security hops`. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> local-as <asn> + [no-prepend] [replace-as] + + Specify an alternate AS for this BGP process when interacting with + the specified peer or peer group. With no modifiers, the specified + local-as is prepended to the received AS_PATH when receiving routing + updates from the peer, and prepended to the outgoing AS_PATH (after + the process local AS) when transmitting local routes to the peer. + + If the {cfgcmd}`no-prepend` attribute is specified, then the supplied + local-as is not prepended to the received AS_PATH. + + If the {cfgcmd}`replace-as` attribute is specified, then only the supplied + local-as is prepended to the AS_PATH when transmitting local-route + updates to this peer. + + .. note:: This command is only allowed for eBGP peers. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> passive + + Configures the BGP speaker so that it only accepts inbound connections + from, but does not initiate outbound connections to the peer or peer group. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> password + <text> + + This command specifies a MD5 password to be used with the tcp socket that + is being used to connect to the remote peer. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> ttl-security + hops <number> + + This command enforces Generalized TTL Security Mechanism (GTSM), + as specified in {rfc}`5082`. With this command, only neighbors + that are specified number of hops away will be allowed to + become neighbors. The number of hops range is 1 to 254. This + command is mutually exclusive with {cfgcmd}`ebgp-multihop`. + +``` + +##### Peer Groups + +Peer groups are used to help improve scaling by generating the same update +information to all members of a peer group. Note that this means that the +routes generated by a member of a peer group will be sent back to that +originating peer with the originator identifier attribute set to indicated +the originating peer. All peers not associated with a specific peer group +are treated as belonging to a default peer group, and will share updates. + +```{eval-rst} +.. cfgcmd:: set protocols bgp peer-group <name> + + This command defines a new peer group. You can specify to the group the same + parameters that you can specify for specific neighbors. + + .. note:: If you apply a parameter to an individual neighbor IP address, you + override the action defined for a peer group that includes that IP + address. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> peer-group + <name> + + This command bind specific peer to peer group with a given name. + +``` + +#### Network Advertisement Configuration + +```{eval-rst} +.. cfgcmd:: set protocols bgp address-family <ipv4-unicast|ipv6-unicast> + network <prefix> + + This command is used for advertising IPv4 or IPv6 networks. + + .. note:: By default, the BGP prefix is advertised even if it's not present + in the routing table. This behaviour differs from the implementation of + some vendors. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp parameters network-import-check + + This configuration modifies the behavior of the network statement. If you + have this configured the underlying network must exist in the routing table. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> default-originate [route-map <name>] + + By default, VyOS does not advertise a default route (0.0.0.0/0) even if it is + in routing table. When you want to announce default routes to the peer, use + this command. Using optional argument {cfgcmd}`route-map` you can inject the + default route to given neighbor only if the conditions in the route map are + met. + +``` + +#### Route Aggregation Configuration + +```{eval-rst} +.. cfgcmd:: set protocols bgp address-family <ipv4-unicast|ipv6-unicast> + aggregate-address <prefix> + + This command specifies an aggregate address. The router will also + announce longer-prefixes inside of the aggregate address. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp address-family <ipv4-unicast|ipv6-unicast> + aggregate-address <prefix> as-set + + This command specifies an aggregate address with a mathematical set of + autonomous systems. This command summarizes the AS_PATH attributes of + all the individual routes. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp address-family <ipv4-unicast|ipv6-unicast> + aggregate-address <prefix> summary-only + + This command specifies an aggregate address and provides that + longer-prefixes inside of the aggregate address are suppressed + before sending BGP updates out to peers. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> unsuppress-map <name> + + This command applies route-map to selectively unsuppress prefixes + suppressed by summarisation. + +``` + +#### Redistribution Configuration + +```{eval-rst} +.. cfgcmd:: set protocols bgp address-family <ipv4-unicast|ipv6-unicast> + redistribute <route source> + + This command redistributes routing information from the given route source + to the BGP process. There are six modes available for route source: + connected, kernel, ospf, rip, static, table. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp address-family <ipv4-unicast|ipv6-unicast> + redistribute <route source> metric <number> + + This command specifies metric (MED) for redistributed routes. The + metric range is 0 to 4294967295. There are six modes available for + route source: connected, kernel, ospf, rip, static, table. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp address-family <ipv4-unicast|ipv6-unicast> + redistribute <route source> route-map <name> + + This command allows to use route map to filter redistributed routes. + There are six modes available for route source: connected, kernel, + ospf, rip, static, table. + +``` + +#### General Configuration + +##### Common parameters + +```{eval-rst} +.. cfgcmd:: set protocols bgp parameters allow-martian-nexthop + + When a peer receives a martian nexthop as part of the NLRI for a route + permit the nexthop to be used as such, instead of rejecting and resetting + the connection. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp parameters router-id <id> + + This command specifies the router-ID. If router ID is not specified it will + use the highest interface IP address. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp address-family <ipv4-unicast|ipv6-unicast> + maximum-paths <ebgp|ibgp> <number> + + This command defines the maximum number of parallel routes that + the BGP can support. In order for BGP to use the second path, the + following attributes have to match: Weight, Local Preference, AS + Path (both AS number and AS path length), Origin code, MED, IGP + metric. Also, the next hop address for each path must be different. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp parameters no-hard-administrative-reset + + Do not send Hard Reset CEASE Notification for "Administrative Reset" + events. When set and Graceful Restart Notification capability is exchanged + between the peers, Graceful Restart procedures apply, and routes will be retained. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp parameters log-neighbor-changes + + This command enable logging neighbor up/down changes and reset reason. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp parameters no-client-to-client-reflection + + This command disables route reflection between route reflector clients. + By default, the clients of a route reflector are not required to be + fully meshed and the routes from a client are reflected to other clients. + However, if the clients are fully meshed, route reflection is not required. + In this case, use the {cfgcmd}`no-client-to-client-reflection` command + to disable client-to-client reflection. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp parameters no-fast-external-failover + + Disable immediate session reset if peer's connected link goes down. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp parameters no-ipv6-auto-ra + + By default, FRR sends router advertisement packets when Extended Next Hop is + on or when a connection is established directly using the device name (Unnumbered BGP). + Setting this option prevents FRR from sending router advertisement packets, but could break Unnumbered BGP. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp listen range <prefix> peer-group <name> + + This command is useful if one desires to loosen the requirement for BGP + to have strictly defined neighbors. Specifically what is allowed is for + the local router to listen to a range of IPv4 or IPv6 addresses defined + by a prefix and to accept BGP open messages. When a TCP connection + (and subsequently a BGP open message) from within this range tries to + connect the local router then the local router will respond and connect + with the parameters that are defined within the peer group. One must define + a peer-group for each range that is listed. If no peer-group is defined + then an error will keep you from committing the configuration. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp listen limit <number> + + This command goes hand in hand with the listen range command to limit the + amount of BGP neighbors that are allowed to connect to the local router. + The limit range is 1 to 5000. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp parameters ebgp-requires-policy + + This command changes the eBGP behavior of FRR. By default FRR enables + {rfc}`8212` functionality which affects how eBGP routes are advertised, + namely no routes are advertised across eBGP sessions without some + sort of egress route-map/policy in place. In VyOS however we have this + RFC functionality disabled by default so that we can preserve backwards + compatibility with older versions of VyOS. With this option one can + enable {rfc}`8212` functionality to operate. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp parameters labeled-unicast <explicit-null | + ipv4-explicit-null | ipv6-explicit-null> + + By default, locally advertised prefixes use the implicit-null label to + encode in the outgoing NLRI. + + The following command uses the explicit-null label value for all the + BGP instances. + +``` + +##### Administrative Distance + +```{eval-rst} +.. cfgcmd:: set protocols bgp parameters distance global + <external|internal|local> <distance> + + This command change distance value of BGP. The arguments are the distance + values for external routes, internal routes and local routes respectively. + The distance range is 1 to 255. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp parameters distance prefix <subnet> + distance <distance> + + This command sets the administrative distance for a particular route. The + distance range is 1 to 255. + + .. note:: Routes with a distance of 255 are effectively disabled and not + installed into the kernel. + +``` + +##### Timers + +```{eval-rst} +.. cfgcmd:: set protocols bgp timers holdtime <seconds> + + This command specifies hold-time in seconds. The timer range is + 4 to 65535. The default value is 180 second. If you set value to 0 + VyOS will not hold routes. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp timers keepalive <seconds> + + This command specifies keep-alive time in seconds. The timer + can range from 4 to 65535. The default value is 60 second. + +``` + +##### Route Dampening + +When a route fails, a routing update is sent to withdraw the route from the +network's routing tables. When the route is re-enabled, the change in +availability is also advertised. A route that continually fails and returns +requires a great deal of network traffic to update the network about the +route's status. + +Route dampening wich described in {rfc}`2439` enables you to identify routes +that repeatedly fail and return. If route dampening is enabled, an unstable +route accumulates penalties each time the route fails and returns. If the +accumulated penalties exceed a threshold, the route is no longer advertised. +This is route suppression. Routes that have been suppressed are re-entered +into the routing table only when the amount of their penalty falls below a +threshold. + +A penalty of 1000 is assessed each time the route fails. When the penalties +reach a predefined threshold (suppress-value), the router stops advertising +the route. + +Once a route is assessed a penalty, the penalty is decreased by half each time +a predefined amount of time elapses (half-life-time). When the accumulated +penalties fall below a predefined threshold (reuse-value), the route is +unsuppressed and added back into the BGP routing table. + +No route is suppressed indefinitely. Maximum-suppress-time defines the maximum +time a route can be suppressed before it is re-advertised. + +```{eval-rst} +.. cfgcmd:: set protocols bgp parameters dampening + half-life <minutes> + + This command defines the amount of time in minutes after + which a penalty is reduced by half. The timer range is + 10 to 45 minutes. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp parameters dampening + re-use <seconds> + + This command defines the accumulated penalty amount at which the + route is re-advertised. The penalty range is 1 to 20000. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp parameters dampening + start-suppress-time <seconds> + + This command defines the accumulated penalty amount at which the + route is suppressed. The penalty range is 1 to 20000. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp parameters dampening + max-suppress-time <seconds> + + This command defines the maximum time in minutes that a route is + suppressed. The timer range is 1 to 255 minutes. + +``` + +#### Route Selection Configuration + +```{eval-rst} +.. cfgcmd:: set protocols bgp parameters always-compare-med + + This command provides to compare the MED on routes, even when they were + received from different neighbouring ASes. Setting this option makes the + order of preference of routes more defined, and should eliminate MED + induced oscillations. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp parameters bestpath as-path confed + + This command specifies that the length of confederation path sets and + sequences should be taken into account during the BGP best path + decision process. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp parameters bestpath as-path multipath-relax + + This command specifies that BGP decision process should consider paths + of equal AS_PATH length candidates for multipath computation. Without + the knob, the entire AS_PATH must match for multipath computation. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp parameters bestpath as-path ignore + + Ignore AS_PATH length when selecting a route +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp parameters bestpath compare-routerid + + Ensure that when comparing routes where both are equal on most metrics, + including local-pref, AS_PATH length, IGP cost, MED, that the tie is + broken based on router-ID. + + If this option is enabled, then the already-selected check, where + already selected eBGP routes are preferred, is skipped. + + If a route has an ORIGINATOR_ID attribute because it has been reflected, + that ORIGINATOR_ID will be used. Otherwise, the router-ID of the peer + the route was received from will be used. + + The advantage of this is that the route-selection (at this point) will + be more deterministic. The disadvantage is that a few or even one lowest-ID + router may attract all traffic to otherwise-equal paths because of this + check. It may increase the possibility of MED or IGP oscillation, unless + other measures were taken to avoid these. The exact behaviour will be + sensitive to the iBGP and reflection topology. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp parameters bestpath med confed + + This command specifies that BGP considers the MED when comparing routes + originated from different sub-ASs within the confederation to which this + BGP speaker belongs. The default state, where the MED attribute is not + considered. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp parameters bestpath med missing-as-worst + + This command specifies that a route with a MED is always considered to be + better than a route without a MED by causing the missing MED attribute to + have a value of infinity. The default state, where the missing MED + attribute is considered to have a value of zero. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp parameters default local-pref + <local-pref value> + + This command specifies the default local preference value. The local + preference range is 0 to 4294967295. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp parameters deterministic-med + + This command provides to compare different MED values that advertised by + neighbours in the same AS for routes selection. When this command is + enabled, routes from the same autonomous system are grouped together, and + the best entries of each group are compared. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp address-family ipv4-unicast network + <prefix> backdoor + + This command allows the router to prefer route to specified prefix learned + via IGP through backdoor link instead of a route to the same prefix learned + via EBGP. + +``` + +#### Route Filtering Configuration + +In order to control and modify routing information that is exchanged between +peers you can use route-map, filter-list, prefix-list, distribute-list. + +For inbound updates the order of preference is: + +> - route-map +> - filter-list +> - prefix-list, distribute-list + +For outbound updates the order of preference is: + +> - prefix-list, distribute-list +> - filter-list +> - route-map +> +> :::{note} +> The attributes {cfgcmd}`prefix-list` and {cfgcmd}`distribute-list` +> are mutually exclusive, and only one command (distribute-list or +> prefix-list) can be applied to each inbound or outbound direction for a +> particular neighbor. +> ::: + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> distribute-list <export|import> <number> + + This command applies the access list filters named in <number> to the + specified BGP neighbor to restrict the routing information that BGP learns + and/or advertises. The arguments {cfgcmd}`export` and {cfgcmd}`import` + specify the direction in which the access list are applied. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> prefix-list <export|import> <name> + + This command applies the prfefix list filters named in <name> to the + specified BGP neighbor to restrict the routing information that BGP learns + and/or advertises. The arguments {cfgcmd}`export` and {cfgcmd}`import` + specify the direction in which the prefix list are applied. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> route-map <export|import> <name> + + This command applies the route map named in <name> to the specified BGP + neighbor to control and modify routing information that is exchanged + between peers. The arguments {cfgcmd}`export` and {cfgcmd}`import` + specify the direction in which the route map are applied. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> filter-list <export|import> <name> + + This command applies the AS path access list filters named in <name> to the + specified BGP neighbor to restrict the routing information that BGP learns + and/or advertises. The arguments {cfgcmd}`export` and {cfgcmd}`import` + specify the direction in which the AS path access list are applied. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> capability orf <receive|send> + + This command enables the ORF capability (described in {rfc}`5291`) on the + local router, and enables ORF capability advertisement to the specified BGP + peer. The {cfgcmd}`receive` keyword configures a router to advertise ORF + receive capabilities. The {cfgcmd}`send` keyword configures a router to + advertise ORF send capabilities. To advertise a filter from a sender, you + must create an IP prefix list for the specified BGP peer applied in inbound + derection. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address|interface> solo + + This command prevents from sending back prefixes learned from the neighbor. +``` + +#### BGP Scaling Configuration + +BGP routers connected inside the same AS through BGP belong to an internal BGP +session, or IBGP. In order to prevent routing table loops, IBGP speaker does +not advertise IBGP-learned routes to other IBGP speaker (Split Horizon +mechanism). As such, IBGP requires a full mesh of all peers. For large +networks, this quickly becomes unscalable. + +There are two ways that help us to mitigate the BGPs full-mesh requirement in +a network: + +> - Using BGP route-reflectors +> - Using BGP confederation + +##### Route Reflector Configuration + +Introducing route reflectors removes the need for the full-mesh. When you +configure a route reflector you have to tell the router whether the other IBGP +router is a client or non-client. A client is an IBGP router that the route +reflector will “reflect” routes to, the non-client is just a regular IBGP +neighbor. Route reflectors mechanism is described in {rfc}`4456` and updated +by {rfc}`7606`. + +```{eval-rst} +.. cfgcmd:: set protocols bgp neighbor <address> address-family + <ipv4-unicast|ipv6-unicast> route-reflector-client + + This command specifies the given neighbor as route reflector client. +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp parameters cluster-id <id> + + This command specifies cluster ID which identifies a collection of route + reflectors and their clients, and is used by route reflectors to avoid + looping. By default cluster ID is set to the BGP router id value, but can be + set to an arbitrary 32-bit value. + +``` + +##### Confederation Configuration + +A BGP confederation divides our AS into sub-ASes to reduce the number of +required IBGP peerings. Within a sub-AS we still require full-mesh IBGP but +between these sub-ASes we use something that looks like EBGP but behaves like +IBGP (called confederation BGP). Confederation mechanism is described in +{rfc}`5065` + +```{eval-rst} +.. cfgcmd:: set protocols bgp parameters confederation identifier + <asn> + + This command specifies a BGP confederation identifier. <asn> is the number + of the autonomous system that internally includes multiple sub-autonomous + systems (a confederation). +``` + +```{eval-rst} +.. cfgcmd:: set protocols bgp parameters confederation peers <nsubasn> + + This command sets other confederations <nsubasn> as members of autonomous + system specified by {cfgcmd}`confederation identifier <asn>`. + +``` + +## Operational Mode Commands + +### Show + +```{eval-rst} +.. opcmd:: show bgp <ip|ipv6> + + This command displays all entries in BGP routing table. +``` + +```none +BGP table version is 10, local router ID is 10.0.35.3, vrf id 0 +Default local pref 100, local AS 65000 +Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, + i internal, r RIB-failure, S Stale, R Removed +Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self +Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path +*> 198.51.100.0/24 10.0.34.4 0 0 65004 i +*> 203.0.113.0/24 10.0.35.5 0 0 65005 i + +Displayed 2 routes and 2 total paths +``` + +```{eval-rst} +.. opcmd:: show bgp <ip|ipv6> <address|prefix> + + This command displays information about the particular entry in the BGP + routing table. +``` + +```none +BGP routing table entry for 198.51.100.0/24 +Paths: (1 available, best #1, table default) + Advertised to non peer-group peers: + 10.0.13.1 10.0.23.2 10.0.34.4 10.0.35.5 + 65004 + 10.0.34.4 from 10.0.34.4 (10.0.34.4) + Origin IGP, metric 0, valid, external, best (First path received) + Last update: Wed Jan 6 12:18:53 2021 +``` + +```{eval-rst} +.. opcmd:: show bgp cidr-only + + This command displays routes with classless interdomain routing (CIDR). +``` + +```{eval-rst} +.. opcmd:: show bgp <ipv4|ipv6> community <value> + + This command displays routes that belong to specified BGP communities. + Valid value is a community number in the range from 1 to 4294967200, + or AA:NN (autonomous system-community number/2-byte number), no-export, + local-as, or no-advertise. +``` + +```{eval-rst} +.. opcmd:: show bgp <ipv4|ipv6> community-list <name> + + This command displays routes that are permitted by the BGP + community list. +``` + +```{eval-rst} +.. opcmd:: show bgp <ipv4|ipv6> dampening dampened-paths + + This command displays BGP dampened routes. +``` + +```{eval-rst} +.. opcmd:: show bgp <ipv4|ipv6> dampening flap-statistics + + This command displays information about flapping BGP routes. +``` + +```{eval-rst} +.. opcmd:: show bgp <ipv4|ipv6> filter-list <name> + + This command displays BGP routes allowed by the specified AS Path + access list. +``` + +```{eval-rst} +.. opcmd:: show bgp <ipv4|ipv6> neighbors <address> advertised-routes + + This command displays BGP routes advertised to a neighbor. +``` + +```{eval-rst} +.. opcmd:: show bgp <ipv4|ipv6> neighbors <address> received-routes + + This command displays BGP routes originating from the specified BGP + neighbor before inbound policy is applied. To use this command inbound + soft reconfiguration must be enabled. +``` + +```{eval-rst} +.. opcmd:: show bgp <ipv4|ipv6> neighbors <address> routes + + This command displays BGP received-routes that are accepted after filtering. +``` + +```{eval-rst} +.. opcmd:: show bgp <ipv4|ipv6> neighbors <address> dampened-routes + + This command displays dampened routes received from BGP neighbor. +``` + +```{eval-rst} +.. opcmd:: show bgp <ipv4|ipv6> regexp <text> + + This command displays information about BGP routes whose AS path + matches the specified regular expression. +``` + +```{eval-rst} +.. opcmd:: show bgp <ipv4|ipv6> summary + + This command displays the status of all BGP connections. +``` + +```none +IPv4 Unicast Summary: +BGP router identifier 10.0.35.3, local AS number 65000 vrf-id 0 +BGP table version 11 +RIB entries 5, using 920 bytes of memory +Peers 4, using 82 KiB of memory + +Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd +10.0.13.1 4 65000 148 159 0 0 0 02:16:01 0 +10.0.23.2 4 65000 136 143 0 0 0 02:13:21 0 +10.0.34.4 4 65004 161 163 0 0 0 02:16:01 1 +10.0.35.5 4 65005 162 166 0 0 0 02:16:01 1 + +Total number of neighbors 4 +``` + +### Reset + +```{eval-rst} +.. opcmd:: reset bgp <ipv4|ipv6> <address> [soft [in|out]] + + This command resets BGP connections to the specified neighbor IP address. + With argument {cfgcmd}`soft` this command initiates a soft reset. If + you do not specify the {cfgcmd}`in` or {cfgcmd}`out` options, both + inbound and outbound soft reconfiguration are triggered. +``` + +```{eval-rst} +.. opcmd:: reset ip bgp all + + This command resets all BGP connections of given router. +``` + +```{eval-rst} +.. opcmd:: reset bgp <ipv4|ipv6> external + + This command resets all external BGP peers of given router. +``` + +```{eval-rst} +.. opcmd:: reset bgp <ipv4|ipv6> peer-group <name> [soft [in|out]] + + This command resets BGP connections to the specified peer group. + With argument {cfgcmd}`soft` this command initiates a soft reset. If + you do not specify the {cfgcmd}`in` or {cfgcmd}`out` options, both + inbound and outbound soft reconfiguration are triggered. + +``` + +## Examples + +### IPv4 peering + +A simple eBGP configuration: + +**Node 1:** + +```none +set protocols bgp system-as 65534 +set protocols bgp neighbor 192.168.0.2 ebgp-multihop '2' +set protocols bgp neighbor 192.168.0.2 remote-as '65535' +set protocols bgp neighbor 192.168.0.2 update-source '192.168.0.1' +set protocols bgp neighbor 192.168.0.2 address-family ipv4-unicast +set protocols bgp address-family ipv4-unicast network '172.16.0.0/16' +set protocols bgp parameters router-id '192.168.0.1' +``` + +**Node 2:** + +```none +set protocols bgp system-as 65535 +set protocols bgp neighbor 192.168.0.1 ebgp-multihop '2' +set protocols bgp neighbor 192.168.0.1 remote-as '65534' +set protocols bgp neighbor 192.168.0.1 update-source '192.168.0.2' +set protocols bgp neighbor 192.168.0.2 address-family ipv4-unicast +set protocols bgp address-family ipv4-unicast network '172.17.0.0/16' +set protocols bgp 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:** + +```none +set protocols static route 172.16.0.0/16 blackhole distance '254' +``` + +**Node 2:** + +```none +set protocols static route 172.17.0.0/16 blackhole distance '254' +``` + +### IPv6 peering + +A simple BGP configuration via IPv6. + +**Node 1:** + +```none +set protocols bgp system-as 65534 +set protocols bgp neighbor 2001:db8::2 ebgp-multihop '2' +set protocols bgp neighbor 2001:db8::2 remote-as '65535' +set protocols bgp neighbor 2001:db8::2 update-source '2001:db8::1' +set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast +set protocols bgp address-family ipv6-unicast network '2001:db8:1::/48' +set protocols bgp parameters router-id '10.1.1.1' +``` + +**Node 2:** + +```none +set protocols bgp system-as 65535 +set protocols bgp neighbor 2001:db8::1 ebgp-multihop '2' +set protocols bgp neighbor 2001:db8::1 remote-as '65534' +set protocols bgp neighbor 2001:db8::1 update-source '2001:db8::2' +set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast +set protocols bgp address-family ipv6-unicast network '2001:db8:2::/48' +set protocols bgp 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:** + +```none +set protocols static route6 2001:db8:1::/48 blackhole distance '254' +``` + +**Node 2:** + +```none +set protocols static route6 2001:db8:2::/48 blackhole distance '254' +``` + +### Route Filtering + +Route filter can be applied using a route-map: + +**Node1:** + +```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 system-as 65534 +set protocols bgp neighbor 2001:db8::2 address-family ipv4-unicast route-map export 'AS65535-OUT' +set protocols bgp neighbor 2001:db8::2 address-family ipv4-unicast route-map import 'AS65535-IN' +set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast route-map export 'AS65535-OUT' +set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast route-map import 'AS65535-IN' +``` + +**Node2:** + +```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 system-as 65535 +set protocols bgp neighbor 2001:db8::1 address-family ipv4-unicast route-map export 'AS65534-OUT' +set protocols bgp neighbor 2001:db8::1 address-family ipv4-unicast route-map import 'AS65534-IN' +set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast route-map export 'AS65534-OUT' +set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast 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/md-failover.md b/docs/configuration/protocols/md-failover.md new file mode 100644 index 00000000..45c3e449 --- /dev/null +++ b/docs/configuration/protocols/md-failover.md @@ -0,0 +1,120 @@ +# Failover + +Failover routes are manually configured routes, but they only install +to the routing table if the health-check target is alive. +If the target is not alive the route is removed from the routing table +until the target becomes available. + +## Failover Routes + +```{eval-rst} +.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check + target <target-address> + + Configure next-hop `<address>` and `<target-address>` for an IPv4 static + route. Specify the target + IPv4 address for health checking. +``` + +```{eval-rst} +.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check + timeout <timeout> + + Timeout in seconds between health target checks. + + Range is 1 to 300, default is 10. +``` + +```{eval-rst} +.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check + type <protocol> + + Defines protocols for checking ARP, ICMP, TCP + + Default is ``icmp``. +``` + +```{eval-rst} +.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check + policy <policy> + + Policy for checking targets +``` + +- `all-available` all checking target addresses must be available to pass + this check + +- `any-available` any of the checking target addresses must be available + to pass this check + + > Default is `any-available`. + +```{eval-rst} +.. cfgcmd:: set protocols failover route <subnet> next-hop <address> + interface <interface> + + Next-hop interface for the route +``` + +```{eval-rst} +.. cfgcmd:: set protocols failover route <subnet> next-hop <address> + metric <metric> + + Route metric + + Default 1. + +``` + +## Example + +**One gateway:** + +```none +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check target '192.0.2.1' +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check timeout '5' +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check type 'icmp' +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 interface 'eth0' +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 metric '10' +``` + +Show the route + +```none +vyos@vyos:~$ show ip route 203.0.113.1 + Routing entry for 203.0.113.1/32 + Known via "kernel", distance 0, metric 10, best + Last update 00:00:39 ago + * 192.0.2.1, via eth0 +``` + +**Two gateways and different metrics:** + +```none +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check target '192.0.2.1' +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check timeout '5' +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check type 'icmp' +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 interface 'eth0' +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 metric '10' + +set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check target '198.51.100.99' +set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check timeout '5' +set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check type 'icmp' +set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 interface 'eth2' +set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 metric '20' +``` + +Show the route + +```none +vyos@vyos:~$ show ip route 203.0.113.1 +Routing entry for 203.0.113.1/32 + Known via "kernel", distance 0, metric 10, best + Last update 00:08:06 ago + * 192.0.2.1, via eth0 + +Routing entry for 203.0.113.1/32 + Known via "kernel", distance 0, metric 20 + Last update 00:08:14 ago + * 198.51.100.1, via eth2 +``` diff --git a/docs/configuration/protocols/md-igmp-proxy.md b/docs/configuration/protocols/md-igmp-proxy.md new file mode 100644 index 00000000..961f921b --- /dev/null +++ b/docs/configuration/protocols/md-igmp-proxy.md @@ -0,0 +1,79 @@ +--- +lastproofread: '2023-11-13' +--- + +(igmp-proxy)= + +# 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 the +upstream. + +If it's vital that the daemon should act exactly like 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. +``` + +(igmp-proxy-example)= + +### 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. + +```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. +```
\ No newline at end of file diff --git a/docs/configuration/protocols/md-index.md b/docs/configuration/protocols/md-index.md new file mode 100644 index 00000000..418e49af --- /dev/null +++ b/docs/configuration/protocols/md-index.md @@ -0,0 +1,22 @@ +# Protocols + +```{eval-rst} +.. toctree:: + :maxdepth: 1 + :includehidden: + + babel + bfd + bgp + failover + igmp-proxy + isis + mpls + segment-routing + ospf + pim + pim6 + rip + rpki + static +``` diff --git a/docs/configuration/protocols/md-isis.md b/docs/configuration/protocols/md-isis.md new file mode 100644 index 00000000..07ffd827 --- /dev/null +++ b/docs/configuration/protocols/md-isis.md @@ -0,0 +1,596 @@ +```{include} /_include/need_improvement.txt +``` + +(routing-isis)= + +# IS-IS + +{abbr}`IS-IS (Intermediate System to Intermediate System)` is a link-state +interior gateway protocol (IGP) which is described in ISO10589, +{rfc}`1195`, {rfc}`5308`. IS-IS runs the Dijkstra shortest-path first (SPF) +algorithm to create a database of the network’s topology, and +from that database to determine the best (that is, lowest cost) path to a +destination. The intermediate systems (the name for routers) exchange topology +information with their directly conencted neighbors. IS-IS runs directly on +the data link layer (Layer 2). IS-IS addresses are called +{abbr}`NETs (Network Entity Titles)` and can be 8 to 20 bytes long, but are +generally 10 bytes long. The tree database that is created with IS-IS is +similar to the one that is created with OSPF in that the paths chosen should +be similar. Comparisons to OSPF are inevitable and often are reasonable ones +to make in regards to the way a network will respond with either IGP. + +## General + +### Configuration + +#### Mandatory Settings + +For IS-IS top operate correctly, one must do the equivalent of a Router ID in +CLNS. This Router ID is called the {abbr}`NET (Network Entity Title)`. This +must be unique for each and every router that is operating in IS-IS. It also +must not be duplicated otherwise the same issues that occur within OSPF will +occur within IS-IS when it comes to said duplication. + +```{eval-rst} +.. cfgcmd:: set protocols isis net <network-entity-title> + + This commad sets network entity title (NET) provided in ISO format. + + Here is an example {abbr}`NET (Network Entity Title)` value: + + .. code-block:: none + + 49.0001.1921.6800.1002.00 + + The CLNS address consists of the following parts: + + * {abbr}`AFI (Address family authority identifier)` - ``49`` The AFI value + 49 is what IS-IS uses for private addressing. + + * Area identifier: ``0001`` IS-IS area number (numberical area ``1``) + + * System identifier: ``1921.6800.1002`` - for system idetifiers we recommend + to use IP address or MAC address of the router itself. The way to construct + this is to keep all of the zeroes of the router IP address, and then change + the periods from being every three numbers to every four numbers. The + address that is listed here is ``192.168.1.2``, which if expanded will turn + into ``192.168.001.002``. Then all one has to do is move the dots to have + four numbers instead of three. This gives us ``1921.6800.1002``. + + * {abbr}`NET (Network Entity Title)` selector: ``00`` Must always be 00. This + setting indicates "this system" or "local system." +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis interface <interface> + + This command enables IS-IS on this interface, and allows for + adjacency to occur. Note that the name of IS-IS instance must be + the same as the one used to configure the IS-IS process. +``` + +#### IS-IS Global Configuration + +```{eval-rst} +.. cfgcmd:: set protocols isis dynamic-hostname + + This command enables support for dynamic hostname TLV. Dynamic hostname + mapping determined as described in {rfc}`2763`, Dynamic Hostname + Exchange Mechanism for IS-IS. +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis level <level-1|level-1-2|level-2> + + This command defines the IS-IS router behavior: + + * **level-1** - Act as a station (Level 1) router only. + * **level-1-2** - Act as a station (Level 1) router and area (Level 2) router. + * **level-2-only** - Act as an area (Level 2) router only. +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis lsp-mtu <size> + + This command configures the maximum size of generated + {abbr}`LSPs (Link State PDUs)`, in bytes. The size range is 128 to 4352. +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis metric-style <narrow|transition|wide> + + This command sets old-style (ISO 10589) or new style packet formats: + + * **narrow** - Use old style of TLVs with narrow metric. + * **transition** - Send and accept both styles of TLVs during transition. + * **wide** - Use new style of TLVs to carry wider metric. +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis purge-originator + + This command enables {rfc}`6232` purge originator identification. Enable + purge originator identification (POI) by adding the type, length and value + (TLV) with the Intermediate System (IS) identification to the LSPs that do + not contain POI information. If an IS generates a purge, VyOS adds this TLV + with the system ID of the IS to the purge. +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis set-attached-bit + + This command sets ATT bit to 1 in Level1 LSPs. It is described in {rfc}`3787`. +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis set-overload-bit + + This command sets overload bit to avoid any transit traffic through this + router. It is described in {rfc}`3787`. +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis name default-information originate <ipv4|ipv6> + level-1 + + This command will generate a default-route in L1 database. +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis name default-information originate <ipv4|ipv6> + level-2 + + This command will generate a default-route in L2 database. + +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis ldp-sync + + This command will enable IGP-LDP synchronization globally for ISIS. This + requires for LDP to be functional. This is described in {rfc}`5443`. By + default all interfaces operational in IS-IS are enabled for synchronization. + Loopbacks are exempt. +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis ldp-sync holddown <seconds> + + This command will change the hold down value globally for IGP-LDP + synchronization during convergence/interface flap events. + +``` + +#### Interface Configuration + +```{eval-rst} +.. cfgcmd:: set protocols isis interface <interface> circuit-type + <level-1|level-1-2|level-2-only> + + This command specifies circuit type for interface: + + * **level-1** - Level-1 only adjacencies are formed. + * **level-1-2** - Level-1-2 adjacencies are formed + * **level-2-only** - Level-2 only adjacencies are formed +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis interface <interface> hello-interval + <seconds> + + This command sets hello interval in seconds on a given interface. + The range is 1 to 600. +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis interface <interface> hello-multiplier + <seconds> + + This command sets multiplier for hello holding time on a given + interface. The range is 2 to 100. +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis interface <interface> hello-padding + + This command configures padding on hello packets to accommodate asymmetrical + maximum transfer units (MTUs) from different hosts as described in + {rfc}`3719`. This helps to prevent a premature adjacency Up state when one + routing devices MTU does not meet the requirements to establish the adjacency. +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis interface <interface> metric <metric> + + This command set default metric for circuit. + + The metric range is 1 to 16777215 (Max value depend if metric support narrow + or wide value). +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis interface <interface> network + point-to-point + + This command specifies network type to Point-to-Point. The default + network type is broadcast. +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis interface <interface> passive + + This command configures the passive mode for this interface. +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis interface <interface> password + plaintext-password <text> + + This command configures the authentication password for the interface. +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis interface <interface> priority <number> + + This command sets priority for the interface for + {abbr}`DIS (Designated Intermediate System)` election. The priority + range is 0 to 127. +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis interface <interface> psnp-interval + <number> + + This command sets PSNP interval in seconds. The interval range is 0 + to 127. +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis interface <interface> + no-three-way-handshake + + This command disables Three-Way Handshake for P2P adjacencies which + described in {rfc}`5303`. Three-Way Handshake is enabled by default. +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis interface <interface> ldp-sync disable + + This command disables IGP-LDP sync for this specific interface. +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis interface <interface> ldp-sync holddown + <seconds> + + This command will change the hold down value for IGP-LDP synchronization + during convergence/interface flap events, but for this interface only. +``` + +#### Route Redistribution + +```{eval-rst} +.. cfgcmd:: set protocols isis redistribute ipv4 <route source> level-1 + + This command redistributes routing information from the given route source + into the ISIS database as Level-1. There are six modes available for route + source: bgp, connected, kernel, ospf, rip, static. +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis redistribute ipv4 <route source> level-2 + + This command redistributes routing information from the given route source + into the ISIS database as Level-2. There are six modes available for route + source: bgp, connected, kernel, ospf, rip, static. +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis redistribute ipv4 <route source> + <level-1|level-2> metric <number> + + This command specifies metric for redistributed routes from the given route + source. There are six modes available for route source: bgp, connected, + kernel, ospf, rip, static. The metric range is 1 to 16777215. +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis redistribute ipv4 <route source> + <level-1|level-2> route-map <name> + + This command allows to use route map to filter redistributed routes from + the given route source. There are six modes available for route source: + bgp, connected, kernel, ospf, rip, static. + +``` + +#### Timers + +```{eval-rst} +.. cfgcmd:: set protocols isis lsp-gen-interval <seconds> + + This command sets minimum interval in seconds between regenerating same + LSP. The interval range is 1 to 120. +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis lsp-refresh-interval <seconds> + + This command sets LSP refresh interval in seconds. IS-IS generates LSPs + when the state of a link changes. However, to ensure that routing + databases on all routers remain converged, LSPs in stable networks are + generated on a regular basis even though there has been no change to + the state of the links. The interval range is 1 to 65235. The default + value is 900 seconds. +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis max-lsp-lifetime <seconds> + + This command sets LSP maximum LSP lifetime in seconds. The interval range + is 350 to 65535. LSPs remain in a database for 1200 seconds by default. + If they are not refreshed by that time, they are deleted. You can change + the LSP refresh interval or the LSP lifetime. The LSP refresh interval + should be less than the LSP lifetime or else LSPs will time out before + they are refreshed. +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis spf-interval <seconds> + + This command sets minimum interval between consecutive SPF calculations in + seconds.The interval range is 1 to 120. +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis spf-delay-ietf holddown <milliseconds> +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis spf-delay-ietf init-delay + <milliseconds> +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis spf-delay-ietf long-delay + <milliseconds> +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis spf-delay-ietf short-delay + <milliseconds> +``` + +```{eval-rst} +.. cfgcmd:: set protocols isis spf-delay-ietf time-to-learn + <milliseconds> + + This commands specifies the Finite State Machine (FSM) intended to + control the timing of the execution of SPF calculations in response + to IGP events. The process described in {rfc}`8405`. + +``` + +## Examples + +### Enable IS-IS + +**Node 1:** + +```none +set interfaces loopback lo address '192.168.255.255/32' +set interfaces ethernet eth1 address '192.0.2.1/24' + +set protocols isis interface eth1 +set protocols isis interface lo +set protocols isis net '49.0001.1921.6825.5255.00' +``` + +**Node 2:** + +```none +set interfaces ethernet eth1 address '192.0.2.2/24' + +set interfaces loopback lo address '192.168.255.254/32' +set interfaces ethernet eth1 address '192.0.2.2/24' + +set protocols isis interface eth1 +set protocols isis interface lo +set protocols isis net '49.0001.1921.6825.5254.00' +``` + +This gives us the following neighborships, Level 1 and Level 2: + +```none +Node-1@vyos:~$ show isis neighbor +Area VyOS: + System Id Interface L State Holdtime SNPA + vyos eth1 1 Up 28 0c87.6c09.0001 + vyos eth1 2 Up 28 0c87.6c09.0001 + +Node-2@vyos:~$ show isis neighbor +Area VyOS: + System Id Interface L State Holdtime SNPA + vyos eth1 1 Up 29 0c33.0280.0001 + vyos eth1 2 Up 28 0c33.0280.0001 +``` + +Here's the IP routes that are populated. Just the loopback: + +```none +Node-1@vyos:~$ show ip route isis +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +I 192.0.2.0/24 [115/20] via 192.0.2.2, eth1 inactive, weight 1, 00:02:22 +I>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1, weight 1, 00:02:22 + +Node-2@vyos:~$ show ip route isis +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +I 192.0.2.0/24 [115/20] via 192.0.2.1, eth1 inactive, weight 1, 00:02:21 +I>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1, weight 1, 00:02:21 +``` + +### Enable IS-IS and redistribute routes not natively in IS-IS + +**Node 1:** + +```none +set interfaces dummy dum0 address '203.0.113.1/24' +set interfaces ethernet eth1 address '192.0.2.1/24' + +set policy prefix-list EXPORT-ISIS rule 10 action 'permit' +set policy prefix-list EXPORT-ISIS rule 10 prefix '203.0.113.0/24' +set policy route-map EXPORT-ISIS rule 10 action 'permit' +set policy route-map EXPORT-ISIS rule 10 match ip address prefix-list 'EXPORT-ISIS' + +set protocols isis interface eth1 +set protocols isis net '49.0001.1921.6800.1002.00' +set protocols isis redistribute ipv4 connected level-2 route-map 'EXPORT-ISIS' +``` + +**Node 2:** + +```none +set interfaces ethernet eth1 address '192.0.2.2/24' + +set protocols isis interface eth1 +set protocols isis net '49.0001.1921.6800.2002.00' +``` + +Routes on Node 2: + +```none +Node-2@r2:~$ show ip route isis +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued route, r - rejected route + +I 203.0.113.0/24 [115/10] via 192.0.2.1, eth1, 00:03:42 +``` + +### Enable IS-IS and IGP-LDP synchronization + +**Node 1:** + +```none +set interfaces loopback lo address 192.168.255.255/32 +set interfaces ethernet eth0 address 192.0.2.1/24 + +set protocols isis interface eth0 +set protocols isis interface lo passive +set protocols isis ldp-sync +set protocols isis net 49.0001.1921.6825.5255.00 + +set protocols mpls interface eth0 +set protocols mpls ldp discovery transport-ipv4-address 192.168.255.255 +set protocols mpls ldp interface lo +set protocols mpls ldp interface eth0 +set protocols mpls ldp parameters transport-prefer-ipv4 +set protocols mpls ldp router-id 192.168.255.255 +``` + +This gives us IGP-LDP synchronization for all non-loopback interfaces with +a holddown timer of zero seconds: + +```none +Node-1@vyos:~$ show isis mpls ldp-sync +eth0 + LDP-IGP Synchronization enabled: yes + holddown timer in seconds: 0 + State: Sync achieved +``` + +### Enable IS-IS with Segment Routing (Experimental) + +**Node 1:** + +```none +set interfaces loopback lo address '192.168.255.255/32' +set interfaces ethernet eth1 address '192.0.2.1/24' + +set protocols isis interface eth1 +set protocols isis interface lo +set protocols isis net '49.0001.1921.6825.5255.00' +set protocols isis segment-routing global-block high-label-value '599' +set protocols isis segment-routing global-block low-label-value '550' +set protocols isis segment-routing prefix 192.168.255.255/32 index value '1' +set protocols isis segment-routing prefix 192.168.255.255/32 index explicit-null +set protocols mpls interface 'eth1' +``` + +**Node 2:** + +```none +set interfaces loopback lo address '192.168.255.254/32' +set interfaces ethernet eth1 address '192.0.2.2/24' + +set protocols isis interface eth1 +set protocols isis interface lo +set protocols isis net '49.0001.1921.6825.5254.00' +set protocols isis segment-routing global-block high-label-value '599' +set protocols isis segment-routing global-block low-label-value '550' +set protocols isis segment-routing prefix 192.168.255.254/32 index value '2' +set protocols isis segment-routing prefix 192.168.255.254/32 index explicit-null +set protocols mpls interface 'eth1' +``` + +This gives us MPLS segment routing enabled and labels for far end loopbacks: + +```none +Node-1@vyos:~$ show mpls table + Inbound Label Type Nexthop Outbound Label + ---------------------------------------------------------------------- + 552 SR (IS-IS) 192.0.2.2 IPv4 Explicit Null <-- Node-2 loopback learned on Node-1 + 15000 SR (IS-IS) 192.0.2.2 implicit-null + 15001 SR (IS-IS) fe80::e87:6cff:fe09:1 implicit-null + 15002 SR (IS-IS) 192.0.2.2 implicit-null + 15003 SR (IS-IS) fe80::e87:6cff:fe09:1 implicit-null + +Node-2@vyos:~$ show mpls table + Inbound Label Type Nexthop Outbound Label + --------------------------------------------------------------------- + 551 SR (IS-IS) 192.0.2.1 IPv4 Explicit Null <-- Node-1 loopback learned on Node-2 + 15000 SR (IS-IS) 192.0.2.1 implicit-null + 15001 SR (IS-IS) fe80::e33:2ff:fe80:1 implicit-null + 15002 SR (IS-IS) 192.0.2.1 implicit-null + 15003 SR (IS-IS) fe80::e33:2ff:fe80:1 implicit-null +``` + +Here is the routing tables showing the MPLS segment routing label operations: + +```none +Node-1@vyos:~$ show ip route isis +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +I 192.0.2.0/24 [115/20] via 192.0.2.2, eth1 inactive, weight 1, 00:07:48 +I>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1, label IPv4 Explicit Null, weight 1, 00:03:39 + +Node-2@vyos:~$ show ip route isis +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +I 192.0.2.0/24 [115/20] via 192.0.2.1, eth1 inactive, weight 1, 00:07:46 +I>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1, label IPv4 Explicit Null, weight 1, 00:03:43 +``` diff --git a/docs/configuration/protocols/md-mpls.md b/docs/configuration/protocols/md-mpls.md new file mode 100644 index 00000000..71b14be2 --- /dev/null +++ b/docs/configuration/protocols/md-mpls.md @@ -0,0 +1,285 @@ +(mpls)= + +# MPLS + +{abbr}`MPLS (Multi-Protocol Label Switching)` is a packet forwarding paradigm +which differs from regular IP forwarding. Instead of IP addresses being used to +make the decision on finding the exit interface, a router will instead use an +exact match on a 32 bit/4 byte header called the MPLS label. This label is +inserted between the ethernet (layer 2) header and the IP (layer 3) header. +One can statically or dynamically assign label allocations, but we will focus +on dynamic allocation of labels using some sort of label distribution protocol +(such as the aptly named Label Distribution Protocol / LDP, Resource Reservation +Protocol / RSVP, or Segment Routing through OSPF/ISIS). These protocols allow +for the creation of a unidirectional/unicast path called a labeled switched +path (initialized as LSP) throughout the network that operates very much like +a tunnel through the network. An easy way of thinking about how an MPLS LSP +actually forwards traffic throughout a network is to think of a GRE tunnel. +They are not the same in how they operate, but they are the same in how they +handle the tunneled packet. It would be good to think of MPLS as a tunneling +technology that can be used to transport many different types of packets, to +aid in traffic engineering by allowing one to specify paths throughout the +network (using RSVP or SR), and to generally allow for easier intra/inter +network transport of data packets. + +For more information on how MPLS label switching works, please go visit +[Wikipedia (MPLS)]. + +:::{note} +MPLS support in VyOS is not finished yet, and therefore its +functionality is limited. Currently there is no support for MPLS enabled VPN +services such as L2VPNs and mVPNs. RSVP support is also not present as the +underlying routing stack (FRR) does not implement it. Currently VyOS +implements LDP as described in RFC 5036; other LDP standard are the +following ones: RFC 6720, RFC 6667, RFC 5919, RFC 5561, RFC 7552, RFC 4447. +Because MPLS is already available (FRR also supports RFC 3031). +::: + +## Label Distribution Protocol + +The {abbr}`MPLS (Multi-Protocol Label Switching)` architecture does not assume +a single protocol to create MPLS paths. VyOS supports the Label Distribution +Protocol (LDP) as implemented by FRR, based on {rfc}`5036`. + +{abbr}`LDP (Label Distribution Protocol)` is a TCP based MPLS signaling protocol +that distributes labels creating MPLS label switched paths in a dynamic manner. +LDP is not a routing protocol, as it relies on other routing protocols for +forwarding decisions. LDP cannot bootstrap itself, and therefore relies on said +routing protocols for communication with other routers that use LDP. + +In order to allow for LDP on the local router to exchange label advertisements +with other routers, a TCP session will be established between automatically +discovered and statically assigned routers. LDP will try to establish a TCP +session to the **transport address** of other routers. Therefore for LDP to +function properly please make sure the transport address is shown in the +routing table and reachable to traffic at all times. + +It is highly recommended to use the same address for both the LDP router-id and +the discovery transport address, but for VyOS MPLS LDP to work both parameters +must be explicitly set in the configuration. + +Another thing to keep in mind with LDP is that much like BGP, it is a protocol +that runs on top of TCP. It however does not have an ability to do something +like a refresh capability like BGPs route refresh capability. Therefore one +might have to reset the neighbor for a capability change or a configuration +change to work. + +## Configuration Options + +```{cfgcmd} set protocols mpls interface \<interface\> + +Use this command to enable MPLS processing on the interface you define. +``` + + +```{cfgcmd} set protocols mpls ldp interface \<interface\> + +Use this command to enable LDP on the interface you define. +``` + + +```{cfgcmd} set protocols mpls ldp router-id \<address\> + +Use this command to configure the IP address used as the LDP router-id of the +local device. +``` + + +```{cfgcmd} set protocols mpls ldp discovery transport-ipv4-address \<address\> + +``` +```{cfgcmd} set protocols mpls ldp discovery transport-ipv6-address \<address\> + +Use this command to set the IPv4 or IPv6 transport-address used by LDP. +``` + +```{cfgcmd} set protocols mpls ldp neighbor \<address\> password \<password\> + +Use this command to configure authentication for LDP peers. Set the +IP address of the LDP peer and a password that should be shared in +order to become neighbors. +``` + +```{cfgcmd} set protocols mpls ldp neighbor \<address\> session-holdtime \<seconds\> + +Use this command to configure a specific session hold time for LDP peers. +Set the IP address of the LDP peer and a session hold time that should be +configured for it. You may have to reset the neighbor for this to work. +``` + +```{cfgcmd} set protocols mpls ldp neighbor \<address\> ttl-security \<disable | hop count\> + +Use this command to enable, disable, or specify hop count for TTL security +for LDP peers. By default the value is set to 255 (or max TTL). +``` + +```{eval-rst} +.. cfgcmd:: set protocols mpls ldp discovery hello-ipv4-interval <seconds> +.. cfgcmd:: set protocols mpls ldp discovery hello-ipv4-holdtime <seconds> +.. cfgcmd:: set protocols mpls ldp discovery hello-ipv6-interval <seconds> +.. cfgcmd:: set protocols mpls ldp discovery hello-ipv6-holdtime <seconds> + + Use these commands if you would like to set the discovery hello and hold time + parameters. +``` + +```{eval-rst} +.. cfgcmd:: set protocols mpls ldp discovery session-ipv4-holdtime <seconds> +.. cfgcmd:: set protocols mpls ldp discovery session-ipv6-holdtime <seconds> + + Use this command if you would like to set the TCP session hold time intervals. +``` + +```{eval-rst} +.. cfgcmd:: set protocols mpls ldp import ipv4 import-filter filter-access-list + <access list number> +.. cfgcmd:: set protocols mpls ldp import ipv6 import-filter filter-access-list6 + <access list number> + + Use these commands to control the importing of forwarding equivalence classes + (FECs) for LDP from neighbors. This would be useful for example on only + accepting the labeled routes that are needed and not ones that are not + needed, such as accepting loopback interfaces and rejecting all others. +``` + +```{eval-rst} +.. cfgcmd:: set protocols mpls ldp export ipv4 export-filter filter-access-list + <access list number> +.. cfgcmd:: set protocols mpls ldp export ipv6 export-filter filter-access-list6 + <access list number> + + Use these commands to control the exporting of forwarding equivalence classes + (FECs) for LDP to neighbors. This would be useful for example on only + announcing the labeled routes that are needed and not ones that are not + needed, such as announcing loopback interfaces and no others. +``` + +```{eval-rst} +.. cfgcmd:: set protocols mpls ldp export ipv4 explicit-null +.. cfgcmd:: set protocols mpls ldp export ipv6 explicit-null + + Use this command if you would like for the router to advertise FECs with a + label of 0 for explicit null operations. +``` + +```{eval-rst} +.. cfgcmd:: set protocols mpls ldp allocation ipv4 access-list <access list number> +.. cfgcmd:: set protocols mpls ldp allocation ipv6 access-list6 <access list number> + + Use this command if you would like to control the local FEC allocations for + LDP. A good example would be for your local router to not allocate a label for + everything. Just a label for what it's useful. A good example would be just a + loopback label. +``` + +```{cfgcmd} set protocols mpls ldp parameters cisco-interop-tlv + +Use this command to use a Cisco non-compliant format to send and interpret +the Dual-Stack capability TLV for IPv6 LDP communications. This is related to +{rfc}`7552`. +``` + +```{cfgcmd} set protocols mpls ldp parameters ordered-control + +Use this command to use ordered label distribution control mode. FRR +by default uses independent label distribution control mode for label +distribution. This is related to {rfc}`5036`. +``` + +```{cfgcmd} set protocols mpls ldp parameters transport-prefer-ipv4 + +Use this command to prefer IPv4 for TCP peer transport connection for LDP +when both an IPv4 and IPv6 LDP address are configured on the same interface. +``` + +```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv4 enable +``` + +```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv6 enable + +Use this command to enable targeted LDP sessions to the local router. The +router will then respond to any sessions that are trying to connect to it that +are not a link local type of TCP connection. +``` + +```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv4 address \<address\> +``` + +```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv6 address \<address\> + +Use this command to enable the local router to try and connect with a targeted +LDP session to another router. +``` + +```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv4 hello-holdtime \<seconds\> +``` + +```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv4 hello-interval \<seconds\> +``` + +```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv6 hello-holdtime \<seconds\> +``` + +```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv6 hello-interval \<seconds\> + +Use these commands if you would like to set the discovery hello and hold time +parameters for the targeted LDP neighbors. +``` + +### Sample configuration to setup LDP on VyOS + +```none +set protocols ospf area 0 network '192.168.255.252/32' <--- Routing for loopback +set protocols ospf area 0 network '192.168.0.5/32' <--- Routing for an interface connecting to the network +set protocols ospf parameters router-id '192.168.255.252' <--- Router ID setting for OSPF +set protocols mpls interface 'eth1' <--- Enable MPLS for an interface connecting to network +set protocols mpls ldp discovery transport-ipv4-address '192.168.255.252' <--- Transport address for LDP for TCP sessions to connect to +set protocols mpls ldp interface 'eth1' <--- Enable LDP for an interface connecting to network +set protocols mpls ldp interface 'lo' <--- Enable LDP on loopback for future services connectivity +set protocols mpls ldp router-id '192.168.255.252' <--- Router ID setting for LDP +set interfaces ethernet eth1 address '192.168.0.5/31' <--- Interface IP for connecting to network +set interfaces loopback lo address '192.168.255.252/32' <--- Interface loopback IP for router ID and other uses +``` + +## Operational Mode Commands + +When LDP is working, you will be able to see label information in the outcome +of `show ip route`. Besides that information, there are also specific *show* +commands for LDP: + +### Show + +```{opcmd} show mpls ldp binding + +Use this command to see the Label Information Base. + +``` + +```{opcmd} show mpls ldp discovery + +Use this command to see discovery hello information +``` + +```{opcmd} show mpls ldp interface + +Use this command to see LDP interface information +``` + +```{opcmd} show mpls ldp neighbor + +Use this command to see LDP neighbor information +``` + +```{opcmd} show mpls ldp neighbor detail + +Use this command to see detailed LDP neighbor information +``` + +### Reset + +```{opcmd} reset mpls ldp neighbor \<IPv4 or IPv6 address\> + +Use this command to reset an LDP neighbor/TCP session that is established +``` + +[wikipedia (mpls)]: <https://en.wikipedia.org/wiki/Multiprotocol_Label_Switching> diff --git a/docs/configuration/protocols/md-ospf.md b/docs/configuration/protocols/md-ospf.md new file mode 100644 index 00000000..adc62520 --- /dev/null +++ b/docs/configuration/protocols/md-ospf.md @@ -0,0 +1,1560 @@ +(routing-ospf)= + +# OSPF + +{abbr}`OSPF (Open Shortest Path First)` 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 {rfc}`2328` (1998) +for IPv4. Updates for IPv6 are specified as OSPF Version 3 in {rfc}`5340` +(2008). OSPF supports the {abbr}`CIDR (Classless Inter-Domain Routing)` +addressing model. + +OSPF is a widely used IGP in large enterprise networks. + +## OSPFv2 (IPv4) + +### Configuration + +#### General + +VyOS does not have a special command to start the OSPF process. The OSPF process +starts when the first ospf enabled interface is configured. + +```{eval-rst} +.. cfgcmd:: set protocols ospf area <number> network <A.B.C.D/M> + + This command specifies the OSPF enabled interface(s). If the interface has + an address from defined range then the command enables OSPF on this + interface so router can provide network information to the other ospf + routers via this interface. + + This command is also used to enable the OSPF process. The area number can be + specified in decimal notation in the range from 0 to 4294967295. Or it + can be specified in dotted decimal notation similar to ip address. + + Prefix length in interface must be equal or bigger (i.e. smaller network) + than prefix length in network statement. For example statement above doesn't + enable ospf on interface with address 192.168.1.1/23, but it does on + interface with address 192.168.1.129/25. + + In some cases it may be more convenient to enable OSPF on a per + interface/subnet + basis {cfgcmd}`set protocols ospf interface <interface> area <x.x.x.x | x>` +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf auto-cost reference-bandwidth <number> + + This command sets the reference bandwidth for cost calculations, where + bandwidth can be in range from 1 to 4294967, specified in Mbits/s. The + default is 100Mbit/s (i.e. a link of bandwidth 100Mbit/s or higher will + have a cost of 1. Cost of lower bandwidth links will be scaled with + reference to this cost). +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf parameters router-id <rid> + + This command sets the router-ID of the OSPF process. The router-ID may be an + IP address of the router, but need not be – it can be any arbitrary 32bit + number. However it MUST be unique within the entire OSPF domain to the OSPF + speaker – bad things will happen if multiple OSPF speakers are configured + with the same router-ID! + +``` + +#### Optional + +```{eval-rst} +.. cfgcmd:: set protocols ospf default-information originate [always] + [metric <number>] [metric-type <1|2>] [route-map <name>] + + Originate an AS-External (type-5) LSA describing a default route into all + external-routing capable areas, of the specified metric and metric type. + If the {cfgcmd}`always` keyword is given then the default is always + advertised, even when there is no default present in the routing table. + The argument {cfgcmd}`route-map` specifies to advertise the default route + if the route map is satisfied. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf distance global <distance> + + This command change distance value of OSPF globally. + The distance range is 1 to 255. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf distance ospf <external|inter-area|intra-area> + <distance> + + This command change distance value of OSPF. The arguments are the distance + values for external routes, inter-area routes and intra-area routes + respectively. The distance range is 1 to 255. + + .. note:: Routes with a distance of 255 are effectively disabled and not + installed into the kernel. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf log-adjacency-changes [detail] + + This command allows to log changes in adjacency. With the optional + {cfgcmd}`detail` argument, all changes in adjacency status are shown. + Without {cfgcmd}`detail`, only changes to full or regressions are shown. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf max-metric router-lsa + <administrative|on-shutdown <seconds>|on-startup <seconds>> + + This enables {rfc}`3137` support, where the OSPF process describes its + transit links in its router-LSA as having infinite distance so that other + routers will avoid calculating transit paths through the router while + still being able to reach networks through the router. + + This support may be enabled administratively (and indefinitely) with the + {cfgcmd}`administrative` command. It may also be enabled conditionally. + Conditional enabling of max-metric router-lsas can be for a period of + seconds after startup with the {cfgcmd}`on-startup <seconds>` command + and/or for a period of seconds prior to shutdown with the + {cfgcmd}`on-shutdown <seconds>` command. The time range is 5 to 86400. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf parameters abr-type + <cisco|ibm|shortcut|standard> + + This command selects ABR model. OSPF router supports four ABR models: + + **cisco** – a router will be considered as ABR if it has several configured + links to the networks in different areas one of which is a backbone area. + Moreover, the link to the backbone area should be active (working). + **ibm** – identical to "cisco" model but in this case a backbone area link + may not be active. + **standard** – router has several active links to different areas. + **shortcut** – identical to "standard" but in this model a router is + allowed to use a connected areas topology without involving a backbone + area for inter-area connections. + + Detailed information about "cisco" and "ibm" models differences can be + found in {rfc}`3509`. A "shortcut" model allows ABR to create routes + between areas based on the topology of the areas connected to this router + but not using a backbone area in case if non-backbone route will be + cheaper. For more information about "shortcut" model, + see :t:`ospf-shortcut-abr-02.txt` +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf parameters rfc1583-compatibility + + {rfc}`2328`, the successor to {rfc}`1583`, suggests according to section + G.2 (changes) in section 16.4.1 a change to the path preference algorithm + that prevents possible routing loops that were possible in the old version + of OSPFv2. More specifically it demands that inter-area paths and + intra-area backbone path are now of equal preference but still both + preferred to external paths. + + This command should NOT be set normally. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf interface <interface> passive [disable] + + This command specifies interface as passive. Passive interface advertises + its address, but does not run the OSPF protocol (adjacencies are not formed + and hello packets are not generated). + + The optional `disable` option allows to exclude interface from passive state. + This command is used if the command {cfgcmd}`passive-interface default` was + configured. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf passive-interface default + + This command specifies all interfaces as passive by default. Because this + command changes the configuration logic to a default passive; therefore, + interfaces where router adjacencies are expected need to be configured + by setting the {cfgcmd}`passive disable` flag for the specific interface. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf maximum-paths <1-64> + + Use this command to control the maximum number of equal cost paths to reach + a specific destination. The upper limit may differ if you change the value + of MULTIPATH_NUM during compilation. The default is MULTIPATH_NUM (64). +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf refresh timers <seconds> + + The router automatically updates link-state information with its neighbors. + Only an obsolete information is updated which age has exceeded a specific + threshold. This parameter changes a threshold value, which by default is + 1800 seconds (half an hour). The value is applied to the whole OSPF router. + The timer range is 10 to 1800. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf timers throttle spf + <delay|initial-holdtime|max-holdtime> <seconds> + + This command sets the initial delay, the initial-holdtime and the + maximum-holdtime between when SPF is calculated and the event which + triggered the calculation. The times are specified in milliseconds and must + be in the range of 0 to 600000 milliseconds. {cfgcmd}`delay` sets the + initial SPF schedule delay in milliseconds. The default value is 200 ms. + {cfgcmd}`initial-holdtime` sets the minimum hold time between two + consecutive SPF calculations. The default value is 1000 ms. + {cfgcmd}`max-holdtime` sets the maximum wait time between two + consecutive SPF calculations. The default value is 10000 ms. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf ldp-sync + + This command will enable IGP-LDP synchronization globally for OSPF. This + requires for LDP to be functional. This is described in {rfc}`5443`. By + default all interfaces operational in OSPF are enabled for synchronization. + Loopbacks are exempt. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf ldp-sync holddown <seconds> + + This command will change the hold down value globally for IGP-LDP + synchronization during convergence/interface flap events. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf capability opaque + + ospfd supports Opaque LSA {rfc}`2370` as partial support for MPLS Traffic + Engineering LSAs. The opaque-lsa capability must be enabled in the + configuration. + + An alternate command could be "mpls-te on" (Traffic Engineering) + + .. note:: FRR offers only partial support for some of the routing + protocol extensions that are used with MPLS-TE; it does not + support a complete RSVP-TE solution. +``` + +#### Area Configuration + +```{eval-rst} +.. cfgcmd:: set protocols ospf area <number> area-type stub + + This command specifies the area to be a Stub Area. That is, an area where + no router originates routes external to OSPF and hence an area where all + external routes are via the ABR(s). Hence, ABRs for such an area do not + need to pass AS-External LSAs (type-5) or ASBR-Summary LSAs (type-4) into + the area. They need only pass Network-Summary (type-3) LSAs into such an + area, along with a default-route summary. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf area <number> area-type stub no-summary + + This command specifies the area to be a Totally Stub Area. In addition to + stub area limitations this area type prevents an ABR from injecting + Network-Summary (type-3) LSAs into the specified stub area. Only default + summary route is allowed. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf area <number> area-type stub default-cost + <number> + + This command sets the cost of default-summary LSAs announced to stubby + areas. The cost range is 0 to 16777215. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf area <number> area-type nssa + + This command specifies the area to be a Not So Stubby Area. External + routing information is imported into an NSSA in Type-7 LSAs. Type-7 LSAs + are similar to Type-5 AS-external LSAs, except that they can only be + flooded into the NSSA. In order to further propagate the NSSA external + information, the Type-7 LSA must be translated to a Type-5 AS-external-LSA + by the NSSA ABR. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf area <number> area-type nssa no-summary + + This command specifies the area to be a NSSA Totally Stub Area. ABRs for + such an area do not need to pass Network-Summary (type-3) LSAs (except the + default summary route), ASBR-Summary LSAs (type-4) and AS-External LSAs + (type-5) into the area. But Type-7 LSAs that convert to Type-5 at the NSSA + ABR are allowed. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf area <number> area-type nssa default-cost + <number> + + This command sets the default cost of LSAs announced to NSSA areas. + The cost range is 0 to 16777215. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf area <number> area-type nssa translate + <always|candidate|never> + + Specifies whether this NSSA border router will unconditionally translate + Type-7 LSAs into Type-5 LSAs. When role is Always, Type-7 LSAs are + translated into Type-5 LSAs regardless of the translator state of other + NSSA border routers. When role is Candidate, this router participates in + the translator election to determine if it will perform the translations + duties. When role is Never, this router will never translate Type-7 LSAs + into Type-5 LSAs. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf area <number> authentication plaintext-password + + This command specifies that simple password authentication should be used + for the given area. The password must also be configured on a per-interface + basis. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf area <number> authentication md5 + + This command specify that OSPF packets must be authenticated with MD5 HMACs + within the given area. Keying material must also be configured on a + per-interface basis. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf area <number> range <A.B.C.D/M> [cost <number>] + + This command summarizes intra area paths from specified area into one + summary-LSA (Type-3) announced to other areas. This command can be used + only in ABR and ONLY router-LSAs (Type-1) and network-LSAs (Type-2) + (i.e. LSAs with scope area) can be summarized. AS-external-LSAs (Type-5) + can’t be summarized - their scope is AS. The optional argument + {cfgcmd}`cost` specifies the aggregated link metric. The metric range is 0 + to 16777215. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf area <number> range <A.B.C.D/M> not-advertise + + This command instead of summarizing intra area paths filter them - i.e. + intra area paths from this range are not advertised into other areas. + This command makes sense in ABR only. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf area <number> export-list <acl_number> + + Filter Type-3 summary-LSAs announced to other areas originated from + intra- area paths from specified area. + This command makes sense in ABR only. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf area <number> import-list <acl_number> + + Same as export-list, but it applies to paths announced into specified + area as Type-3 summary-LSAs. + This command makes sense in ABR only. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf area <number> range <A.B.C.D/M> substitute + <E.F.G.H/M> + + One Type-3 summary-LSA with routing info <E.F.G.H/M> is announced into + backbone area if defined area contains at least one intra-area network + (i.e. described with router-LSA or network-LSA) from range <A.B.C.D/M>. + This command makes sense in ABR only. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf area <number> shortcut <default|disable|enable> + + This parameter allows to "shortcut" routes (non-backbone) for inter-area + routes. There are three modes available for routes shortcutting: + + **default** – this area will be used for shortcutting only if ABR does not + have a link to the backbone area or this link was lost. + **enable** – the area will be used for shortcutting every time the route + that goes through it is cheaper. + **disable** – this area is never used by ABR for routes shortcutting. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf area <number> virtual-link <A.B.C.D> + + Provides a backbone area coherence by virtual link establishment. + + In general, OSPF protocol requires a backbone area (area 0) to be coherent + and fully connected. I.e. any backbone area router must have a route to any + other backbone area router. Moreover, every ABR must have a link to + backbone area. However, it is not always possible to have a physical link + to a backbone area. In this case between two ABR (one of them has a link to + the backbone area) in the area (not stub area) a virtual link is organized. + + <number> – area identifier through which a virtual link goes. + <A.B.C.D> – ABR router-id with which a virtual link is established. Virtual + link must be configured on both routers. + + Formally, a virtual link looks like a point-to-point network connecting two + ABR from one area one of which physically connected to a backbone area. + This pseudo-network is considered to belong to a backbone area. + +``` + +#### Interface Configuration + +```{eval-rst} +.. cfgcmd:: set protocols ospf interface <interface> area <x.x.x.x | x> + + Enable ospf on an interface and set associated area. + + If you have a lot of interfaces, and/or a lot of subnets, then enabling + OSPF via this command may result in a slight performance improvement. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf interface <interface> authentication + plaintext-password <text> + + This command sets OSPF authentication key to a simple password. After + setting, all OSPF packets are authenticated. Key has length up to 8 chars. + + Simple text password authentication is insecure and deprecated in favour of + MD5 HMAC authentication. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf interface <interface> authentication md5 + key-id <id> md5-key <text> + + This command specifys that MD5 HMAC authentication must be used on this + interface. It sets OSPF authentication key to a cryptographic password. + Key-id identifies secret key used to create the message digest. This ID + is part of the protocol and must be consistent across routers on a link. + The key can be long up to 16 chars (larger strings will be truncated), + and is associated with the given key-id. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf interface <interface> bandwidth <number> + + This command sets the interface bandwidth for cost calculations, where + bandwidth can be in range from 1 to 100000, specified in Mbits/s. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf interface <interface> cost <number> + + This command sets link cost for the specified interface. The cost value is + set to router-LSA’s metric field and used for SPF calculation. The cost + range is 1 to 65535. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf interface <interface> dead-interval <number> + + Set number of seconds for router Dead Interval timer value used for Wait + Timer and Inactivity Timer. This value must be the same for all routers + attached to a common network. The default value is 40 seconds. The + interval range is 1 to 65535. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf interface <interface> hello-multiplier <number> + + The hello-multiplier specifies how many Hellos to send per second, from 1 + (every second) to 10 (every 100ms). Thus one can have 1s convergence time + for OSPF. If this form is specified, then the hello-interval advertised in + Hello packets is set to 0 and the hello-interval on received Hello packets + is not checked, thus the hello-multiplier need NOT be the same across + multiple routers on a common link. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf interface <interface> hello-interval <number> + + Set number of seconds for Hello Interval timer value. Setting this value, + Hello packet will be sent every timer value seconds on the specified + interface. This value must be the same for all routers attached to a + common network. The default value is 10 seconds. The interval range is 1 + to 65535. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf interface <interface> bfd + + This command enables {abbr}`BFD (Bidirectional Forwarding Detection)` on + this OSPF link interface. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf interface <interface> mtu-ignore + + This command disables check of the MTU value in the OSPF DBD packets. Thus, + use of this command allows the OSPF adjacency to reach the FULL state even + though there is an interface MTU mismatch between two OSPF routers. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf interface <interface> network <type> + + This command allows to specify the distribution type for the network + connected to this interface: + + **broadcast** – broadcast IP addresses distribution. + **non-broadcast** – address distribution in NBMA networks topology. + **point-to-multipoint** – address distribution in point-to-multipoint + networks. + **point-to-point** – address distribution in point-to-point networks. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf interface <interface> priority <number> + + This command sets Router Priority integer value. The router with the + highest priority will be more eligible to become Designated Router. + Setting the value to 0, makes the router ineligible to become + Designated Router. The default value is 1. The interval range is 0 to 255. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf interface <interface> retransmit-interval + <number> + + This command sets number of seconds for RxmtInterval timer value. This + value is used when retransmitting Database Description and Link State + Request packets if acknowledge was not received. The default value is 5 + seconds. The interval range is 3 to 65535. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf interface <interface> transmit-delay <number> + + This command sets number of seconds for InfTransDelay value. It allows to + set and adjust for each interface the delay interval before starting the + synchronizing process of the router's database with all neighbors. The + default value is 1 seconds. The interval range is 3 to 65535. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf interface <interface> ldp-sync disable + + This command disables IGP-LDP sync for this specific interface. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf interface <interface> ldp-sync holddown + <seconds> + + This command will change the hold down value for IGP-LDP synchronization + during convergence/interface flap events, but for this interface only. +``` + +#### External Route Summarisation + +This feature summarises originated external LSAs (Type-5 and Type-7). Summary +Route will be originated on-behalf of all matched external LSAs. + +```{eval-rst} +.. cfgcmd:: set protocols ospf aggregation timer <seconds> + + Configure aggregation delay timer interval. + + Summarisation starts only after this delay timer expiry. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf summary-address x.x.x.x/y [tag (1-4294967295)] + + This command enable/disables summarisation for the configured address range. + + Tag is the optional parameter. If tag configured Summary route will be + originated with the configured tag. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf summary-address x.x.x.x/y no-advertise + + This command to ensure not advertise the summary lsa for the matched + external LSAs. +``` + +#### Graceful Restart + +```{eval-rst} +.. cfgcmd:: set protocols ospf graceful-restart [grace-period (1-1800)] + + Configure Graceful Restart {rfc}`3623` restarting support. When enabled, + the default grace period is 120 seconds. + + To perform a graceful shutdown, the FRR ``graceful-restart prepare ip + ospf`` EXEC-level command needs to be issued before restarting the + ospfd daemon. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf graceful-restart helper enable [router-id A.B.C.D] + + Configure Graceful Restart {rfc}`3623` helper support. By default, helper support + is disabled for all neighbours. This config enables/disables helper support + on this router for all neighbours. + + To enable/disable helper support for a specific neighbour, the router-id + (A.B.C.D) has to be specified. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf graceful-restart helper no-strict-lsa-checking + + By default `strict-lsa-checking` is configured then the helper will abort + the Graceful Restart when a LSA change occurs which affects the restarting + router. + + This command disables it. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf graceful-restart helper supported-grace-time + + Supports as HELPER for configured grace period. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf graceful-restart helper planned-only + + It helps to support as HELPER only for planned restarts. + + By default, it supports both planned and unplanned outages. +``` + +#### Manual Neighbor Configuration + +OSPF routing devices normally discover their neighbors dynamically by +listening to the broadcast or multicast hello packets on the network. +Because an NBMA network does not support broadcast (or multicast), the +device cannot discover its neighbors dynamically, so you must configure all +the neighbors statically. + +```{eval-rst} +.. cfgcmd:: set protocols ospf neighbor <A.B.C.D> + + This command specifies the IP address of the neighboring device. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf neighbor <A.B.C.D> poll-interval <seconds> + + This command specifies the length of time, in seconds, before the routing + device sends hello packets out of the interface before it establishes + adjacency with a neighbor. The range is 1 to 65535 seconds. The default + value is 60 seconds. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf neighbor <A.B.C.D> priority <number> + + This command specifies the router priority value of the nonbroadcast + neighbor associated with the IP address specified. The default is 0. + This keyword does not apply to point-to-multipoint interfaces. + +``` + +#### Redistribution Configuration + +```{eval-rst} +.. cfgcmd:: set protocols ospf redistribute <route source> + + This command redistributes routing information from the given route source + to the OSPF process. There are five modes available for route source: bgp, + connected, kernel, rip, static. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf default-metric <number> + + This command specifies the default metric value of redistributed routes. + The metric range is 0 to 16777214. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf redistribute <route source> metric <number> + + This command specifies metric for redistributed routes from the given + route source. There are five modes available for route source: bgp, + connected, kernel, rip, static. The metric range is 1 to 16777214. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf redistribute <route source> metric-type <1|2> + + This command specifies metric type for redistributed routes. Difference + between two metric types that metric type 1 is a metric which is + "commensurable" with inner OSPF links. When calculating a metric to the + external destination, the full path metric is calculated as a metric sum + path of a router which had advertised this link plus the link metric. + Thus, a route with the least summary metric will be selected. If external + link is advertised with metric type 2 the path is selected which lies + through the router which advertised this link with the least metric + despite of the fact that internal path to this router is longer (with more + cost). However, if two routers advertised an external link and with metric + type 2 the preference is given to the path which lies through the router + with a shorter internal path. If two different routers advertised two + links to the same external destimation but with different metric type, + metric type 1 is preferred. If type of a metric left undefined the router + will consider these external links to have a default metric type 2. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf redistribute <route source> route-map <name> + + This command allows to use route map to filter redistributed routes from + the given route source. There are five modes available for route source: + bgp, connected, kernel, rip, static. + +``` + +#### Operational Mode Commands + +```{eval-rst} +.. opcmd:: show ip ospf neighbor + + This command displays the neighbors status. +``` + +```none +Neighbor ID Pri State Dead Time Address Interface RXmtL RqstL DBsmL +10.0.13.1 1 Full/DR 38.365s 10.0.13.1 eth0:10.0.13.3 0 0 0 +10.0.23.2 1 Full/Backup 39.175s 10.0.23.2 eth1:10.0.23.3 0 0 0 +``` + +```{eval-rst} +.. opcmd:: show ip ospf neighbor detail + + This command displays the neighbors information in a detailed form, not + just a summary table. +``` + +```none + Neighbor 10.0.13.1, interface address 10.0.13.1 + In the area 0.0.0.0 via interface eth0 + Neighbor priority is 1, State is Full, 5 state changes + Most recent state change statistics: + Progressive change 11m55s ago + DR is 10.0.13.1, BDR is 10.0.13.3 + Options 2 *|-|-|-|-|-|E|- + Dead timer due in 34.854s + Database Summary List 0 + Link State Request List 0 + Link State Retransmission List 0 + Thread Inactivity Timer on + Thread Database Description Retransmision off + Thread Link State Request Retransmission on + Thread Link State Update Retransmission on + +Neighbor 10.0.23.2, interface address 10.0.23.2 + In the area 0.0.0.1 via interface eth1 + Neighbor priority is 1, State is Full, 4 state changes + Most recent state change statistics: + Progressive change 41.193s ago + DR is 10.0.23.3, BDR is 10.0.23.2 + Options 2 *|-|-|-|-|-|E|- + Dead timer due in 35.661s + Database Summary List 0 + Link State Request List 0 + Link State Retransmission List 0 + Thread Inactivity Timer on + Thread Database Description Retransmision off + Thread Link State Request Retransmission on + Thread Link State Update Retransmission on +``` + +```{eval-rst} +.. opcmd:: show ip ospf neighbor <A.B.C.D> + + This command displays the neighbors information in a detailed form for a + neighbor whose IP address is specified. +``` + +```{eval-rst} +.. opcmd:: show ip ospf neighbor <interface> + + This command displays the neighbors status for a neighbor on the specified + interface. +``` + +```{eval-rst} +.. opcmd:: show ip ospf interface [<interface>] + + This command displays state and configuration of OSPF the specified + interface, or all interfaces if no interface is given. +``` + +```none +eth0 is up + ifindex 2, MTU 1500 bytes, BW 4294967295 Mbit <UP,BROADCAST,RUNNING,MULTICAST> + Internet Address 10.0.13.3/24, Broadcast 10.0.13.255, Area 0.0.0.0 + MTU mismatch detection: enabled + Router ID 10.0.23.3, Network Type BROADCAST, Cost: 1 + Transmit Delay is 1 sec, State Backup, Priority 1 + Backup Designated Router (ID) 10.0.23.3, Interface Address 10.0.13.3 + Multicast group memberships: OSPFAllRouters OSPFDesignatedRouters + Timer intervals configured, Hello 10s, Dead 40s, Wait 40s, Retransmit 5 + Hello due in 4.470s + Neighbor Count is 1, Adjacent neighbor count is 1 +eth1 is up + ifindex 3, MTU 1500 bytes, BW 4294967295 Mbit <UP,BROADCAST,RUNNING,MULTICAST> + Internet Address 10.0.23.3/24, Broadcast 10.0.23.255, Area 0.0.0.1 + MTU mismatch detection: enabled + Router ID 10.0.23.3, Network Type BROADCAST, Cost: 1 + Transmit Delay is 1 sec, State DR, Priority 1 + Backup Designated Router (ID) 10.0.23.2, Interface Address 10.0.23.2 + Saved Network-LSA sequence number 0x80000002 + Multicast group memberships: OSPFAllRouters OSPFDesignatedRouters + Timer intervals configured, Hello 10s, Dead 40s, Wait 40s, Retransmit 5 + Hello due in 4.563s + Neighbor Count is 1, Adjacent neighbor count is 1 +``` + +```{eval-rst} +.. opcmd:: show ip ospf route [detail] + + This command displays the OSPF routing table, as determined by the most + recent SPF calculation. With the optional {cfgcmd}`detail` argument, + each route item's advertiser router and network attribute will be shown. +``` + +```none +============ OSPF network routing table ============ +N IA 10.0.12.0/24 [3] area: 0.0.0.0 + via 10.0.13.3, eth0 +N 10.0.13.0/24 [1] area: 0.0.0.0 + directly attached to eth0 +N IA 10.0.23.0/24 [2] area: 0.0.0.0 + via 10.0.13.3, eth0 +N 10.0.34.0/24 [2] area: 0.0.0.0 + via 10.0.13.3, eth0 + +============ OSPF router routing table ============= +R 10.0.23.3 [1] area: 0.0.0.0, ABR + via 10.0.13.3, eth0 +R 10.0.34.4 [2] area: 0.0.0.0, ASBR + via 10.0.13.3, eth0 + +============ OSPF external routing table =========== +N E2 172.16.0.0/24 [2/20] tag: 0 + via 10.0.13.3, eth0 +``` + +The table consists of following data: + +**OSPF network routing table** – includes a list of acquired routes for all +accessible networks (or aggregated area ranges) of OSPF system. "IA" flag +means that route destination is in the area to which the router is not +connected, i.e. it’s an inter-area path. In square brackets a summary metric +for all links through which a path lies to this network is specified. "via" +prefix defines a router-gateway, i.e. the first router on the way to the +destination (next hop). +**OSPF router routing table** – includes a list of acquired routes to all +accessible ABRs and ASBRs. +**OSPF external routing table** – includes a list of acquired routes that are +external to the OSPF process. "E" flag points to the external link metric type +(E1 – metric type 1, E2 – metric type 2). External link metric is printed in +the "\<metric of the router which advertised the link>/\<link metric>" format. + +```{eval-rst} +.. opcmd:: show ip ospf border-routers + + This command displays a table of paths to area boundary and autonomous + system boundary routers. +``` + +```{eval-rst} +.. opcmd:: show ip ospf database + + This command displays a summary table with a database contents (LSA). +``` + +```none + OSPF Router with ID (10.0.13.1) + + Router Link States (Area 0.0.0.0) + +Link ID ADV Router Age Seq# CkSum Link count +10.0.13.1 10.0.13.1 984 0x80000005 0xd915 1 +10.0.23.3 10.0.23.3 1186 0x80000008 0xfe62 2 +10.0.34.4 10.0.34.4 1063 0x80000004 0x4e3f 1 + + Net Link States (Area 0.0.0.0) + +Link ID ADV Router Age Seq# CkSum +10.0.13.1 10.0.13.1 994 0x80000003 0x30bb +10.0.34.4 10.0.34.4 1188 0x80000001 0x9411 + + Summary Link States (Area 0.0.0.0) + +Link ID ADV Router Age Seq# CkSum Route +10.0.12.0 10.0.23.3 1608 0x80000001 0x6ab6 10.0.12.0/24 +10.0.23.0 10.0.23.3 981 0x80000003 0xe232 10.0.23.0/24 + + AS External Link States + +Link ID ADV Router Age Seq# CkSum Route +172.16.0.0 10.0.34.4 1063 0x80000001 0xc40d E2 172.16.0.0/24 [0x0] +``` + +```{eval-rst} +.. opcmd:: show ip ospf database <type> [A.B.C.D] + [adv-router <A.B.C.D>|self-originate] + + This command displays a database contents for a specific link advertisement + type. + + The type can be the following: + asbr-summary, external, network, nssa-external, opaque-area, opaque-as, + opaque-link, router, summary. + + [A.B.C.D] – link-state-id. With this specified the command displays portion + of the network environment that is being described by the advertisement. + The value entered depends on the advertisement’s LS type. It must be + entered in the form of an IP address. + + {cfgcmd}`adv-router <A.B.C.D>` – router id, which link advertisements need + to be reviewed. + + {cfgcmd}`self-originate` displays only self-originated LSAs from the local + router. +``` + +```none + OSPF Router with ID (10.0.13.1) + + Router Link States (Area 0.0.0.0) + +LS age: 1213 +Options: 0x2 : *|-|-|-|-|-|E|- +LS Flags: 0x3 +Flags: 0x0 +LS Type: router-LSA +Link State ID: 10.0.13.1 +Advertising Router: 10.0.13.1 +LS Seq Number: 80000009 +Checksum: 0xd119 +Length: 36 + + Number of Links: 1 + + Link connected to: a Transit Network + (Link ID) Designated Router address: 10.0.13.1 + (Link Data) Router Interface address: 10.0.13.1 + Number of TOS metrics: 0 + TOS 0 Metric: 1 +``` + +```{eval-rst} +.. opcmd:: show ip ospf database max-age + + This command displays LSAs in MaxAge list. + +``` + +#### Examples + +##### Enable OSPF + +**Node 1** + +```none +set interfaces loopback lo address 10.1.1.1/32 +set interfaces ethernet eth0 address 192.168.0.1/24 +set protocols ospf area 0 network 192.168.0.0/24 +set protocols ospf area 0 network 10.1.1.1/32 +set protocols ospf parameters router-id 10.1.1.1 +``` + +**Node 2** + +```none +set interfaces loopback lo address 10.1.1.2/32 +set interfaces ethernet eth0 address 192.168.0.2/24 +set protocols ospf area 0 network 192.168.0.0/24 +set protocols ospf area 0 network 10.1.1.2/32 +set protocols ospf parameters router-id 10.1.1.2 +``` + +Here's the neighbors up: + +```none +Node-1@vyos:~$ show ip ospf neighbor + +Neighbor ID Pri State Up Time Dead Time Address Interface RXmtL RqstL DBsmL +10.1.1.2 1 Full/DR 3m43s 36.094s 192.168.0.2 eth0:192.168.0.1 0 0 0 + + + +Node-2@vyos:~$ show ip ospf neighbor + +Neighbor ID Pri State Up Time Dead Time Address Interface RXmtL RqstL DBsmL +10.1.1.1 1 Full/Backup 3m47s 31.736s 192.168.0.1 eth0:192.168.0.2 0 0 0 +``` + +Here's the routes: + +```none +Node-1@vyos:~$ show ip route ospf +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +O 10.1.1.1/32 [110/0] is directly connected, lo, weight 1, 00:00:14 +O>* 10.1.1.2/32 [110/1] via 192.168.0.2, eth0, weight 1, 00:00:07 +O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:32 + +Node-2@vyos:~$ show ip route ospf +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +O>* 10.1.1.1/32 [110/1] via 192.168.0.1, eth0, weight 1, 00:00:11 +O 10.1.1.2/32 [110/0] is directly connected, lo, weight 1, 00:00:04 +O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:18 +``` + +##### Enable OSPF with route redistribution of the loopback and default originate: + +**Node 1** + +```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** + +```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 +``` + +##### Enable OSPF and IGP-LDP synchronization: + +**Node 1:** + +```none +set interfaces loopback lo address 10.1.1.1/32 +set interfaces ethernet eth0 address 192.168.0.1/24 + +set protocols ospf area 0 network '192.168.0.0/24' +set protocols ospf area 0 network '10.1.1.1/32' +set protocols ospf parameters router-id '10.1.1.1' +set protocols ospf ldp-sync + +set protocols mpls interface eth0 +set protocols mpls ldp discovery transport-ipv4-address 10.1.1.1 +set protocols mpls ldp interface lo +set protocols mpls ldp interface eth0 +set protocols mpls ldp parameters transport-prefer-ipv4 +set protocols mpls ldp router-id 10.1.1.1 +``` + +This gives us IGP-LDP synchronization for all non-loopback interfaces with +a holddown timer of zero seconds: + +```none +Node-1@vyos:~$ show ip ospf mpls ldp-sync + eth0 + LDP-IGP Synchronization enabled: yes + Holddown timer in seconds: 0 + State: Sync achieved +``` + +##### Enable OSPF with Segment Routing (Experimental): + +**Node 1** + +```none +set interfaces loopback lo address 10.1.1.1/32 +set interfaces ethernet eth0 address 192.168.0.1/24 + +set protocols ospf area 0 network '192.168.0.0/24' +set protocols ospf area 0 network '10.1.1.1/32' +set protocols ospf parameters opaque-lsa +set protocols ospf parameters router-id '10.1.1.1' +set protocols ospf segment-routing global-block high-label-value '1100' +set protocols ospf segment-routing global-block low-label-value '1000' +set protocols ospf segment-routing prefix 10.1.1.1/32 index explicit-null +set protocols ospf segment-routing prefix 10.1.1.1/32 index value '1' +``` + +**Node 2** + +```none +set interfaces loopback lo address 10.1.1.2/32 +set interfaces ethernet eth0 address 192.168.0.2/24 + +set protocols ospf area 0 network '192.168.0.0/24' +set protocols ospf area 0 network '10.1.1.2/32' +set protocols ospf parameters opaque-lsa +set protocols ospf parameters router-id '10.1.1.2' +set protocols ospf segment-routing global-block high-label-value '1100' +set protocols ospf segment-routing global-block low-label-value '1000' +set protocols ospf segment-routing prefix 10.1.1.2/32 index explicit-null +set protocols ospf segment-routing prefix 10.1.1.2/32 index value '2' +``` + +This gives us MPLS segment routing enabled and labels for far end loopbacks: + +```none +Node-1@vyos:~$ show mpls table + Inbound Label Type Nexthop Outbound Label + ----------------------------------------------------------- + 1002 SR (OSPF) 192.168.0.2 IPv4 Explicit Null <-- Node-2 loopback learned on Node-1 + 15000 SR (OSPF) 192.168.0.2 implicit-null + 15001 SR (OSPF) 192.168.0.2 implicit-null + +Node-2@vyos:~$ show mpls table + Inbound Label Type Nexthop Outbound Label + ----------------------------------------------------------- + 1001 SR (OSPF) 192.168.0.1 IPv4 Explicit Null <-- Node-1 loopback learned on Node-2 + 15000 SR (OSPF) 192.168.0.1 implicit-null + 15001 SR (OSPF) 192.168.0.1 implicit-null +``` + +Here is the routing tables showing the MPLS segment routing label operations: + +```none +Node-1@vyos:~$ show ip route ospf +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +O 10.1.1.1/32 [110/0] is directly connected, lo, weight 1, 00:03:43 +O>* 10.1.1.2/32 [110/1] via 192.168.0.2, eth0, label IPv4 Explicit Null, weight 1, 00:03:32 +O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:43 + +Node-2@vyos:~$ show ip route ospf +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +O>* 10.1.1.1/32 [110/1] via 192.168.0.1, eth0, label IPv4 Explicit Null, weight 1, 00:03:36 +O 10.1.1.2/32 [110/0] is directly connected, lo, weight 1, 00:03:51 +O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:51 +``` + +(routing-ospfv3)= + +## OSPFv3 (IPv6) + +(ospf-v3-configuration)= + +### Configuration + +(ospf-v3-general)= + +#### General + +VyOS does not have a special command to start the OSPFv3 process. The OSPFv3 +process starts when the first ospf enabled interface is configured. + +```{eval-rst} +.. cfgcmd:: set protocols ospfv3 interface <interface> area <number> + + This command specifies the OSPFv3 enabled interface. This command is also + used to enable the OSPF process. The area number can be specified in + decimal notation in the range from 0 to 4294967295. Or it can be specified + in dotted decimal notation similar to ip address. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospfv3 parameters router-id <rid> + + This command sets the router-ID of the OSPFv3 process. The router-ID may be + an IP address of the router, but need not be – it can be any arbitrary + 32bit number. However it MUST be unique within the entire OSPFv3 domain to + the OSPFv3 speaker – bad things will happen if multiple OSPFv3 speakers are + configured with the same router-ID! + +``` + +(ospf-v3-optional)= + +#### Optional + +```{eval-rst} +.. cfgcmd:: set protocols ospfv3 distance global <distance> + + This command change distance value of OSPFv3 globally. + The distance range is 1 to 255. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospfv3 distance ospfv3 + <external|inter-area|intra-area> <distance> + + This command change distance value of OSPFv3. The arguments are the + distance values for external routes, inter-area routes and intra-area + routes respectively. The distance range is 1 to 255. +``` + +(ospf-v3-area-configuration)= + +#### Area Configuration + +```{eval-rst} +.. cfgcmd:: set protocols ospfv3 area <number> range <prefix> + + This command summarizes intra area paths from specified area into one + Type-3 Inter-Area Prefix LSA announced to other areas. This command can be + used only in ABR. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospfv3 area <number> range <prefix> not-advertise + + This command instead of summarizing intra area paths filter them - i.e. + intra area paths from this range are not advertised into other areas. This + command makes sense in ABR only. +``` + +(ospf-v3-interface-config)= + +#### Interface Configuration + +```{eval-rst} +.. cfgcmd:: set protocols ospfv3 interface <interface> ipv6 cost <number> + + This command sets link cost for the specified interface. The cost value is + set to router-LSA’s metric field and used for SPF calculation. The cost + range is 1 to 65535. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospfv3 interface <interface> dead-interval <number> + + Set number of seconds for router Dead Interval timer value used for Wait + Timer and Inactivity Timer. This value must be the same for all routers + attached to a common network. The default value is 40 seconds. The + interval range is 1 to 65535. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospfv3 interface <interface> hello-interval + <number> + + Set number of seconds for Hello Interval timer value. Setting this value, + Hello packet will be sent every timer value seconds on the specified + interface. This value must be the same for all routers attached to a + common network. The default value is 10 seconds. The interval range is 1 + to 65535. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospfv3 interface <interface> mtu-ignore + + This command disables check of the MTU value in the OSPF DBD packets. + Thus, use of this command allows the OSPF adjacency to reach the FULL + state even though there is an interface MTU mismatch between two OSPF + routers. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospfv3 interface <interface> network <type> + + This command allows to specify the distribution type for the network + connected to this interface: + + **broadcast** – broadcast IP addresses distribution. + **point-to-point** – address distribution in point-to-point networks. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospfv3 interface <interface> priority <number> + + This command sets Router Priority integer value. The router with the + highest priority will be more eligible to become Designated Router. + Setting the value to 0, makes the router ineligible to become Designated + Router. The default value is 1. The interval range is 0 to 255. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospfv3 interface <interface> passive + + This command specifies interface as passive. Passive interface advertises + its address, but does not run the OSPF protocol (adjacencies are not formed + and hello packets are not generated). +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospfv3 interface <interface> retransmit-interval + <number> + + This command sets number of seconds for RxmtInterval timer value. This + value is used when retransmitting Database Description and Link State + Request packets if acknowledge was not received. The default value is 5 + seconds. The interval range is 3 to 65535. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospfv3 interface <interface> transmit-delay + <number> + + This command sets number of seconds for InfTransDelay value. It allows to + set and adjust for each interface the delay interval before starting the + synchronizing process of the router's database with all neighbors. The + default value is 1 seconds. The interval range is 3 to 65535. +``` + +(ospf-v3-graceful-restart)= + +#### Graceful Restart + +```{eval-rst} +.. cfgcmd:: set protocols ospfv3 graceful-restart [grace-period (1-1800)] + + Configure Graceful Restart {rfc}`3623` restarting support. When enabled, + the default grace period is 120 seconds. + + To perform a graceful shutdown, the FRR ``graceful-restart prepare ip + ospf`` EXEC-level command needs to be issued before restarting the + ospfd daemon. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospfv3 graceful-restart helper enable [router-id A.B.C.D] + + Configure Graceful Restart {rfc}`3623` helper support. By default, helper support + is disabled for all neighbours. This config enables/disables helper support + on this router for all neighbours. + + To enable/disable helper support for a specific neighbour, the router-id + (A.B.C.D) has to be specified. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospfv3 graceful-restart helper lsa-check-disable + + By default `strict-lsa-checking` is configured then the helper will abort + the Graceful Restart when a LSA change occurs which affects the restarting + router. + + This command disables it. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospfv3 graceful-restart helper supported-grace-time + + Supports as HELPER for configured grace period. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospfv3 graceful-restart helper planned-only + + It helps to support as HELPER only for planned restarts. + + By default, it supports both planned and unplanned outages. +``` + +(ospf-v3-redistribution-config)= + +#### Redistribution Configuration + +```{eval-rst} +.. cfgcmd:: set protocols ospfv3 redistribute <route source> + + This command redistributes routing information from the given route source + to the OSPFv3 process. There are five modes available for route source: + bgp, connected, kernel, ripng, static. +``` + +```{eval-rst} +.. cfgcmd:: set protocols ospf redistribute <route source> route-map <name> + + This command allows to use route map to filter redistributed routes from + given route source. There are five modes available for route source: bgp, + connected, kernel, ripng, static. +``` + +(ospf-v3-op-cmd)= + +#### Operational Mode Commands + +```{eval-rst} +.. opcmd:: show ipv6 ospfv3 neighbor + + This command displays the neighbors status. +``` + +```{eval-rst} +.. opcmd:: show ipv6 ospfv3 neighbor detail + + This command displays the neighbors information in a detailed form, not + just a summary table. +``` + +```{eval-rst} +.. opcmd:: show ipv6 ospfv3 neighbor drchoice + + This command displays the neighbor DR choice information. +``` + +```{eval-rst} +.. opcmd:: show ipv6 ospfv3 interface [prefix]|[<interface> [prefix]] + + This command displays state and configuration of OSPF the specified + interface, or all interfaces if no interface is given. Whith the argument + {cfgcmd}`prefix` this command shows connected prefixes to advertise. +``` + +```{eval-rst} +.. opcmd:: show ipv6 ospfv3 route + + This command displays the OSPF routing table, as determined by the most + recent SPF calculation. +``` + +```{eval-rst} +.. opcmd:: show ipv6 ospfv3 border-routers + + This command displays a table of paths to area boundary and autonomous + system boundary routers. +``` + +```{eval-rst} +.. opcmd:: show ipv6 ospfv3 database + + This command displays a summary table with a database contents (LSA). +``` + +```{eval-rst} +.. opcmd:: show ipv6 ospfv3 database <type> [A.B.C.D] + [adv-router <A.B.C.D>|self-originate] + + This command displays a database contents for a specific link + advertisement type. +``` + +```{eval-rst} +.. opcmd:: show ipv6 ospfv3 redistribute + + This command displays external information redistributed into OSPFv3 +``` + +(ospf-v3-config-example)= + +#### Configuration Example + +A typical configuration using 2 nodes. + +**Node 1:** + +```none +set protocols ospfv3 interface eth1 area 0.0.0.0 +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:** + +```none +set protocols ospfv3 interface eth1 area 0.0.0.0 +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 +``` + +**To see the redistributed routes:** + +```none +show ipv6 ospfv3 redistribute +``` + +:::{note} +You cannot 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 {vytask}`T1483`. +::: + +Example configuration for WireGuard interfaces: + +**Node 1** + +```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 interface 'wg01' area 0.0.0.0 +set protocols ospfv3 interface 'lo' area 0.0.0.0 +``` + +**Node 2** + +```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 interface 'wg01' area 0.0.0.0 +set protocols ospfv3 interface 'lo' area 0.0.0.0 +``` + +**Status** + +```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] +``` diff --git a/docs/configuration/protocols/md-pim.md b/docs/configuration/protocols/md-pim.md new file mode 100644 index 00000000..1768be72 --- /dev/null +++ b/docs/configuration/protocols/md-pim.md @@ -0,0 +1,304 @@ +--- +lastproofread: '2023-11-13' +--- + +(pim)= + +# PIM – Protocol Independent Multicast + +VyOS supports {abbr}`PIM-SM (PIM Sparse Mode)` as well as +{abbr}`IGMP (Internet Group Management Protocol)` v2 and v3 + +{abbr}`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 {abbr}`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). + +## PIM-SM - PIM Sparse Mode + +```{eval-rst} +.. cfgcmd:: set protocols pim ecmp + + If PIM has the a choice of ECMP nexthops for a particular + {abbr}`RPF (Reverse Path Forwarding)`, PIM will cause S,G flows to be + spread out amongst the nexthops. If this command is not specified then + the first nexthop found will be used. +``` + +```{eval-rst} +.. cfgcmd:: set protocols pim ecmp rebalance + + If PIM is using ECMP and an interface goes down, cause PIM to rebalance all + S,G flows across the remaining nexthops. If this command is not configured + PIM only modifies those S,G flows that were using the interface that went + down. +``` + +```{eval-rst} +.. cfgcmd:: set protocols pim join-prune-interval <n> + + Modify the join/prune interval that PIM uses to the new value. Time is + specified in seconds. + + The default time is 60 seconds. + + If you enter a value smaller than 60 seconds be aware that this can and + will affect convergence at scale. +``` + +```{eval-rst} +.. cfgcmd:: set protocols pim keep-alive-timer <n> + + Modify the time out value for a S,G flow from 1-65535 seconds. If choosing + a value below 31 seconds be aware that some hardware platforms cannot see + data flowing in better than 30 second chunks. +``` + +```{eval-rst} +.. cfgcmd:: set protocols pim packets <n> + + When processing packets from a neighbor process the number of packets + incoming at one time before moving on to the next task. + + The default value is 3 packets. + + This command is only useful at scale when you can possibly have a large + number of PIM control packets flowing. +``` + +```{eval-rst} +.. cfgcmd:: set protocols pim register-accept-list <prefix-list> + + When PIM receives a register packet the source of the packet will be compared + to the prefix-list specified, and if a permit is received normal processing + continues. If a deny is returned for the source address of the register packet + a register stop message is sent to the source. +``` + +```{eval-rst} +.. cfgcmd:: set protocols pim register-suppress-time <n> + + Modify the time that pim will register suppress a FHR will send register + notifications to the kernel. +``` + +```{eval-rst} +.. cfgcmd:: set protocols pim rp <address> group <group> + + In order to use PIM, it is necessary to configure a {abbr}`RP (Rendezvous Point)` + for join messages to be sent to. Currently the only methodology to do this is + via static rendezvous point commands. + + All routers in the PIM network must agree on these values. + + The first ip address is the RP's address and the second value is the matching + prefix of group ranges covered. +``` + +```{eval-rst} +.. cfgcmd:: set protocols pim rp keep-alive-timer <n> + + Modify the time out value for a S,G flow from 1-65535 seconds at + {abbr}`RP (Rendezvous Point)`. The normal keepalive period for the KAT(S,G) + defaults to 210 seconds. However, at the {abbr}`RP (Rendezvous Point)`, the + keepalive period must be at least the Register_Suppression_Time, or the RP + may time out the (S,G) state before the next Null-Register arrives. + Thus, the KAT(S,G) is set to max(Keepalive_Period, RP_Keepalive_Period) + when a Register-Stop is sent. + + If choosing a value below 31 seconds be aware that some hardware platforms + cannot see data flowing in better than 30 second chunks. + + See {rfc}`7761#section-4.1` for details. +``` + +```{eval-rst} +.. cfgcmd:: set protocols pim no-v6-secondary + + When sending PIM hello packets tell PIM to not send any v6 secondary + addresses on the interface. This information is used to allow PIM to use v6 + nexthops in it's decision for {abbr}`RPF (Reverse Path Forwarding)` lookup + if this option is not set (default). +``` + +```{eval-rst} +.. cfgcmd:: set protocols pim spt-switchover infinity-and-beyond [prefix-list <list>] + + On the last hop router if it is desired to not switch over to the SPT tree + configure this command. + + Optional parameter prefix-list can be use to control which groups to switch or + not switch. If a group is PERMIT as per the prefix-list, then the SPT switchover + does not happen for it and if it is DENY, then the SPT switchover happens. +``` + +```{eval-rst} +.. cfgcmd:: set protocols pim ssm prefix-list <list> + + Specify a range of group addresses via a prefix-list that forces PIM to never + do {abbr}`SSM (Source-Specific Multicast)` over. +``` + +### Interface specific commands + +```{eval-rst} +.. cfgcmd:: set protocols pim interface <interface> bfd [profile <name>] + + Automatically create BFD session for each RIP peer discovered in this + interface. When the BFD session monitor signalize that the link is down + the RIP peer is removed and all the learned routes associated with that + peer are removed. + + If optional profile parameter is used, select a BFD profile for the BFD + sessions created via this interface. +``` + +```{eval-rst} +.. cfgcmd:: set protocols pim interface <interface> dr-priority <n> + + Set the {abbr}`DR (Designated Router)` Priority for the interface. + This command is useful to allow the user to influence what node becomes + the DR for a LAN segment. +``` + +```{eval-rst} +.. cfgcmd:: set protocols pim interface <interface> hello <n> + + Set the PIM hello and hold interval for a interface. +``` + +```{eval-rst} +.. cfgcmd:: set protocols pim interface <interface> no-bsm + + Tell PIM that we would not like to use this interface to process + bootstrap messages. +``` + +```{eval-rst} +.. cfgcmd:: set protocols pim interface <interface> no-unicast-bsm + + Tell PIM that we would not like to use this interface to process + unicast bootstrap messages. +``` + +```{eval-rst} +.. cfgcmd:: set protocols pim interface <interface> passive + + Disable sending and receiving PIM control packets on the interface. + + .. cfgcmd:: set protocols pim interface <interface> source-address <ip-address> + + If you have multiple addresses configured on a particular interface and would + like PIM to use a specific source address associated with that interface. +``` + +## IGMP - Internet Group Management Protocol) + +```{eval-rst} +.. cfgcmd:: set protocols pim igmp watermark-warning <n> + + Configure watermark warning generation for an IGMP group limit. Generates + warning once the configured group limit is reached while adding new groups. +``` + +(pim-igmp-interface-commands)= + +### Interface specific commands + +```{eval-rst} +.. cfgcmd:: set protocols pim interface <interface> igmp + join <multicast-address> source-address <IP-address> + + Use this command to allow the selected interface to join a multicast + group defining the multicast address you want to join and the source + IP address too. +``` + +```{eval-rst} +.. cfgcmd:: set protocols pim interface <interface> igmp + 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. +``` + +```{eval-rst} +.. cfgcmd:: set protocols pim interface <interface> igmp + query-max-response-time <n> + + 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 assumed the (S,G) or + (\*,G) state {rfc}`7761#section-4.1` has timed out. +``` + +```{eval-rst} +.. cfgcmd:: set protocols pim interface <interface> igmp 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. +``` + +#### Example + +In the following example we can see a basic multicast setup: + +```{image} /_static/images/multicast-basic.png +:align: center +:alt: Network Topology Diagram +:width: 90% +``` + +**Router 1** + +```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** + +```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** + +```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' +``` diff --git a/docs/configuration/protocols/md-pim6.md b/docs/configuration/protocols/md-pim6.md new file mode 100644 index 00000000..707ae606 --- /dev/null +++ b/docs/configuration/protocols/md-pim6.md @@ -0,0 +1,100 @@ +(pim6)= + +# PIM6 - Protocol Independent Multicast for IPv6 + +VyOS facilitates IPv6 Multicast by supporting **PIMv6** and **MLD**. + +PIMv6 (Protocol Independent Multicast for IPv6) 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 MLD (Multicast Listener Discovery). + +Multicast receivers will talk MLD to their local router, so, besides having +PIMv6 configured in every router, MLD must also be configured in any router +where there could be a multicast receiver locally connected. + +VyOS supports both MLD version 1 and version 2 +(which allows source-specific multicast). + +## Basic commands + +These are the commands for a basic setup. + +```{cfgcmd} set protocols pim6 interface \<interface-name\> + + Use this command to enable PIMv6 in the selected interface so that it + can communicate with PIMv6 neighbors. This command also enables MLD reports + and query on the interface unless {cfgcmd}`mld disable` is configured. +``` + + +```{cfgcmd} set protocols pim6 interface \<interface-name\> mld disable + +Disable MLD reports and query on the interface. +``` + + +## Tuning commands + +You can also tune multicast with the following commands. + +```{cfgcmd} set protocols pim6 interface \<interface-name\> mld interval \<seconds\> + +Use this command to configure in the selected interface the MLD +host query interval (1-65535) in seconds that PIM will use. +The default value is 125 seconds. +``` + +```{cfgcmd} set protocols pim6 interface \<interface-name\> mld join \<multicast-address\> + +Use this command to allow the selected interface to join a multicast group. +``` + +```{cfgcmd} set protocols pim6 interface \<interface-name\> mld join \<multicast-address\> source \<source-address\> + +Use this command to allow the selected interface to join a source-specific multicast +group. +``` + +```{cfgcmd} set protocols pim6 interface \<interface-name\> mld last-member-query-count \<count\> + +Set the MLD last member query count. The default value is 2. +``` + +```{cfgcmd} set protocols pim6 interface \<interface-name\> mld last-member-query-interval \<milliseconds\> + +Set the MLD last member query interval in milliseconds (100-6553500). The default value is 1000 milliseconds. +``` + +```{cfgcmd} set protocols pim6 interface \<interface-name\> mld max-response-time \<milliseconds\> + +Set the MLD query response timeout in milliseconds (100-6553500). The default value is 10000 milliseconds. +``` + +```{cfgcmd} set protocols pim6 interface \<interface-name\> mld version \<version-number\> + +Set the MLD version used on this interface. The default value is 2. +``` + + +### Configuration Example + +To enable MLD reports and query on interfaces `eth0` and `eth1`: + +```none +set protocols pim6 interface eth0 +set protocols pim6 interface eth1 +``` + +The following configuration explicitly joins multicast group `ff15::1234` on interface `eth1` +and source-specific multicast group `ff15::5678` with source address `2001:db8::1` on interface +`eth1`: + +```none +set protocols pim6 interface eth0 mld join ff15::1234 +set protocols pim6 interface eth1 mld join ff15::5678 source 2001:db8::1 +``` diff --git a/docs/configuration/protocols/md-rip.md b/docs/configuration/protocols/md-rip.md new file mode 100644 index 00000000..684337d6 --- /dev/null +++ b/docs/configuration/protocols/md-rip.md @@ -0,0 +1,294 @@ +--- +lastproofread: '2021-10-04' +--- + +(rip)= + +# RIP + +{abbr}`RIP (Routing Information Protocol)` is a widely deployed interior gateway +protocol. RIP was developed in the 1970s at Xerox Labs as part of the XNS +routing protocol. RIP is a distance-vector protocol and is based on the +Bellman-Ford algorithms. As a distance-vector protocol, RIP router send updates +to its neighbors periodically, thus allowing the convergence to a known +topology. In each update, the distance to any given network will be broadcast +to its neighboring router. + +Supported versions of RIP are: + +> - RIPv1 as described in {rfc}`1058` +> - RIPv2 as described in {rfc}`2453` + +## General Configuration + +```{cfgcmd} set protocols rip network \<A.B.C.D/M\> + +This command enables RIP and sets the RIP enable interface by NETWORK. +The interfaces which have addresses matching with NETWORK are enabled. +``` + + +```{cfgcmd} set protocols rip interface \<interface\> + +This command specifies a RIP enabled interface by interface name. Both +the sending and receiving of RIP packets will be enabled on the port +specified in this command. +``` + + +```{cfgcmd} set protocols rip neighbor \<A.B.C.D\> + +This command specifies a RIP neighbor. When a neighbor doesn’t understand +multicast, this command is used to specify neighbors. In some cases, not +all routers will be able to understand multicasting, where packets are +sent to a network or a group of addresses. In a situation where a neighbor +cannot process multicast packets, it is necessary to establish a direct +link between routers. +``` + + +```{cfgcmd} set protocols rip passive-interface interface \<interface\> + +This command sets the specified interface to passive mode. On passive mode +interface, all receiving packets are processed as normal and VyOS does not +send either multicast or unicast RIP packets except to RIP neighbors +specified with neighbor command. +``` + + +```{cfgcmd} set protocols rip passive-interface interface default + +This command specifies all interfaces to passive mode. +``` + +## Optional Configuration + +```{cfgcmd} set protocols rip default-distance \<distance\> + +This command change the distance value of RIP. The distance range is 1 to 255. + +> :::{note} +> Routes with a distance of 255 are effectively disabled and not +> installed into the kernel. +> ::: +``` + + +```{cfgcmd} set protocols rip network-distance \<A.B.C.D/M\> distance \<distance\> + +This command sets default RIP distance to a specified value when the routes +source IP address matches the specified prefix. +``` + + +```{cfgcmd} set protocols rip network-distance \<A.B.C.D/M\> access-list \<name\> + +This command can be used with previous command to sets default RIP distance +to specified value when the route source IP address matches the specified +prefix and the specified access-list. +``` + + +```{cfgcmd} set protocols rip default-information originate + +This command generate a default route into the RIP. +``` + + +```{cfgcmd} set protocols rip distribute-list access-list \<in|out\> \<number\> + +This command can be used to filter the RIP path using access lists. +{cfgcmd}`in` and {cfgcmd}`out` this is the direction in which the access +lists are applied. +``` + + +```{cfgcmd} set protocols rip distribute-list interface \<interface\> access-list \<in|out\> \<number\> + +This command allows you apply access lists to a chosen interface to +filter the RIP path. +``` + + +```{cfgcmd} set protocols rip distribute-list prefix-list \<in|out\> \<name\> + +This command can be used to filter the RIP path using prefix lists. +{cfgcmd}`in` and {cfgcmd}`out` this is the direction in which the prefix +lists are applied. +``` + + +```{cfgcmd} set protocols rip distribute-list interface \<interface\> prefix-list \<in|out\> \<name\> + +This command allows you apply prefix lists to a chosen interface to +filter the RIP path. +``` + + +```{cfgcmd} set protocols rip route \<A.B.C.D/M\> + +This command is specific to FRR and VyOS. The route command makes a static +route only inside RIP. This command should be used only by advanced users +who are particularly knowledgeable about the RIP protocol. In most cases, +we recommend creating a static route in VyOS and redistributing it in RIP +using {cfgcmd}`redistribute static`. +``` + + +```{cfgcmd} set protocols rip timers update \<seconds\> + +This command specifies the update timer. Every update timer seconds, the +RIP process is awakened to send an unsolicited response message containing +the complete routing table to all neighboring RIP routers. The time range +is 5 to 2147483647. The default value is 30 seconds. +``` + + +```{cfgcmd} set protocols rip timers timeout \<seconds\> + +This command specifies the timeout timer. Upon expiration of the timeout, +the route is no longer valid; however, it is retained in the routing table +for a short time so that neighbors can be notified that the route has been +dropped. The time range is 5 to 2147483647. The default value is 180 +seconds. +``` + + +```{cfgcmd} set protocols rip timers garbage-collection \<seconds\> + +This command specifies the garbage-collection timer. Upon expiration of +the garbage-collection timer, the route is finally removed from the +routing table. The time range is 5 to 2147483647. The default value is 120 +seconds. +``` + +## Redistribution Configuration + +```{cfgcmd} set protocols rip redistribute \<route source\> + +This command redistributes routing information from the given route source +into the RIP tables. There are five modes available for route source: bgp, +connected, kernel, ospf, static. +``` + + +```{cfgcmd} set protocols rip redistribute \<route source\> metric \<metric\> + +This command specifies metric for redistributed routes from the given route +source. There are five modes available for route source: bgp, connected, +kernel, ospf, static. The metric range is 1 to 16. +``` + + +```{cfgcmd} set protocols rip redistribute \<route source\> route-map \<name\> + +This command allows to use route map to filter redistributed routes from +the given route source. There are five modes available for route source: +bgp, connected, kernel, ospf, static. +``` + + +```{cfgcmd} set protocols rip default-metric \<metric\> + +This command modifies the default metric (hop count) value for redistributed +routes. The metric range is 1 to 16. The default value is 1. This command +does not affect connected route even if it is redistributed by +{cfgcmd}`redistribute connected`. To modify connected routes metric +value, please use {cfgcmd}`redistribute connected metric`. +``` + +## Interfaces Configuration + +```{cfgcmd} set interfaces \<inttype\> \<intname\> ip rip authentication plaintext-password \<text\> + +This command sets the interface with RIP simple password authentication. +This command also sets authentication string. The string must be shorter +than 16 characters. +``` + + +```{cfgcmd} set interfaces \<inttype\> \<intname\> ip rip authentication md5 \<id\> password \<text\> + +This command sets the interface with RIP MD5 authentication. This command +also sets MD5 Key. The key must be shorter than 16 characters. +``` + + +```{cfgcmd} set interfaces \<inttype\> \<intname\> ip rip split-horizon disable + +This command disables split-horizon on the interface. By default, VyOS does +not advertise RIP routes out the interface over which they were learned +(split horizon).3 +``` + + +```{cfgcmd} set interfaces \<inttype\> \<intname\> ip rip split-horizon poison-reverse + +This command enables poison-reverse on the interface. If both poison reverse +and split horizon are enabled, then VyOS advertises the learned routes +as unreachable over the interface on which the route was learned. +``` + +## Operational Mode Commands + +```{opcmd} show ip rip + +This command displays RIP routes. +``` +```none +Codes: R - RIP, C - connected, S - Static, O - OSPF, B - BGP +Sub-codes: + (n) - normal, (s) - static, (d) - default, (r) - redistribute, + (i) - interface + + Network Next Hop Metric From Tag Time +C(i) 10.0.12.0/24 0.0.0.0 1 self 0 +C(i) 10.0.13.0/24 0.0.0.0 1 self 0 +R(n) 10.0.23.0/24 10.0.12.2 2 10.0.12.2 0 02:53 +``` + +```{opcmd} show ip rip status + +The command displays current RIP status. It includes RIP timer, filtering, +version, RIP enabled interface and RIP peer information. +``` +```none +Routing Protocol is "rip" + Sending updates every 30 seconds with +/-50%, next due in 11 seconds + Timeout after 180 seconds, garbage collect after 120 seconds + Outgoing update filter list for all interface is not set + Incoming update filter list for all interface is not set + Default redistribution metric is 1 + Redistributing: + Default version control: send version 2, receive any version + Interface Send Recv Key-chain + eth0 2 1 2 + eth2 2 1 2 + Routing for Networks: + 10.0.12.0/24 + eth0 + Routing Information Sources: + Gateway BadPackets BadRoutes Distance Last Update + 10.0.12.2 0 0 120 00:00:11 + Distance: (default is 120) +``` + +## Configuration Example + +Simple RIP configuration using 2 nodes and redistributing connected interfaces. + +**Node 1:** + +```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:** + +```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/md-rpki.md b/docs/configuration/protocols/md-rpki.md new file mode 100644 index 00000000..1f4cf5bf --- /dev/null +++ b/docs/configuration/protocols/md-rpki.md @@ -0,0 +1,210 @@ +(rpki)= + +# RPKI + +:::{pull-quote} + +There are two types of Network Admins who deal with BGP, those who have +created an international incident and/or outage, and those who are lying + +-- [tweet by EvilMog](https://twitter.com/Evil_Mog/status/1230924170508169216), 2020-02-21 +::: + +{abbr}`RPKI (Resource Public Key Infrastructure)` is a framework designed to +secure the Internet routing infrastructure. It associates BGP route +announcements with the correct originating {abbr}`ASN (Autonomus System +Number)` which BGP routers can then use to check each route against the +corresponding {abbr}`ROA (Route Origin Authorisation)` for validity. RPKI is +described in {rfc}`6480`. + +A BGP-speaking router like VyOS can retrieve ROA information from RPKI +"Relying Party software" (often just called an "RPKI server" or "RPKI +validator") by using {abbr}`RTR (RPKI to Router)` protocol. There are several +open source implementations to choose from, such as NLNetLabs' [Routinator] +(written in Rust), OpenBSD's [rpki-client] (written in C), and [StayRTR] (written +in Go). The RTR protocol is described in {rfc}`8210`. + +:::{tip} +If you are new to these routing security technologies then there is an +[excellent guide to RPKI] by NLnet Labs which will get you up to speed +very quickly. Their documentation explains everything from what RPKI is to +deploying it in production. It also has some +[help and operational guidance] including "What can I do about my route +having an Invalid state?" +::: + +## Getting started + +First you will need to deploy an RPKI validator for your routers to use. NLnet +Labs provides a collection of [software] you can compare and settle on one. +Once your server is running you can start validating announcements. + +Imported prefixes during the validation may have values: + +> valid +> +> : The prefix and ASN that originated it match a signed ROA. These are +> probably trustworthy route announcements. +> +> invalid +> +> : The prefix or prefix length and ASN that originated it doesn't +> match any existing ROA. This could be the result of a prefix hijack, or +> merely a misconfiguration, but should probably be treated as +> untrustworthy route announcements. +> +> notfound +> +> : No ROA exists which covers that prefix. Unfortunately this is the case for +> about 40%-50% of the prefixes which were announced to the {abbr}`DFZ +> (default-free zone)` at the start of 2024. + +:::{note} +If you are responsible for the global addresses assigned to your +network, please make sure that your prefixes have ROAs associated with them +to avoid being `notfound` by RPKI. For most ASNs this will involve +publishing ROAs via your {abbr}`RIR (Regional Internet Registry)` (RIPE +NCC, APNIC, ARIN, LACNIC, or AFRINIC), and is something you are encouraged +to do whenever you plan to announce addresses into the DFZ. + +Particularly large networks may wish to run their own RPKI certificate +authority and publication server instead of publishing ROAs via their RIR. +This is a subject far beyond the scope of VyOS' documentation. Consider +reading about [Krill] if this is a rabbit hole you need or especially want +to dive down. +::: + +### Features of the Current Implementation + +In a nutshell, the current implementation provides the following features: + +- The BGP router can connect to one or more RPKI cache servers to receive + validated prefix to origin AS mappings. Advanced failover can be implemented + by server sockets with different preference values. +- If no connection to an RPKI cache server can be established after a + pre-defined timeout, the router will process routes without prefix origin + validation. It still will try to establish a connection to an RPKI cache + server in the background. +- By default, enabling RPKI does not change best path selection. In particular, + invalid prefixes will still be considered during best path selection. However, + the router can be configured to ignore all invalid prefixes. +- Route maps can be configured to match a specific RPKI validation state. This + allows the creation of local policies, which handle BGP routes based on the + outcome of the Prefix Origin Validation. +- Updates from the RPKI cache servers are directly applied and path selection is + updated accordingly. (Soft reconfiguration must be enabled for this to work). + +## Configuration + +```{cfgcmd} set protocols rpki polling-period \<1-86400\> + +Define the time interval to update the local cache + +The default value is 300 seconds. +``` + +```{cfgcmd} set protocols rpki expire-interval \<600-172800\> + +Set the number of seconds the router waits until the router +expires the cache. + +The default value is 7200 seconds. +``` + +```{cfgcmd} set protocols rpki retry-interval \<1-7200\> + +Set the number of seconds the router waits until retrying to connect +to the cache server. + +The default value is 600 seconds. +``` + +```{cfgcmd} set protocols rpki cache \<address\> port \<port\> + +Defined the IPv4, IPv6 or FQDN and port number of the caching RPKI caching +instance which is used. + +This is a mandatory setting. +``` + +```{cfgcmd} set protocols rpki cache \<address\> preference \<preference\> + +Multiple RPKI caching instances can be supplied and they need a preference in +which their result sets are used. + +This is a mandatory setting. +``` + + +### SSH + +Connections to the RPKI caching server can not only be established by TCP using +the RTR protocol but you can also rely on a secure SSH session to the server. +This provides transport integrity and confidentiality and it is a good idea if +your validation software supports it. To enable SSH, first you need to create +an SSH client keypair using `generate ssh client-key +/config/auth/id_rsa_rpki`. Once your key is created you can setup the +connection. + +```{cfgcmd} set protocols rpki cache \<address\> ssh username \<user\> + +SSH username to establish an SSH connection to the cache server. +``` + +```{cfgcmd} set protocols rpki cache \<address\> ssh private-key-file \<filepath\> + +Local path that includes the private key file of the router. +``` + +```{cfgcmd} set protocols rpki cache \<address\> ssh public-key-file \<filepath\> + +Local path that includes the public key file of the router. +``` + +:::{note} +When using SSH, private-key-file and public-key-file +are mandatory options. +::: + +## Example + +We can build route-maps for import based on these states. Here is a simple +RPKI configuration, where `routinator` is the RPKI-validating "cache" +server with ip `192.0.2.1`: + +```none +set protocols rpki cache 192.0.2.1 port '3323' +set protocols rpki cache 192.0.2.1 preference '1' +``` + +Here is an example route-map to apply to routes learned at import. In this +filter we reject prefixes with the state `invalid`, and set a higher +`local-preference` if the prefix is RPKI `valid` rather than merely +`notfound`. + +```none +set policy route-map ROUTES-IN rule 10 action 'permit' +set policy route-map ROUTES-IN rule 10 match rpki 'valid' +set policy route-map ROUTES-IN rule 10 set local-preference '300' +set policy route-map ROUTES-IN rule 20 action 'permit' +set policy route-map ROUTES-IN rule 20 match rpki 'notfound' +set policy route-map ROUTES-IN rule 20 set local-preference '125' +set policy route-map ROUTES-IN rule 30 action 'deny' +set policy route-map ROUTES-IN rule 30 match rpki 'invalid' +``` + +Once your routers are configured to reject RPKI-invalid prefixes, you can +test whether the configuration is working correctly using Cloudflare's [test] +website. Keep in mind that in order for this to work, you need to have no +default routes or anything else that would still send traffic to RPKI-invalid +destinations. + +[excellent guide to rpki]: https://rpki.readthedocs.io/ +[help and operational guidance]: https://rpki.readthedocs.io/en/latest/about/help.html +[krill]: https://www.nlnetlabs.nl/projects/rpki/krill/ +[routinator]: https://www.nlnetlabs.nl/projects/rpki/routinator/ +[rpki-client]: https://www.rpki-client.org/ +[software]: https://rpki.readthedocs.io/en/latest/ops/tools.html#relying-party-software +[stayrtr]: https://github.com/bgp/stayrtr/ +[test]: https://isbgpsafeyet.com/ +[tweet by evilmog]: <https://twitter.com/Evil_Mog/status/1230924170508169216> diff --git a/docs/configuration/protocols/md-segment-routing.md b/docs/configuration/protocols/md-segment-routing.md new file mode 100644 index 00000000..af47d343 --- /dev/null +++ b/docs/configuration/protocols/md-segment-routing.md @@ -0,0 +1,359 @@ +(segment-routing)= + +# Segment Routing + +Segment Routing (SR) is a network architecture that is similar to source-routing +. In this architecture, the ingress router adds a list of segments, known as +SIDs, to the packet as it enters the network. These segments represent different +portions of the network path that the packet will take. + +The SR segments are portions of the network path taken by the packet, and are +called SIDs. At each node, the first SID of the list is read, executed as a +forwarding function, and may be popped to let the next node read the next SID of +the list. The SID list completely determines the path where the packet is +forwarded. + +Segment Routing can be applied to an existing MPLS-based data plane and defines +a control plane network architecture. In MPLS networks, segments are encoded as +MPLS labels and are added at the ingress router. These MPLS labels are then +exchanged and populated by Interior Gateway Protocols (IGPs) like IS-IS or OSPF +which are running on most ISPs. + +:::{note} +Segment routing defines a control plane network architecture and +can be applied to an existing MPLS based dataplane. In the MPLS networks, +segments are encoded as MPLS labels and are imposed at the ingress router. +MPLS labels are exchanged and populated by IGPs like IS-IS.Segment Routing +as per RFC8667 for MPLS dataplane. It supports IPv4, IPv6 and ECMP and has +been tested against Cisco & Juniper routers.however,this deployment is still +EXPERIMENTAL for FRR. +::: + +## IS-IS SR Configuration + +Segment routing (SR) is used by the IGP protocols to interconnect network +devices, below configuration shows how to enable SR on IS-IS: + +:::{note} +``Known limitations:`` + +No support for level redistribution (L1 to L2 or L2 to L1) + +No support for binding SID + +No support for SRLB + +Only one SRGB and default SPF Algorithm is supported +::: + +```{cfgcmd} set protocols isis segment-routing global-block high-label-value \<label-value\> + +Set the Segment Routing Global Block i.e. the label range used by MPLS to +store label in the MPLS FIB for Prefix SID. Note that the block size may +not exceed 65535. +``` + + +```{cfgcmd} set protocols isis segment-routing global-block low-label-value \<label-value\> + +Set the Segment Routing Global Block i.e. the low label range used by MPLS to +store label in the MPLS FIB for Prefix SID. Note that the block size may +not exceed 65535. +``` + + +```{cfgcmd} set protocols isis segment-routing local-block high-label-value \<label-value\> + +Set the Segment Routing Local Block i.e. the label range used by MPLS to +store label in the MPLS FIB for Prefix SID. Note that the block size may +not exceed 65535.Segment Routing Local Block, The negative command always +unsets both. +``` + + +```{cfgcmd} set protocols isis segment-routing local-block \<low-label-value \<label-value\> + +Set the Segment Routing Local Block i.e. the low label range used by MPLS to +store label in the MPLS FIB for Prefix SID. Note that the block size may +not exceed 65535.Segment Routing Local Block, The negative command always +unsets both. +``` + + +```{cfgcmd} set protocols isis segment-routing maximum-label-depth \<1-16\> + +Set the Maximum Stack Depth supported by the router. The value depend of +the MPLS dataplane. +``` + + +```{cfgcmd} set protocols isis segment-routing prefix \<address\> index value \<0-65535\> + +A segment ID that contains an IP address prefix calculated by an IGP in the +service provider core network. Prefix SIDs are globally unique, this value +identify it +``` + + +```{cfgcmd} set protocols isis segment-routing prefix \<address\> index \<no-php-flag | explicit-null| n-flag-clear\> + +this option allows to configure prefix-sid on SR. The ‘no-php-flag’ means NO +Penultimate Hop Popping that allows SR node to request to its neighbor to +not pop the label. The ‘explicit-null’ flag allows SR node to request to its +neighbor to send IP packet with the EXPLICIT-NULL label. The ‘n-flag-clear’ +option can be used to explicitly clear the Node flag that is set by default +for Prefix-SIDs associated to loopback addresses. This option is necessary +to configure Anycast-SIDs. +``` + +```{opcmd} show isis segment-routing node + + Show detailed information about all learned Segment Routing Nodes +``` + + +```{opcmd} show isis route prefix-sid + +Show detailed information about prefix-sid and label learned +``` + +:::{note} +more information related IGP - {ref}`routing-isis` +::: + + +## OSPF SR Configuration + + +Segment routing (SR) is used by the IGP protocols to interconnect network +devices, below configuration shows how to enable SR on OSPF: + +```{cfgcmd} set protocols ospf parameters opaque-lsa + +Enable the Opaque-LSA capability (rfc2370), necessary to transport label +on IGP +``` + +```{cfgcmd} set protocols ospf segment-routing global-block high-label-value \<label-value\> + +Set the Segment Routing Global Block i.e. the label range used by MPLS to +store label in the MPLS FIB for Prefix SID. Note that the block size may +not exceed 65535. +``` + +```{cfgcmd} set protocols ospf segment-routing global-block low-label-value \<label-value\> + +Set the Segment Routing Global Block i.e. the low label range used by MPLS to +store label in the MPLS FIB for Prefix SID. Note that the block size may +not exceed 65535. +``` + +```{cfgcmd} set protocols ospf segment-routing local-block high-label-value \<label-value\> + +Set the Segment Routing Local Block i.e. the label range used by MPLS to +store label in the MPLS FIB for Prefix SID. Note that the block size may +not exceed 65535.Segment Routing Local Block, The negative command always +unsets both. +``` + +```{cfgcmd} set protocols ospf segment-routing local-block \<low-label-value \<label-value\> + +Set the Segment Routing Local Block i.e. the low label range used by MPLS to +store label in the MPLS FIB for Prefix SID. Note that the block size may +not exceed 65535.Segment Routing Local Block, The negative command always +unsets both. +``` + +```{cfgcmd} set protocols ospf segment-routing maximum-label-depth \<1-16\> + +Set the Maximum Stack Depth supported by the router. The value depend of +the MPLS dataplane. +``` + +```{cfgcmd} set protocols ospf segment-routing prefix \<address\> index value \<0-65535\> + +A segment ID that contains an IP address prefix calculated by an IGP in the +service provider core network. Prefix SIDs are globally unique, this value +identify it +``` + +```{cfgcmd} set protocols ospf segment-routing prefix \<address\> index \<no-php-flag | explicit-null| n-flag-clear\> + +this option allows to configure prefix-sid on SR. The ‘no-php-flag’ means NO +Penultimate Hop Popping that allows SR node to request to its neighbor to +not pop the label. The ‘explicit-null’ flag allows SR node to request to its +neighbor to send IP packet with the EXPLICIT-NULL label. The ‘n-flag-clear’ +option can be used to explicitly clear the Node flag that is set by default +for Prefix-SIDs associated to loopback addresses. This option is necessary +to configure Anycast-SIDs. +``` + +:::{note} +more information related IGP - {ref}`routing-ospf` +::: + +## Configuration Example + +we described the configuration SR ISIS / SR OSPF using 2 connected with them to +share label information. + +### Enable IS-IS with Segment Routing (Experimental) + +**Node 1:** + +```none +set interfaces loopback lo address '192.168.255.255/32' +set interfaces ethernet eth1 address '192.0.2.1/24' + +set protocols isis interface eth1 +set protocols isis interface lo +set protocols isis net '49.0001.1921.6825.5255.00' +set protocols isis segment-routing global-block high-label-value '599' +set protocols isis segment-routing global-block low-label-value '550' +set protocols isis segment-routing prefix 192.168.255.255/32 index value '1' +set protocols isis segment-routing prefix 192.168.255.255/32 index explicit-null +set protocols mpls interface 'eth1' +``` + +**Node 2:** + +```none +set interfaces loopback lo address '192.168.255.254/32' +set interfaces ethernet eth1 address '192.0.2.2/24' + +set protocols isis interface eth1 +set protocols isis interface lo +set protocols isis net '49.0001.1921.6825.5254.00' +set protocols isis segment-routing global-block high-label-value '599' +set protocols isis segment-routing global-block low-label-value '550' +set protocols isis segment-routing prefix 192.168.255.254/32 index value '2' +set protocols isis segment-routing prefix 192.168.255.254/32 index explicit-null +set protocols mpls interface 'eth1' +``` + +This gives us MPLS segment routing enabled and labels for far end loopbacks: + +```none +Node-1@vyos:~$ show mpls table + Inbound Label Type Nexthop Outbound Label + ---------------------------------------------------------------------- + 552 SR (IS-IS) 192.0.2.2 IPv4 Explicit Null <-- Node-2 loopback learned on Node-1 + 15000 SR (IS-IS) 192.0.2.2 implicit-null + 15001 SR (IS-IS) fe80::e87:6cff:fe09:1 implicit-null + 15002 SR (IS-IS) 192.0.2.2 implicit-null + 15003 SR (IS-IS) fe80::e87:6cff:fe09:1 implicit-null + +Node-2@vyos:~$ show mpls table + Inbound Label Type Nexthop Outbound Label + --------------------------------------------------------------------- + 551 SR (IS-IS) 192.0.2.1 IPv4 Explicit Null <-- Node-1 loopback learned on Node-2 + 15000 SR (IS-IS) 192.0.2.1 implicit-null + 15001 SR (IS-IS) fe80::e33:2ff:fe80:1 implicit-null + 15002 SR (IS-IS) 192.0.2.1 implicit-null + 15003 SR (IS-IS) fe80::e33:2ff:fe80:1 implicit-null +``` + +Here is the routing tables showing the MPLS segment routing label operations: + +```none +Node-1@vyos:~$ show ip route isis +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +I 192.0.2.0/24 [115/20] via 192.0.2.2, eth1 inactive, weight 1, 00:07:48 +I>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1, label IPv4 Explicit Null, weight 1, 00:03:39 + +Node-2@vyos:~$ show ip route isis +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +I 192.0.2.0/24 [115/20] via 192.0.2.1, eth1 inactive, weight 1, 00:07:46 +I>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1, label IPv4 Explicit Null, weight 1, 00:03:43 +``` + + +### Enable OSPF with Segment Routing (Experimental): + +**Node 1** + +```none +set interfaces loopback lo address 10.1.1.1/32 +set interfaces ethernet eth0 address 192.168.0.1/24 +set protocols ospf area 0 network '192.168.0.0/24' +set protocols ospf area 0 network '10.1.1.1/32' +set protocols ospf parameters opaque-lsa +set protocols ospf parameters router-id '10.1.1.1' +set protocols ospf segment-routing global-block high-label-value '1100' +set protocols ospf segment-routing global-block low-label-value '1000' +set protocols ospf segment-routing prefix 10.1.1.1/32 index explicit-null +set protocols ospf segment-routing prefix 10.1.1.1/32 index value '1' +``` + +**Node 2** + +```none +set interfaces loopback lo address 10.1.1.2/32 +set interfaces ethernet eth0 address 192.168.0.2/24 +set protocols ospf area 0 network '192.168.0.0/24' +set protocols ospf area 0 network '10.1.1.2/32' +set protocols ospf parameters opaque-lsa +set protocols ospf parameters router-id '10.1.1.2' +set protocols ospf segment-routing global-block high-label-value '1100' +set protocols ospf segment-routing global-block low-label-value '1000' +set protocols ospf segment-routing prefix 10.1.1.2/32 index explicit-null +set protocols ospf segment-routing prefix 10.1.1.2/32 index value '2' +``` + +This gives us MPLS segment routing enabled and labels for far end loopbacks: + +```none +Node-1@vyos:~$ show mpls table + Inbound Label Type Nexthop Outbound Label + ----------------------------------------------------------- + 1002 SR (OSPF) 192.168.0.2 IPv4 Explicit Null <-- Node-2 loopback learned on Node-1 + 15000 SR (OSPF) 192.168.0.2 implicit-null + 15001 SR (OSPF) 192.168.0.2 implicit-null + +Node-2@vyos:~$ show mpls table + Inbound Label Type Nexthop Outbound Label + ----------------------------------------------------------- + 1001 SR (OSPF) 192.168.0.1 IPv4 Explicit Null <-- Node-1 loopback learned on Node-2 + 15000 SR (OSPF) 192.168.0.1 implicit-null + 15001 SR (OSPF) 192.168.0.1 implicit-null +``` + +Here is the routing tables showing the MPLS segment routing label operations: + +```none +Node-1@vyos:~$ show ip route ospf +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +O 10.1.1.1/32 [110/0] is directly connected, lo, weight 1, 00:03:43 +O>* 10.1.1.2/32 [110/1] via 192.168.0.2, eth0, label IPv4 Explicit Null, weight 1, 00:03:32 +O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:43 + +Node-2@vyos:~$ show ip route ospf +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +O>* 10.1.1.1/32 [110/1] via 192.168.0.1, eth0, label IPv4 Explicit Null, weight 1, 00:03:36 +O 10.1.1.2/32 [110/0] is directly connected, lo, weight 1, 00:03:51 +O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:51 +``` diff --git a/docs/configuration/protocols/md-static.md b/docs/configuration/protocols/md-static.md new file mode 100644 index 00000000..fca17a6c --- /dev/null +++ b/docs/configuration/protocols/md-static.md @@ -0,0 +1,268 @@ +(routing-static)= + +# Static + +Static routes are manually configured routes, which, in general, cannot be +updated dynamically from information VyOS learns about the network topology from +other routing protocols. However, if a link fails, the router will remove +routes, including static routes, from the {abbr}`RIPB (Routing Information +Base)` that used this interface to reach the next hop. In general, static +routes should only be used for very simple network topologies, or to override +the behavior of a dynamic routing protocol for a small number of routes. The +collection of all routes the router has learned from its configuration or from +its dynamic routing protocols is stored in the RIB. Unicast routes are directly +used to determine the forwarding table used for unicast packet forwarding. + +## Static Routes + +```{eval-rst} +.. cfgcmd:: set protocols static route <subnet> next-hop <address> + + Configure next-hop `<address>` for an IPv4 static route. Multiple static + routes can be created. +``` + +```{eval-rst} +.. cfgcmd:: set protocols static route <subnet> next-hop <address> disable + + Disable this IPv4 static route entry. +``` + +```{eval-rst} +.. cfgcmd:: set protocols static route <subnet> next-hop <address> + distance <distance> + + Defines next-hop distance for this route, routes with smaller administrative + distance are elected prior to those with a higher distance. + + Range is 1 to 255, default is 1. + + .. note:: Routes with a distance of 255 are effectively disabled and not + installed into the kernel. +``` + +```{eval-rst} +.. cfgcmd:: set protocols static route6 <subnet> next-hop <address> + + Configure next-hop `<address>` for an IPv6 static route. Multiple static + routes can be created. +``` + +```{eval-rst} +.. cfgcmd:: set protocols static route6 <subnet> next-hop <address> disable + + Disable this IPv6 static route entry. +``` + +```{eval-rst} +.. cfgcmd:: set protocols static route6 <subnet> next-hop <address> + distance <distance> + + Defines next-hop distance for this route, routes with smaller administrative + distance are elected prior to those with a higher distance. + + Range is 1 to 255, default is 1. + + .. note:: Routes with a distance of 255 are effectively disabled and not + installed into the kernel. +``` + +```{eval-rst} +.. cfgcmd:: set protocols static route6 <subnet> next-hop <address> segments <segments> + + It is possible to specify a static route for ipv6 prefixes using an SRv6 segments + instruction. The `/` separator can be used to specify multiple segment instructions. + + Example: + + .. code-block:: none + + set protocols static route6 2001:db8:1000::/36 next-hop 2001:db8:201::ffff segments '2001:db8:aaaa::7/2002::4/2002::3/2002::2' + + .. code-block:: none + + vyos@vyos:~$ show ipv6 route + Codes: K - kernel route, C - connected, S - static, R - RIPng, + O - OSPFv3, I - IS-IS, B - BGP, N - NHRP, T - Table, + v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + C>* 2001:db8:201::/64 is directly connected, eth0.201, 00:00:46 + S>* 2001:db8:1000::/36 [1/0] via 2001:db8:201::ffff, eth0.201, seg6 2001:db8:aaaa::7,2002::4,2002::3,2002::2, weight 1, 00:00:08 + +``` + +### Interface Routes + +```{eval-rst} +.. cfgcmd:: set protocols static route <subnet> interface + <interface> + + Allows you to configure the next-hop interface for an interface-based IPv4 + static route. `<interface>` will be the next-hop interface where traffic is + routed for the given `<subnet>`. +``` + +```{eval-rst} +.. cfgcmd:: set protocols static route <subnet> interface + <interface> disable + + Disables interface-based IPv4 static route. +``` + +```{eval-rst} +.. cfgcmd:: set protocols static route <subnet> interface + <interface> distance <distance> + + Defines next-hop distance for this route, routes with smaller administrative + distance are elected prior to those with a higher distance. + + Range is 1 to 255, default is 1. +``` + +```{eval-rst} +.. cfgcmd:: set protocols static route6 <subnet> interface + <interface> + + Allows you to configure the next-hop interface for an interface-based IPv6 + static route. `<interface>` will be the next-hop interface where traffic is + routed for the given `<subnet>`. +``` + +```{eval-rst} +.. cfgcmd:: set protocols static route6 <subnet> interface + <interface> disable + + Disables interface-based IPv6 static route. +``` + +```{eval-rst} +.. cfgcmd:: set protocols static route6 <subnet> interface + <interface> distance <distance> + + Defines next-hop distance for this route, routes with smaller administrative + distance are elected prior to those with a higher distance. + + Range is 1 to 255, default is 1. +``` + +```{eval-rst} +.. cfgcmd:: set protocols static route6 <subnet> interface + <interface> segments <segments> + + It is possible to specify a static route for ipv6 prefixes using an SRv6 segments + instruction. The `/` separator can be used to specify multiple segment instructions. + + Example: + + .. code-block:: none + + set protocols static route6 2001:db8:1000::/36 interface eth0 segments '2001:db8:aaaa::7/2002::4/2002::3/2002::2' +``` + +### Blackhole + +```{eval-rst} +.. cfgcmd:: set protocols static route <subnet> blackhole + + Use this command to configure a "black-hole" route on the router. A + black-hole route is a route for which the system silently discard packets + that are matched. This prevents networks leaking out public interfaces, but + it does not prevent them from being used as a more specific route inside your + network. +``` + +```{eval-rst} +.. cfgcmd:: set protocols static route <subnet> blackhole distance <distance> + + Defines blackhole distance for this route, routes with smaller administrative + distance are elected prior to those with a higher distance. +``` + +```{eval-rst} +.. cfgcmd:: set protocols static route6 <subnet> blackhole + + Use this command to configure a "black-hole" route on the router. A + black-hole route is a route for which the system silently discard packets + that are matched. This prevents networks leaking out public interfaces, but + it does not prevent them from being used as a more specific route inside your + network. +``` + +```{eval-rst} +.. cfgcmd:: set protocols static route6 <subnet> blackhole distance <distance> + + Defines blackhole distance for this route, routes with smaller administrative + distance are elected prior to those with a higher distance. +``` + +### Alternate Routing Tables + +TBD + +Alternate routing tables are used with policy based routing by utilizing +{ref}`vrf`. + +(routing-arp)= + +# ARP + +{abbr}`ARP (Address Resolution Protocol)` is a communication protocol used for +discovering the link layer address, such as a MAC address, associated with a +given internet layer address, typically an IPv4 address. This mapping is a +critical function in the Internet protocol suite. ARP was defined in 1982 by +{rfc}`826` which is Internet Standard STD 37. + +In Internet Protocol Version 6 (IPv6) networks, the functionality of ARP is +provided by the Neighbor Discovery Protocol (NDP). + +To manipulate or display [ARP] table entries, the following commands are +implemented. + +## Configure + +```{eval-rst} +.. cfgcmd:: set protocols static arp interface <interface> address <host> + mac <mac> + + This will configure a static ARP entry always resolving `<address>` to + `<mac>` for interface `<interface>`. + + Example: + + .. code-block:: none + + set protocols static arp interface eth0 address 192.0.2.1 mac 01:23:45:67:89:01 + +``` + +## Operation + +```{eval-rst} +.. opcmd:: show protocols static arp + + Display all known ARP table entries spanning across all interfaces +``` + +```none +vyos@vyos:~$ show protocols static arp +Address HWtype HWaddress Flags Mask Iface +10.1.1.1 ether 00:53:00:de:23:2e C eth1 +10.1.1.100 ether 00:53:00:de:23:aa CM eth1 +``` + +```{eval-rst} +.. opcmd:: show protocols static arp interface eth1 + + Display all known ARP table entries on a given interface only (`eth1`): +``` + +```none +vyos@vyos:~$ show protocols static arp interface eth1 +Address HWtype HWaddress Flags Mask Iface +10.1.1.1 ether 00:53:00:de:23:2e C eth1 +10.1.1.100 ether 00:53:00:de:23:aa CM eth1 +``` + +[arp]: https://en.wikipedia.org/wiki/Address_Resolution_Protocol diff --git a/docs/configuration/service/md-broadcast-relay.md b/docs/configuration/service/md-broadcast-relay.md new file mode 100644 index 00000000..73baad1b --- /dev/null +++ b/docs/configuration/service/md-broadcast-relay.md @@ -0,0 +1,76 @@ +(udp-broadcast-relay)= + +# UDP Broadcast Relay + +Certain vendors use broadcasts to identify their equipment within one ethernet +segment. Unfortunately if you split your network with multiple VLANs you loose +the ability of identifying your equipment. + +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! + +## Configuration + +```{eval-rst} +.. cfgcmd:: set service broadcast-relay id <n> description <description> + + A description can be added for each and every unique relay ID. This is + useful to distinguish between multiple different ports/appliactions. +``` + +```{eval-rst} +.. cfgcmd:: set service broadcast-relay id <n> interface <interface> + + The interface used to receive and relay individual broadcast packets. If you + want to receive/relay packets on both `eth1` and `eth2` both interfaces need + to be added. +``` + +```{eval-rst} +.. cfgcmd:: set service broadcast-relay id <n> address <ipv4-address> + + Set the source IP of forwarded packets, otherwise original senders address + is used. +``` + +```{eval-rst} +.. cfgcmd:: set service broadcast-relay id <n> port <port> + + The UDP port number used by your apllication. It is mandatory for this kind + of operation. +``` + +```{eval-rst} +.. cfgcmd:: set service broadcast-relay id <n> disable + + Each broadcast relay instance can be individually disabled without deleting + the configured node by using the following command: +``` + +```{eval-rst} +.. cfgcmd:: set service broadcast-relay disable + + In addition you can also disable the whole service without the need to remove + it from the current configuration. +``` + +:::{note} +You can run the UDP broadcast relay service on multiple routers +connected to a subnet. There is **NO** UDP broadcast relay packet storm! +::: + +## Example + +To forward all broadcast packets received on `UDP port 1900` on `eth3`, `eth4` +or `eth5` to all other interfaces in this configuration. + +```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' +``` diff --git a/docs/configuration/service/md-config-sync.md b/docs/configuration/service/md-config-sync.md new file mode 100644 index 00000000..0f92768d --- /dev/null +++ b/docs/configuration/service/md-config-sync.md @@ -0,0 +1,117 @@ +(config-sync)= + +# Config Sync + +Configuration synchronization (config sync) is a feature of VyOS that +permits synchronization of the configuration of one VyOS router to +another in a network. + +The main benefit to configuration synchronization is that it eliminates having +to manually replicate configuration changes made on the primary router to the +secondary (replica) router. + +The writing of the configuration to the secondary router is performed through +the VyOS HTTP API. The user can specify which portion(s) of the configuration will +be synchronized and the mode to use - whether to replace or add. + +To prevent issues with divergent configurations between the pair of routers, +synchronization is strictly unidirectional from primary to replica. Both +routers should be online and run the same version of VyOS. + +## Configuration + +```{eval-rst} +.. cfgcmd:: set service config-sync secondary + <address|key|timeout|port> + + Specify the address, API key, timeout and port of the secondary router. + You need to enable and configure the HTTP API service on the secondary + router for config sync to operate. +``` + +```{eval-rst} +.. cfgcmd:: set service config-sync section <section> + + Specify the section of the configuration to synchronize. If more than one + section is to be synchronized, repeat the command to add additional + sections as required. +``` + +```{eval-rst} +.. cfgcmd:: set service config-sync mode <load|set> + + Two options are available for `mode`: either `load` and replace or `set` + the configuration section. +``` + +```none +Supported options for <section> include: + firewall + interfaces <interface> + nat + nat66 + pki + policy + protocols <protocol> + qos <interface|policy> + service <service> + system <conntrack| + flow-accounting|option|sflow|static-host-mapping|sysctl|time-zone> + vpn + vrf +``` + +## Example + +- Synchronize the time-zone and OSPF configuration from Router A to Router B +- The address of Router B is 10.0.20.112 and the port used is 8443 + +Configure the HTTP API service on Router B + +```none +set service https listen-address '10.0.20.112' +set service https port '8443' +set service https api keys id KID key 'foo' +``` + +Configure the config-sync service on Router A + +```none +set service config-sync mode 'load' +set service config-sync secondary address '10.0.20.112' +set service config-sync secondary port '8443' +set service config-sync secondary key 'foo' +set service config-sync section protocols 'ospf' +set service config-sync section system 'time-zone' +``` + +Make config-sync relevant changes to Router A's configuration + +```none +vyos@vyos-A# set system time-zone 'America/Los_Angeles' +vyos@vyos-A# commit +INFO:vyos_config_sync:Config synchronization: Mode=load, +Secondary=10.0.20.112 +vyos@vyos-A# save + +vyos@vyos-A# set protocols ospf area 0 network '10.0.48.0/30' +vyos@vyos-A# commit +INFO:vyos_config_sync:Config synchronization: Mode=load, +Secondary=10.0.20.112 +yos@vyos-A# save +``` + +Verify configuration changes have been replicated to Router B + +```none +vyos@vyos-B:~$ show configuration commands | match time-zone +set system time-zone 'America/Los_Angeles' + +vyos@vyos-B:~$ show configuration commands | match ospf +set protocols ospf area 0 network '10.0.48.0/30' +``` + +## Known issues + +Configuration resynchronization. With the current implementation of `service +config-sync`, the secondary node must be online. diff --git a/docs/configuration/service/md-conntrack-sync.md b/docs/configuration/service/md-conntrack-sync.md new file mode 100644 index 00000000..d82459df --- /dev/null +++ b/docs/configuration/service/md-conntrack-sync.md @@ -0,0 +1,329 @@ +(conntrack-sync)= + +# Conntrack Sync + +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. + +It is possible to use either Multicast or Unicast to sync conntrack traffic. +Most examples below show Multicast, but unicast can be specified by using the +"peer" keywork after the specificed interface, as in the following example: + +{cfgcmd}`set service conntrack-sync interface eth0 peer 192.168.0.250` + +## Configuration + +```{eval-rst} +.. cfgcmd:: set service conntrack-sync accept-protocol + + Accept only certain protocols: You may want to replicate the state of flows + depending on their layer 4 protocol. + + Protocols are: tcp, sctp, dccp, udp, icmp and ipv6-icmp. +``` + +```{eval-rst} +.. cfgcmd:: set service conntrack-sync event-listen-queue-size <size> + + The daemon doubles the size of the netlink event socket buffer size if it + detects netlink event message dropping. This clause sets the maximum buffer + size growth that can be reached. + + Queue size for listening to local conntrack events in MB. +``` + +```{eval-rst} +.. cfgcmd:: set service conntrack-sync expect-sync <all|ftp|h323|nfs|sip|sqlnet> + + Protocol for which expect entries need to be synchronized. +``` + +```{eval-rst} +.. cfgcmd:: set service conntrack-sync failover-mechanism vrrp sync-group <group> + + Failover mechanism to use for conntrack-sync. + + Only VRRP is supported. Required option. +``` + +```{eval-rst} +.. cfgcmd:: set service conntrack-sync ignore-address <x.x.x.x> + + IP addresses or networks for which local conntrack entries will not be synced +``` + +```{eval-rst} +.. cfgcmd:: set service conntrack-sync interface <name> + + Interface to use for syncing conntrack entries. +``` + +```{eval-rst} +.. cfgcmd:: set service conntrack-sync interface <name> port <port> + + Port number used by connection. +``` + +```{eval-rst} +.. cfgcmd:: set service conntrack-sync listen-address <ipv4address> + + Local IPv4 addresses for service to listen on. +``` + +```{eval-rst} +.. cfgcmd:: set service conntrack-sync mcast-group <x.x.x.x> + + Multicast group to use for syncing conntrack entries. + + Defaults to 225.0.0.50. +``` + +```{eval-rst} +.. cfgcmd:: set service conntrack-sync interface <name> peer <address> + + Peer to send unicast UDP conntrack sync entires to, if not using Multicast + configuration from above above. +``` + +```{eval-rst} +.. cfgcmd:: set service conntrack-sync sync-queue-size <size> + + Queue size for syncing conntrack entries in MB. +``` + +```{eval-rst} +.. cfgcmd:: set service conntrack-sync disable-external-cache + + This diable the external cache and directly injects the flow-states into the + in-kernel Connection Tracking System of the backup firewall. +``` + +```{eval-rst} +.. cfgcmd:: set service conntrack-sync purge-timeout <timeout> + + Timeout (in seconds) for purging synchronized entries on handover events. + + On handover, ``conntrackd -t`` is invoked, which schedules a conntrack table + flush after ``<timeout>`` seconds to purge stale (“zombie”) entries and + reduce clashes when multiple handovers occur in a short period. + The default is 60 seconds. +``` + +:::{note} +In VRRP stateful firewall deployments, align VRRP timing with this +behavior: because synchronized conntrack state is purged after the purge +timeout, set **VRRP preempt-delay** to ≥ **purge-timeout** so mastership +can be restored before conntrack state is purged. +::: + +```{eval-rst} +.. cfgcmd:: set service conntrack-sync disable-syslog + + Disable connection logging via Syslog. +``` + +```{eval-rst} +.. cfgcmd:: set service conntrack-sync startup-resync + + Order conntrackd to request a complete conntrack table resync against + the other node at startup. +``` + +## Operation + +```{eval-rst} +.. opcmd:: show conntrack table ipv4 + + Make sure conntrack is enabled by running and show connection tracking table. + + .. code-block:: none + + vyos@vyos:~$ 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 + + .. note:: + + 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. {cfgcmd}`set firewall state-policy established action accept` +``` + +```{eval-rst} +.. opcmd:: show conntrack-sync cache external + + Show connection syncing external cache entries +``` + +```{eval-rst} +.. opcmd:: show conntrack-sync cache internal + + Show connection syncing internal cache entries +``` + +```{eval-rst} +.. opcmd:: show conntrack-sync statistics + + Retrieve current statistics of connection tracking subsystem. + + .. code-block:: none + + vyos@vyos:~$ show conntrack-sync statistics + Main Table Statistics: + + cache internal: + current active connections: 19606 + connections created: 6298470 failed: 0 + connections updated: 3786793 failed: 0 + connections destroyed: 6278864 failed: 0 + + cache external: + current active connections: 15771 + connections created: 1660193 failed: 0 + connections updated: 77204 failed: 0 + connections destroyed: 1644422 failed: 0 + + traffic processed: + 0 Bytes 0 Pckts + + multicast traffic (active device=eth0.5): + 976826240 Bytes sent 212898000 Bytes recv + 8302333 Pckts sent 2009929 Pckts recv + 0 Error send 0 Error recv + + message tracking: + 0 Malformed msgs 263 Lost msgs + +``` + +```{eval-rst} +.. opcmd:: show conntrack-sync status + + Retrieve current status of connection tracking subsystem. + + .. code-block:: none + + vyos@vyos:~$ show conntrack-sync status + sync-interface : eth0.5 + failover-mechanism : vrrp [sync-group GEFOEKOM] + last state transition : no transition yet! + ExpectationSync : disabled + +``` + +## Example + +The next example is a simple configuration of conntrack-sync. + +:::{figure} /_static/images/service_conntrack_sync-schema.png +:alt: Conntrack Sync Example +:scale: 60 % +::: + +Now configure conntrack-sync service on `router1` **and** `router2` + +```none +set high-availablilty vrrp group internal virtual-address ... etc ... +set high-availability vrrp sync-group syncgrp member 'internal' +set service conntrack-sync accept-protocol 'tcp' +set service conntrack-sync accept-protocol 'udp' +set service conntrack-sync accept-protocol 'icmp' +set service conntrack-sync failover-mechanism vrrp sync-group 'syncgrp' +set service conntrack-sync interface 'eth0' +set service conntrack-sync mcast-group '225.0.0.50' +``` + +On the active router, you should have information 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: + +```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: + +```none +$ 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/md-console-server.md b/docs/configuration/service/md-console-server.md new file mode 100644 index 00000000..f0556652 --- /dev/null +++ b/docs/configuration/service/md-console-server.md @@ -0,0 +1,139 @@ +(console-server)= + +# Console Server + +Starting of with VyOS 1.3 (equuleus) we added support for running VyOS as an +Out-of-Band Management device which provides remote access by means of SSH to +directly attached serial interfaces. + +Serial interfaces can be any interface which is directly connected to the CPU +or chipset (mostly known as a ttyS interface in Linux) or any other USB to +serial converter (Prolific PL2303 or FTDI FT232/FT4232 based chips). + +If you happened to use a Cisco NM-16A - Sixteen Port Async Network Module or +NM-32A - Thirty-two Port Async Network Module - this is your VyOS replacement. + +For USB port information please refor to: {ref}`hardware_usb`. + +## Configuration + +Between computers, the most common configuration used was "8N1": eight bit +characters, with one start bit, one stop bit, and no parity bit. Thus 10 Baud +times are used to send a single character, and so dividing the signalling +bit-rate by ten results in the overall transmission speed in characters per +second. This is also the default setting if none of those options are defined. + +```{cfgcmd} set service console-server device \<device\> data-bits [7 | 8] + +Configure either seven or eight data bits. This defaults to eight data +bits if left unconfigured. +``` + + +```{cfgcmd} set service console-server device \<device\> description \<string\> + +A user friendly description identifying the connected peripheral. +``` + + +```{cfgcmd} set service console-server device \<device\> alias \<string\> + +A user friendly alias for this connection. Can be used instead of the +device name when connecting. +``` + + +```{cfgcmd} set service console-server device \<device\> parity [even | odd | none] + +Set the parity option for the console. If unset this will default to none. +``` + + +```{cfgcmd} set service console-server device \<device\> stop-bits [1 | 2] + +Configure either one or two stop bits. This defaults to one stop bits if +left unconfigured. +``` + + +```{cfgcmd} set service console-server device \<device\> speed [ 300 | 1200 | 2400 | 4800 | 9600 | 19200 | 38400 | 57600 | 115200 ] + +:::{note} +USB to serial converters will handle most of their work in software +so you should be carefull with the selected baudrate as some times they +can't cope with the expected speed. +::: +``` + +### Remote Access + + +Each individual configured console-server device can be directly exposed to +the outside world. A user can directly connect via SSH to the configured +port. + +```{cfgcmd} set service console-server device \<device\> ssh port \<port\> + +Accept SSH connections for the given `<device>` on TCP port `<port>`. +After successful authentication the user will be directly dropped to +the connected serial device. + +:::{hint} +Multiple users can connect to the same serial device but only +one is allowed to write to the console port. +::: +``` + +## Operation + +```{opcmd} show console-server ports + +Show configured serial ports and their respective interface configuration. + +:::{code-block} none +vyos@vyos:~$ show console-server ports +usb0b2.4p1.0 on /dev/serial/by-bus/usb0b2.4p1.0@ at 9600n +::: +``` + + +```{opcmd} show console-server user + +Show currently connected users. + +:::{code-block} none +vyos@vyos:~$ show console-server user +usb0b2.4p1.0 up vyos@localhost +::: +``` +```{opcmd} connect console \<device\> + +Locally connect to serial port identified by `<device>`. + +:::{code-block} none +vyos@vyos-r1:~$ connect console usb0b2.4p1.0 +[Enter `^Ec?' for help] +[-- MOTD -- VyOS Console Server] + +vyos-r2 login: +::: + +:::{hint} +Multiple users can connect to the same serial device but only +one is allowed to write to the console port. +::: + +:::{hint} +The sequence ``^Ec?`` translates to: ``Ctrl+E c ?``. To quit +the session use: ``Ctrl+E c .`` +::: + +:::{hint} +If ``alias`` is set, it can be used instead of the device when +connecting. +::: +``` +```{opcmd} show log console-server + +Show the console server log. +```
\ No newline at end of file diff --git a/docs/configuration/service/md-dhcp-relay.md b/docs/configuration/service/md-dhcp-relay.md new file mode 100644 index 00000000..4bbee82b --- /dev/null +++ b/docs/configuration/service/md-dhcp-relay.md @@ -0,0 +1,225 @@ +(dhcp-relay)= + +# 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. This includes the +uplink to the DHCP server. + +## IPv4 relay + +### Configuration + +```{eval-rst} +.. cfgcmd:: set service dhcp-relay interface <interface> + + Interfaces that participate in the DHCP relay process. If this command is + used, at least two entries of it are required: one for the interface that + captures the dhcp-requests, and one for the interface to forward such + requests. A warning message will be shown if this command is used, since + new implementations should use ``listen-interface`` and + ``upstream-interface``. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcp-relay listen-interface <interface> + + Interface for DHCP Relay Agent to listen for requests. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcp-relay upstream-interface <interface> + + Interface for DHCP Relay Agent to forward requests out. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcp-relay server <server> + + Configure IP address of the DHCP `<server>` which will handle the relayed + packets. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcp-relay relay-options relay-agents-packets discard + + The router should discard DHCP packages already containing relay agent + information to ensure that only requests from DHCP clients are forwarded. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcp-relay disable + + Disable dhcp-relay service. +``` + +#### Options + +```{eval-rst} +.. cfgcmd:: set service dhcp-relay relay-options hop-count <count> + + Set the maximum hop `<count>` before packets are discarded. Range 0...255, + default 10. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcp-relay relay-options max-size <size> + + 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. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcp-relay relay-options relay-agents-packets + <append | discard | forward | replace> + + 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. +``` + +### Example + +- Listen for DHCP requests on interface `eth1`. +- DHCP server is located at IPv4 address 10.0.1.4 on `eth2`. +- Router receives DHCP client requests on `eth1` and relays them to the + server at 10.0.1.4 on `eth2`. + +:::{figure} /_static/images/service_dhcp-relay01.png +:alt: DHCP relay example +:scale: 80 % + +DHCP relay example +::: + +The generated configuration will look like: + +```none +show service dhcp-relay + listen-interface eth1 + upstrem-interface eth2 + server 10.0.1.4 + relay-options { + relay-agents-packets discard + } +``` + +Also, for backwards compatibility this configuration, which uses generic +interface definition, is still valid: + +```none +show service dhcp-relay + interface eth1 + interface eth2 + server 10.0.1.4 + relay-options { + relay-agents-packets discard + } +``` + +### Operation + +```{eval-rst} +.. opcmd:: restart dhcp relay-agent + + Restart DHCP relay service +``` + +## IPv6 relay + +(dhcp-relay-ipv6-configuration)= + +### Configuration + +```{eval-rst} +.. cfgcmd:: set service dhcpv6-relay listen-interface <interface> + + Set eth1 to be the listening interface for the DHCPv6 relay. + + Multiple interfaces may be specified. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcpv6-relay upstream-interface <interface> + address <server> + + Specifies an upstream network `<interface>` from which replies from + `<server>` and other relay agents will be accepted. +``` + +(dhcp-relay-ipv6-options)= + +```{eval-rst} +.. cfgcmd:: set service dhcpv6-relay disable + + Disable dhcpv6-relay service. +``` + +(dhcp-relay-v6-options)= + +#### Options + +```{eval-rst} +.. cfgcmd:: set service dhcpv6-relay max-hop-count <count> + + Set maximum hop count before packets are discarded, default: 10 +``` + +```{eval-rst} +.. cfgcmd:: set service dhcpv6-relay use-interface-id-option + + 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. +``` + +(dhcp-relay-ipv6-example)= + +### Example + +- DHCPv6 requests are received by the router on `listening interface` `eth1` +- Requests are forwarded through `eth2` as the `upstream interface` +- External DHCPv6 server is at 2001:db8::4 + +:::{figure} /_static/images/service_dhcpv6-relay01.png +:alt: DHCPv6 relay example +:scale: 80 % + +DHCPv6 relay example +::: + +The generated configuration will look like: + +```none +commit +show service dhcpv6-relay + listen-interface eth1 { + } + upstream-interface eth2 { + address 2001:db8::4 + } +``` + +(dhcp-relay-ipv6-op-cmd)= + +### Operation + +```{eval-rst} +.. opcmd:: restart dhcpv6 relay-agent + + Restart DHCPv6 relay agent immediately. +``` diff --git a/docs/configuration/service/md-dhcp-server.md b/docs/configuration/service/md-dhcp-server.md new file mode 100644 index 00000000..0373c2c3 --- /dev/null +++ b/docs/configuration/service/md-dhcp-server.md @@ -0,0 +1,919 @@ +(dhcp-server)= + +# DHCP Server + +VyOS uses ISC DHCP server for both IPv4 and IPv6 address assignment. + +## IPv4 server + +The network topology is declared by shared-network-name and the subnet +declarations. The DHCP service can serve multiple shared networks, with each +shared network having 1 or more subnets. Each subnet must be present on an +interface. A range can be declared inside a subnet to define a pool of dynamic +addresses. Multiple ranges can be defined and can contain holes. Static +mappings can be set to assign "static" addresses to clients based on their MAC +address. + +### Configuration + +```{eval-rst} +.. cfgcmd:: set service dhcp-server hostfile-update + + Create DNS record per client lease, by adding clients to /etc/hosts file. + Entry will have format: `<shared-network-name>_<hostname>.<domain-name>` +``` + +```{eval-rst} +.. cfgcmd:: set service dhcp-server host-decl-name + + Will drop `<shared-network-name>_` from client DNS record, using only the + host declaration name and domain: `<hostname>.<domain-name>` +``` + +```{eval-rst} +.. cfgcmd:: set service dhcp-server shared-network-name <name> + domain-name <domain-name> + + The domain-name parameter should be the domain name that will be appended to + the client's hostname to form a fully-qualified domain-name (FQDN) (DHCP + Option 015). + + This is the configuration parameter for the entire shared network definition. + All subnets will inherit this configuration item if not specified locally. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcp-server shared-network-name <name> + domain-search <domain-name> + + The domain-name parameter should be the domain name used when completing DNS + request where no full FQDN is passed. This option can be given multiple times + if you need multiple search domains (DHCP Option 119). + + This is the configuration parameter for the entire shared network definition. + All subnets will inherit this configuration item if not specified locally. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcp-server shared-network-name <name> + name-server <address> + + Inform client that the DNS server can be found at `<address>`. + + This is the configuration parameter for the entire shared network definition. + All subnets will inherit this configuration item if not specified locally. + + Multiple DNS servers can be defined. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcp-server shared-network-name <name> ping-check + + When the DHCP server is considering dynamically allocating an IP address to a + client, it first sends an ICMP Echo request (a ping) to the address being + assigned. It waits for a second, and if no ICMP Echo response has been heard, + it assigns the address. + + If a response is heard, the lease is abandoned, and the server does not + respond to the client. The lease will remain abandoned for a minimum of + abandon-lease-time seconds (defaults to 24 hours). + + If there are no free addresses but there are abandoned IP addresses, the + DHCP server will attempt to reclaim an abandoned IP address regardless of the + value of abandon-lease-time. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcp-server listen-address <address> + + This configuration parameter lets the DHCP server to listen for DHCP + requests sent to the specified address, it is only realistically useful for + a server whose only clients are reached via unicasts, such as via DHCP relay + agents. +``` + +#### Individual Client Subnet + +```{eval-rst} +.. cfgcmd:: set service dhcp-server shared-network-name <name> 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. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + default-router <address> + + This is a configuration parameter for the `<subnet>`, saying that as part of + the response, tell the client that the default gateway can be reached at + `<address>`. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + name-server <address> + + This is a configuration parameter for the subnet, saying that as part of the + response, tell the client that the DNS server can be found at `<address>`. + + Multiple DNS servers can be defined. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + lease <time> + + Assign the IP address to this machine for `<time>` seconds. + + The default value is 86400 seconds which corresponds to one day. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + range <n> start <address> + + Create DHCP address range with a range id of `<n>`. DHCP leases are taken + from this pool. The pool starts at address `<address>`. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + range <n> stop <address> + + Create DHCP address range with a range id of `<n>`. DHCP leases are taken + from this pool. The pool stops with address `<address>`. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + exclude <address> + + Always exclude this address from any defined range. This address will never + be assigned by the DHCP server. + + This option can be specified multiple times. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + domain-name <domain-name> + + The domain-name parameter should be the domain name that will be appended to + the client's hostname to form a fully-qualified domain-name (FQDN) (DHCP + Option 015). +``` + +```{eval-rst} +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + domain-search <domain-name> + + The domain-name parameter should be the domain name used when completing DNS + request where no full FQDN is passed. This option can be given multiple times + if you need multiple search domains (DHCP Option 119). +``` + +```{eval-rst} +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + ping-check + + When the DHCP server is considering dynamically allocating an IP address to a + client, it first sends an ICMP Echo request (a ping) to the address being + assigned. It waits for a second, and if no ICMP Echo response has been heard, + it assigns the address. + + If a response is heard, the lease is abandoned, and the server does not + respond to the client. The lease will remain abandoned for a minimum of + abandon-lease-time seconds (defaults to 24 hours). + + If a there are no free addresses but there are abandoned IP addresses, the + DHCP server will attempt to reclaim an abandoned IP address regardless of the + value of abandon-lease-time. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + enable-failover + + Enable DHCP failover configuration for this address pool. +``` + +#### High Availability + +VyOS provides High Availability support for DHCP server. DHCP High +Availability can act in two different modes: + +- **Active-active**: both DHCP servers will respond to DHCP requests. If + `mode` is not defined, this is the default behavior. +- **Active-passive**: only `primary` server will respond to DHCP requests. + If this server goes offline, then `secondary` server will take place. + +DHCP High Availability must be configured explicitly by the following +statements on both servers: + +```{eval-rst} +.. cfgcmd:: set service dhcp-server high-availability mode [active-active + | active-passive] + + Define operation mode of High Availability feature. Default value if command + is not specified is `active-active` +``` + +```{eval-rst} +.. cfgcmd:: set service dhcp-server high-availability source-address <address> + + Local IP `<address>` used when communicating to the HA peer. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcp-server high-availability remote <address> + + Remote peer IP `<address>` of the second DHCP server in this HA + cluster. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcp-server high-availability name <name> + + Define the name of the peer server to establish and identify the HA (High Availability) connection. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcp-server high-availability status <primary + | secondary> + + The primary and secondary statements determines whether the server is primary + or 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. + + .. hint:: The dialogue between HA partners is neither encrypted nor + authenticated. Since most DHCP servers exist within an organisation's own + secure Intranet, this would be an unnecessary overhead. However, if you + have DHCP HA peers whose communications traverse insecure networks, + then we recommend that you consider the use of VPN tunneling between them + to ensure that the HA partnership is immune to disruption + (accidental or otherwise) via third parties. +``` + +#### Static mappings + +You can specify a static DHCP assignment on a per host basis. You will need the +MAC address of the station and your desired IP address. The address must be +inside the subnet definition but can be outside of the range statement. + +```{eval-rst} +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet + <subnet> static-mapping <description> mac-address <address> + + Create a new DHCP static mapping named `<description>` which is valid for + the host identified by its MAC `<address>`. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet + <subnet> static-mapping <description> ip-address <address> + + Static DHCP IP address assign to host identified by `<description>`. IP + address must be inside the `<subnet>` which is defined but can be outside + the dynamic range created with {cfgcmd}`set service dhcp-server + shared-network-name <name> subnet <subnet> range <n>`. If no ip-address is + specified, an IP from the dynamic pool is used. + + This is useful, for example, in combination with hostfile update. + + .. hint:: This is the equivalent of the host block in dhcpd.conf of + isc-dhcpd. +``` + +**Example:** + +- IP address `192.168.1.100` shall be statically mapped to + client named `client1` + +```none +set service dhcp-server shared-network-name 'NET1' subnet 192.168.1.0/24 static-mapping client1 ip-address 192.168.1.100 +set service dhcp-server shared-network-name 'NET1' subnet 192.168.1.0/24 static-mapping client1 mac-address aa:bb:11:22:33:00 +``` + +The configuration will look as follows: + +```none +show service dhcp-server shared-network-name NET1 + subnet 192.168.1.0/24 { + static-mapping client1 { + ip-address 192.168.1.100 + mac-address aa:bb:11:22:33:00 + } + } +``` + +### Options + +```{eval-rst} +.. list-table:: + :header-rows: 1 + :stub-columns: 0 + :widths: 12 7 23 40 20 + + * - Setting name + - Option number + - ISC-DHCP Option name + - Option description + - Multi + * - client-prefix-length + - 1 + - subnet-mask + - Specifies the clients subnet mask as per RFC 950. If unset, + subnet declaration is used. + - N + * - time-offset + - 2 + - time-offset + - Offset of the client's subnet in seconds from Coordinated + Universal Time (UTC) + - N + * - default-router + - 3 + - routers + - IPv4 address of router on the client's subnet + - N + * - time-server + - 4 + - time-servers + - RFC 868 time server IPv4 address + - Y + * - name-server + - 6 + - domain-name-servers + - DNS server IPv4 address + - Y + * - domain-name + - 15 + - domain-name + - Client domain name + - Y + * - ip-forwarding + - 19 + - ip-forwarding + - Enable IP forwarding on client + - N + * - ntp-server + - 42 + - ntp-servers + - IP address of NTP server + - Y + * - wins-server + - 44 + - netbios-name-servers + - NetBIOS over TCP/IP name server + - Y + * - server-identifier + - 54 + - dhcp-server-identifier + - IP address for DHCP server identifier + - N + * - bootfile-server + - siaddr + - next-server + - IPv4 address of next bootstrap server + - N + * - tftp-server-name + - 66 + - tftp-server-name + - Name or IPv4 address of TFTP server + - N + * - bootfile-name + - 67 + - bootfile-name, filename + - Bootstrap file name + - N + * - bootfile-size + - 13 + - boot-size + - Boot image length in 512-octet blocks + - N + * - smtp-server + - 69 + - smtp-server + - IP address of SMTP server + - Y + * - pop-server + - 70 + - pop-server + - IP address of POP3 server + - Y + * - domain-search + - 119 + - domain-search + - Client domain search + - Y + * - static-route + - 121, 249 + - rfc3442-static-route, windows-static-route + - Classless static route + - N + * - wpad-url + - 252 + - wpad-url, wpad-url code 252 = text + - Web Proxy Autodiscovery (WPAD) URL + - N + * - lease + - + - default-lease-time, max-lease-time + - Lease timeout in seconds (default: 86400) + - N + * - range + - + - range + - DHCP lease range + - Y + * - exclude + - + - + - IP address to exclude from DHCP lease range + - Y + * - failover + - + - + - DHCP failover parameters + - + * - static-mapping + - + - + - Name of static mapping + - Y +``` + +Multi: can be specified multiple times. + +### Raw Parameters + +Raw parameters can be passed to shared-network-name, subnet and static-mapping: + +```none +set service dhcp-server shared-network-name <name> shared-network-parameters + <text> Additional shared-network parameters for DHCP server. +set service dhcp-server shared-network-name <name> subnet <subnet> subnet-parameters + <text> Additional subnet parameters for DHCP server. +set service dhcp-server shared-network-name <name> subnet <subnet> static-mapping <description> static-mapping-parameters + <text> Additional static-mapping parameters for DHCP server. + Will be placed inside the "host" block of the mapping. +``` + +These parameters are passed as-is to isc-dhcp's dhcpd.conf under the +configuration node they are defined in. They are not validated so an error in +the raw parameters won't be caught by vyos's scripts and will cause dhcpd to +fail to start. Always verify that the parameters are correct before committing +the configuration. Refer to isc-dhcp's dhcpd.conf manual for more information: +<https://kb.isc.org/docs/isc-dhcp-44-manual-pages-dhcpdconf> + +Quotes can be used inside parameter values by replacing all quote characters +with the string `"`. They will be replaced with literal quote characters +when generating dhcpd.conf. + +### Example + +Please see the {ref}`dhcp-dns-quick-start` configuration. + +(dhcp-server-v4-example-failover)= + +#### High Availability + +Configuration of a DHCP HA pair + +- Setup DHCP HA for network 192.0.2.0/24 +- Use active-active HA mode. +- Default gateway and DNS server is at `192.0.2.254` +- The primary DHCP server named dhcp-primary uses address `192.168.189.252` +- The secondary DHCP server named dhcp-secondary uses address `192.168.189.253` +- DHCP range spans from `192.168.189.10` - `192.168.189.250` + +Common configuration, valid for both primary and secondary node. + +```none +set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 default-router '192.0.2.254' +set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 name-server '192.0.2.254' +set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 domain-name 'vyos.net' +set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 start '192.0.2.10' +set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 stop '192.0.2.250' +set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 enable-failover +``` + +**Primary** + +```none +set service dhcp-server high-availability mode 'active-active' +set service dhcp-server high-availability source-address '192.168.189.252' +set service dhcp-server high-availability name 'dhcp-secondary' +set service dhcp-server high-availability remote '192.168.189.253' +set service dhcp-server high-availability status 'primary' +``` + +**Secondary** + +```none +set service dhcp-server high-availability mode 'active-active' +set service dhcp-server high-availability source-address '192.168.189.253' +set service dhcp-server high-availability name 'dhcp-primary' +set service dhcp-server high-availability remote '192.168.189.252' +set service dhcp-server high-availability status 'secondary' +``` + +(dhcp-server-v4-example-raw)= + +#### Raw Parameters + +- Override static-mapping's name-server with a custom one that will be sent only + to this host. +- An option that takes a quoted string is set by replacing all quote characters + with the string `"` inside the static-mapping-parameters value. + The resulting line in dhcpd.conf will be + `option pxelinux.configfile "pxelinux.cfg/01-00-15-17-44-2d-aa";`. + +```none +set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping example static-mapping-parameters "option domain-name-servers 192.0.2.11, 192.0.2.12;" +set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping example static-mapping-parameters "option pxelinux.configfile "pxelinux.cfg/01-00-15-17-44-2d-aa";" +``` + +#### Option 43 for UniFI + +- These parameters need to be part of the DHCP global options. + They stay unchanged. + +```none +set service dhcp-server global-parameters 'option space ubnt;' +set service dhcp-server global-parameters 'option ubnt.unifi-address code 1 = ip-address;' +set service dhcp-server global-parameters 'class "ubnt" {' +set service dhcp-server global-parameters 'match if substring (option vendor-class-identifier, 0, 4) = "ubnt";' +set service dhcp-server global-parameters 'option vendor-class-identifier "ubnt";' +set service dhcp-server global-parameters 'vendor-option-space ubnt;' +set service dhcp-server global-parameters '}' +``` + +- Now we add the option to the scope, adapt to your setup + +```none +set service dhcp-server shared-network-name example-scope subnet 10.1.1.0/24 subnet-parameters 'option ubnt.unifi-address 172.16.1.10;' +``` + +### Operation Mode + +```{eval-rst} +.. opcmd:: show log dhcp server + + Show DHCP server daemon log file +``` + +```{eval-rst} +.. opcmd:: show log dhcp client + + Show logs from all DHCP client processes. +``` + +```{eval-rst} +.. opcmd:: show log dhcp client interface <interface> + + Show logs from specific `interface` DHCP client process. +``` + +```{eval-rst} +.. opcmd:: restart dhcp server + + Restart the DHCP server +``` + +```{eval-rst} +.. opcmd:: show dhcp server statistics + + Show the DHCP server statistics: +``` + +```none +vyos@vyos:~$ show dhcp server statistics +Pool Size Leases Available Usage +----------- ------ -------- ----------- ------- +dhcpexample 99 2 97 2% +``` + +```{eval-rst} +.. opcmd:: show dhcp server statistics pool <pool> + + Show the DHCP server statistics for the specified pool. +``` + +```{eval-rst} +.. opcmd:: show dhcp server leases + + Show statuses of all active leases: +``` + +```none +vyos@vyos:~$ show dhcp server leases +IP Address MAC address State Lease start Lease expiration Remaining Pool Hostname Origin +-------------- ----------------- ------- ------------------- ------------------- ----------- -------- ---------- -------- +192.168.11.134 00:50:79:66:68:09 active 2023/11/29 09:51:05 2023/11/29 10:21:05 0:24:10 LAN VPCS1 local +192.168.11.133 50:00:00:06:00:00 active 2023/11/29 09:51:38 2023/11/29 10:21:38 0:24:43 LAN VYOS-6 local +10.11.11.108 50:00:00:05:00:00 active 2023/11/29 09:51:43 2023/11/29 10:21:43 0:24:48 VIF-1001 VYOS5 local +192.168.11.135 00:50:79:66:68:07 active 2023/11/29 09:55:16 2023/11/29 09:59:16 0:02:21 remote +vyos@vyos:~$ +``` + +:::{hint} +Static mappings aren't shown. To show all states, use +`show dhcp server leases state all`. +::: + +```{eval-rst} +.. opcmd:: show dhcp server leases origin [local | remote] + + Show statuses of all active leases granted by local (this server) or + remote (failover server): +``` + +```none +vyos@vyos:~$ show dhcp server leases origin remote +IP Address MAC address State Lease start Lease expiration Remaining Pool Hostname Origin +-------------- ----------------- ------- ------------------- ------------------- ----------- -------- ---------- -------- +192.168.11.135 00:50:79:66:68:07 active 2023/11/29 09:55:16 2023/11/29 09:59:16 0:02:21 remote +vyos@vyos:~$ +``` + +```{eval-rst} +.. opcmd:: show dhcp server leases pool <pool> + + Show only leases in the specified pool. +``` + +```none +vyos@vyos:~$ show dhcp server leases pool LAN +IP Address MAC address State Lease start Lease expiration Remaining Pool Hostname Origin +-------------- ----------------- ------- ------------------- ------------------- ----------- ------ ---------- -------- +192.168.11.134 00:50:79:66:68:09 active 2023/11/29 09:51:05 2023/11/29 10:21:05 0:23:55 LAN VPCS1 local +192.168.11.133 50:00:00:06:00:00 active 2023/11/29 09:51:38 2023/11/29 10:21:38 0:24:28 LAN VYOS-6 local +vyos@vyos:~$ +``` + +```{eval-rst} +.. opcmd:: show dhcp server leases sort <key> + + Sort the output by the specified key. Possible keys: ip, hardware_address, + state, start, end, remaining, pool, hostname (default = ip) +``` + +```{eval-rst} +.. opcmd:: show dhcp server leases state <state> + + Show only leases with the specified state. Possible states: all, active, + free, expired, released, abandoned, reset, backup (default = active) + +``` + +## IPv6 server + +VyOS also provides DHCPv6 server functionality which is described in this +section. + +(dhcp-server-v6-config)= + +### Configuration + +```{eval-rst} +.. cfgcmd:: set service dhcpv6-server preference <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``. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> lease-time {default | maximum | minimum} + + 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 need to be supplied in seconds. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> nis-domain <domain-name> + + A {abbr}`NIS (Network Information Service)` domain can be set to be used for + DHCPv6 clients. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> nisplus-domain <domain-name> + + The procedure to specify a {abbr}`NIS+ (Network Information Service Plus)` + domain is similar to the NIS domain one: +``` + +```{eval-rst} +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> nis-server <address> + + Specify a NIS server address for DHCPv6 clients. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> nisplus-server <address> + + Specify a NIS+ server address for DHCPv6 clients. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> sip-server <address | fqdn> + + Specify a {abbr}`SIP (Session Initiation Protocol)` server by IPv6 + address of Fully Qualified Domain Name for all DHCPv6 clients. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> sntp-server-address <address> + + A SNTP server address can be specified for DHCPv6 clients. +``` + +#### Prefix Delegation + +:::{note} +VyOS =< 1.4.3 does not add the prefixes to the routing table. +::: + +To hand out individual prefixes to your clients the following configuration is +used: + +```{eval-rst} +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> prefix-delegation start <address> prefix-length <length> + + Hand out prefixes of size `<length>` to clients in subnet `<prefix>` when + they request for prefix delegation. +``` + +```{eval-rst} +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> prefix-delegation start <address> stop <address> + + Delegate prefixes from the range indicated by the start and stop qualifier. +``` + +**Example:** + +To delegate /64's from a bigger /56 + +```none +set service dhcpv6-server shared-network-name MYNET subnet 2001:db8:0:1::/64 prefix-delegation start 2001:0db8:1:: prefix-length '64' +set service dhcpv6-server shared-network-name MYNET subnet 2001:db8:0:1::/64 prefix-delegation start 2001:0db8:1:: stop '2001:0db8:1:ff::' +``` + +#### 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:** + +- A shared network named `NET1` serves subnet `2001:db8::/64` +- It is connected to `eth1` +- DNS server is located at `2001:db8::ffff` +- Address pool shall be `2001:db8::100` through `2001:db8::199`. +- Lease time will be left at the default value which is 24 hours + +```none +set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 address-range start 2001:db8::100 stop 2001:db8::199 +set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 name-server 2001:db8::ffff +``` + +The configuration will look as follows: + +```none +show service dhcpv6-server + shared-network-name NET1 { + subnet 2001:db8::/64 { + address-range { + start 2001:db8::100 { + stop 2001:db8::199 + } + } + name-server 2001:db8::ffff + } + } +``` + +(dhcp-server-v6-static-mapping)= + +#### Static mappings + +In order to map specific IPv6 addresses to specific hosts static mappings can +be created. The following example explains the process. + +**Example:** + +- IPv6 address `2001:db8::101` shall be statically mapped +- IPv6 prefix `2001:db8:0:101::/64` shall be statically mapped +- Host specific mapping shall be named `client1` + +:::{hint} +The identifier is the device's DUID: colon-separated hex list (as +used by isc-dhcp option dhcpv6.client-id). If the device already has a +dynamic lease from the DHCPv6 server, its DUID can be found with `show +service dhcpv6 server leases`. +::: + +```none +set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 ipv6-address 2001:db8::101 +set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 ipv6-prefix 2001:db8:0:101::/64 +set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 identifier 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff +``` + +The configuration will look as follows: + + +```none +show service dhcpv6-server shared-network-name NET1 + subnet 2001:db8::/64 { + static-mapping client1 { + identifier 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff + ipv6-address 2001:db8::101 + ipv6-prefix 2001:db8:0:101::/64 + } + } +``` + + +(dhcp-server-v6-op-cmd)= + +### Operation Mode + +```{eval-rst} +.. opcmd:: show log dhcpv6 server + + Show DHCPv6 server daemon log file +``` + +```{eval-rst} +.. opcmd:: show log dhcpv6 client + + Show logs from all DHCPv6 client processes. +``` + +```{eval-rst} +.. opcmd:: show log dhcpv6 client interface <interface> + + Show logs from specific `interface` DHCPv6 client process. +``` + +```{eval-rst} +.. opcmd:: restart dhcpv6 server + + To restart the DHCPv6 server +``` + +```{eval-rst} +.. opcmd:: show dhcpv6 server leases + + Shows status of all assigned leases: +``` + +```none +vyos@vyos:~$ show dhcpv6 server leases +IPv6 address State Last communication Lease expiration Remaining Type Pool DUID +------------- ------- -------------------- ------------------- ----------- ------------- ----- -------------------------------------------- +2001:db8::101 active 2019/12/05 19:40:10 2019/12/06 07:40:10 11:45:21 non-temporary NET1 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff +2001:db8::102 active 2019/12/05 14:01:23 2019/12/06 02:01:23 6:06:34 non-temporary NET1 00:01:00:01:11:22:33:44:fa:fb:fc:fd:fe:ff +``` + +:::{hint} +Static mappings aren't shown. To show all states, use `show dhcp +server leases state all`. +::: + +```{eval-rst} +.. opcmd:: show dhcpv6 server leases pool <pool> + + Show only leases in the specified pool. +``` + +```{eval-rst} +.. opcmd:: show dhcpv6 server leases sort <key> + + Sort the output by the specified key. Possible keys: expires, duid, ip, + last_comm, pool, remaining, state, type (default = ip) +``` + +```{eval-rst} +.. opcmd:: show dhcpv6 server leases state <state> + + Show only leases with the specified state. Possible states: abandoned, + active, all, backup, expired, free, released, reset (default = active) +``` diff --git a/docs/configuration/service/md-dns.md b/docs/configuration/service/md-dns.md new file mode 100644 index 00000000..1e7462e4 --- /dev/null +++ b/docs/configuration/service/md-dns.md @@ -0,0 +1,476 @@ +(dns-forwarding)= + +# DNS Forwarding + +## Configuration + +VyOS provides DNS infrastructure for small networks. It is designed to be +lightweight and have a small footprint, suitable for resource constrained +routers and firewalls. For this we utilize PowerDNS recursor. + +The VyOS DNS forwarder does not require an upstream DNS server. It can serve as +a full recursive DNS server - but it can also forward queries to configurable +upstream DNS servers. By not configuring any upstream DNS servers you also +avoid being tracked by the provider of your upstream DNS server. + +```{eval-rst} +.. cfgcmd:: set service dns forwarding system + + Forward incoming DNS queries to the DNS servers configured under the ``system + name-server`` nodes. +``` + +```{eval-rst} +.. cfgcmd:: set service dns forwarding dhcp <interface> + + Interfaces whose DHCP client nameservers to forward requests to. +``` + +```{eval-rst} +.. cfgcmd:: set service dns forwarding name-server <address> port <port> + + Send all DNS queries to the IPv4/IPv6 DNS server specified under `<address>` + on optional port specified under `<port>`. The port defaults to 53. You can + configure multiple nameservers here. +``` + +```{eval-rst} +.. cfgcmd:: set service dns forwarding domain <domain-name> name-server <address> + + Forward received queries for a particular domain + (specified via `domain-name`) to a given nameserver. Multiple nameservers + can be specified. You can use this feature for a DNS split-horizon + configuration. + + .. note:: This also works for reverse-lookup zones (``18.172.in-addr.arpa``). +``` + +```{eval-rst} +.. cfgcmd:: set service dns forwarding domain <domain-name> addnta + + Add NTA (negative trust anchor) for this domain. This must be set if the + domain does not support DNSSEC. +``` + +```{eval-rst} +.. cfgcmd:: set service dns forwarding domain <domain-name> recursion-desired + + Set the "recursion desired" bit in requests to the upstream nameserver. +``` + +```{eval-rst} +.. cfgcmd:: set service dns forwarding allow-from <network> + + Given the fact that open DNS recursors could be used on DDoS amplification + attacks, you must configure the networks which are allowed to use this + recursor. A network of ``0.0.0.0/0`` or ``::/0`` would allow all IPv4 and + IPv6 networks to query this server. This is generally a bad idea. +``` + +```{eval-rst} +.. cfgcmd:: set service dns forwarding dnssec + <off | process-no-validate | process | log-fail | validate> + + The PowerDNS recursor has 5 different levels of DNSSEC processing, which can + be set with the dnssec setting. In order from least to most processing, these + are: + + * **off** In this mode, no DNSSEC processing takes place. The recursor will + not set the DNSSEC OK (DO) bit in the outgoing queries and will ignore the + DO and AD bits in queries. + + * **process-no-validate** In this mode the recursor acts as a "security + aware, non-validating" nameserver, meaning it will set the DO-bit on + outgoing queries and will provide DNSSEC related RRsets (NSEC, RRSIG) to + clients that ask for them (by means of a DO-bit in the query), except for + zones provided through the auth-zones setting. It will not do any + validation in this mode, not even when requested by the client. + + * **process** When dnssec is set to process the behavior is similar to + process-no-validate. However, the recursor will try to validate the data + if at least one of the DO or AD bits is set in the query; in that case, + it will set the AD-bit in the response when the data is validated + successfully, or send SERVFAIL when the validation comes up bogus. + + * **log-fail** In this mode, the recursor will attempt to validate all data + it retrieves from authoritative servers, regardless of the client's DNSSEC + desires, and will log the validation result. This mode can be used to + determine the extra load and amount of possibly bogus answers before + turning on full-blown validation. Responses to client queries are the same + as with process. + + * **validate** The highest mode of DNSSEC processing. In this mode, all + queries will be validated and will be answered with a SERVFAIL in case of + bogus data, regardless of the client's request. + + .. note:: The popular Unix/Linux ``dig`` tool sets the AD-bit in the query. + This might lead to unexpected query results when testing. Set ``+noad`` + on the ``dig`` command line when this is the case. + + .. note:: The ``CD``-bit is honored correctly for process and validate. For + log-fail, failures will be logged too. +``` + +```{eval-rst} +.. cfgcmd:: set service dns forwarding ignore-hosts-file + + Do not use the local ``/etc/hosts`` file in name resolution. VyOS DHCP + server will use this file to add resolvers to assigned addresses. +``` + +```{eval-rst} +.. cfgcmd:: set service dns forwarding cache-size <0-2147483647> + + Maximum number of DNS cache entries. 1 million per CPU core will generally + suffice for most installations. + + This defaults to 10000. +``` + +```{eval-rst} +.. cfgcmd:: set service dns forwarding negative-ttl <0-7200> + + A query for which there is authoritatively no answer is cached to quickly + deny a record's existence later on, without putting a heavy load on the + remote server. In practice, caches can become saturated with hundreds of + thousands of hosts which are tried only once. + + This setting, which defaults to 3600 seconds, puts a maximum on the amount + of time negative entries are cached. +``` + +```{eval-rst} +.. cfgcmd:: set service dns forwarding timeout <10-60000> + + The number of milliseconds to wait for a remote authoritative server to + respond before timing out and responding with SERVFAIL. + + This setting defaults to 1500 and is valid between 10 and 60000. +``` + +```{eval-rst} +.. cfgcmd:: set service dns forwarding listen-address <address> + + The local IPv4 or IPv6 addresses to bind the DNS forwarder to. The forwarder + will listen on this address for incoming connections. +``` + +```{eval-rst} +.. cfgcmd:: set service dns forwarding source-address <address> + + The local IPv4 or IPv6 addresses to use as a source address for sending queries. + The forwarder will send forwarded outbound DNS requests from this address. +``` + +```{eval-rst} +.. cfgcmd:: set service dns forwarding no-serve-rfc1918 + + This makes the server authoritatively not aware of: 10.in-addr.arpa, + 168.192.in-addr.arpa, 16-31.172.in-addr.arpa, which enabling upstream + DNS server(s) to be used for reverse lookups of these zones. +``` + +## Example + +A VyOS router with two interfaces - eth0 (WAN) and eth1 (LAN) - is required to +implement a split-horizon DNS configuration for example.com. + +In this scenario: + +- All DNS requests for example.com must be forwarded to a DNS server + at 192.0.2.254 and 2001:db8:cafe::1 +- All other DNS requests will be forwarded to a different set of DNS servers at + 192.0.2.1, 192.0.2.2, 2001:db8::1:ffff and 2001:db8::2:ffff +- The VyOS DNS forwarder will only listen for requests on the eth1 (LAN) + interface addresses - 192.168.1.254 for IPv4 and 2001:db8::ffff for IPv6 +- The VyOS DNS forwarder will only accept lookup requests from the + LAN subnets - 192.168.1.0/24 and 2001:db8::/64 +- The VyOS DNS forwarder will pass reverse lookups for 10.in-addr.arpa, + 168.192.in-addr.arpa, 16-31.172.in-addr.arpa zones to upstream server. + +```none +set service dns forwarding domain example.com name-server 192.0.2.254 +set service dns forwarding domain example.com name-server 2001:db8:cafe::1 +set service dns forwarding name-server 192.0.2.1 +set service dns forwarding name-server 192.0.2.2 +set service dns forwarding name-server 192.0.2.3 port 853 +set service dns forwarding name-server 2001:db8::1:ffff +set service dns forwarding name-server 2001:db8::2:ffff +set service dns forwarding name-server 2001:db8::3:ffff port 8053 +set service dns forwarding listen-address 192.168.1.254 +set service dns forwarding listen-address 2001:db8::ffff +set service dns forwarding allow-from 192.168.1.0/24 +set service dns forwarding allow-from 2001:db8::/64 +set service dns forwarding no-serve-rfc1918 +``` + +## Operation + +```{eval-rst} +.. opcmd:: reset dns forwarding <all | domain> + + Resets the local DNS forwarding cache database. You can reset the cache + for all entries or only for entries to a specific domain. +``` + +```{eval-rst} +.. opcmd:: restart dns forwarding + + Restarts the DNS recursor process. This also invalidates the local DNS + forwarding cache. + +``` + +(dynamic-dns)= + +# 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 only one purpose. + +[ddclient] uses two methods to update a DNS record. The first one will send +updates directly to the DNS daemon, in compliance with {rfc}`2136`. The second +one involves a third party service, like DynDNS.com or any other such +service provider. This method uses HTTP requests to transmit the new IP address. You +can configure both in VyOS. + +(dns-dynmaic-config)= + +## Configuration + +### {rfc}`2136` Based + +```{eval-rst} +.. cfgcmd:: set service dns dynamic name <service-name> address interface <interface> + + Create new dynamic DNS update configuration which will update the IP + address assigned to `<interface>` on the service you configured under + `<service-name>`. +``` + +```{eval-rst} +.. cfgcmd:: set service dns dynamic name <service-name> description <text> + + Set description `<text>` for dynamic DNS service being configured. +``` + +```{eval-rst} +.. cfgcmd:: set service dns dynamic name <service-name> key <filename> + + File identified by `<filename>` containing the TSIG authentication key for RFC2136 + nsupdate on remote DNS server. +``` + +```{eval-rst} +.. cfgcmd:: set service dns dynamic name <service-name> server <server> + + Configure the DNS `<server>` IP/FQDN used when updating this dynamic + assignment. +``` + +```{eval-rst} +.. cfgcmd:: set service dns dynamic name <service-name> zone <zone> + + Configure DNS `<zone>` to be updated. +``` + +```{eval-rst} +.. cfgcmd:: set service dns dynamic name <service-name> host-name <record> + + Configure DNS `<record>` which should be updated. This can be set multiple times. +``` + +```{eval-rst} +.. cfgcmd:: set service dns dynamic name <service-name> ttl <ttl> + + Configure optional TTL value on the given resource record. This defaults to + 600 seconds. +``` + +```{eval-rst} +.. cfgcmd:: set service dns dynamic interval <60-3600> + + Specify interval in seconds to wait between Dynamic DNS updates. + The default is 300 seconds. +``` + +(dns-dynmaic-example)= + +#### Example + +- Register DNS record `example.vyos.io` on DNS server `ns1.vyos.io` +- Use auth key file at `/config/auth/my.key` +- Set TTL to 300 seconds + +```none +# Configuration commands entered: +# +set service dns dynamic name 'VyOS-DNS' address interface 'eth0' +set service dns dynamic name 'VyOS-DNS' description 'RFC 2136 dynamic dns service' +set service dns dynamic name 'VyOS-DNS' key '/config/auth/my.key' +set service dns dynamic name 'VyOS-DNS' server 'ns1.vyos.io' +set service dns dynamic name 'VyOS-DNS' zone 'vyos.io' +set service dns dynamic name 'VyOS-DNS' host-name 'example.vyos.io' +set service dns dynamic name 'VyOS-DNS' protocol 'nsupdate' +set service dns dynamic name 'VyOS-DNS' ttl '300' + +# Resulting config: +# +vyos@vyos# show service dns dynamic + name VyOS-DNS { + address { + interface eth0 + } + description "RFC 2136 dynamic dns service" + host-name example.vyos.io + key /config/auth/my.key + protocol nsupdate + server ns1.vyos.io + ttl 300 + zone vyos.io + } +``` + +This will render the following [ddclient] configuration entry: + +```none +# ddclient configuration for interface "eth0": +# + +# Web service dynamic DNS configuration for VyOS-DNS: [nsupdate, example.vyos.io] +use=if, \ +if=eth0, \ +protocol=nsupdate, \ +server=ns1.vyos.io, \ +zone=vyos.io, \ +password='/config/auth/my.key', \ +ttl=300 \ +example.vyos.io +``` + +:::{note} +You can also keep different DNS zone updated. Just create a new +config node: `set service dns dynamic interface <interface> rfc2136 +<other-service-name>` +::: + +### HTTP based services + +VyOS is also able to use any service relying on protocols supported by ddclient. + +To use such a service, one must define a login, password, one or multiple +hostnames, protocol and server. + +```{eval-rst} +.. cfgcmd:: set service dns dynamic name <service-name> address interface <interface> + + Create new dynamic DNS update configuration which will update the IP + address assigned to `<interface>` on the service you configured under + `<service-name>`. +``` + +```{eval-rst} +.. cfgcmd:: set service dns dynamic name <service-name> description <text> + + Set description `<text>` for dynamic DNS service being configured. +``` + +```{eval-rst} +.. cfgcmd:: set service dns dynamic name <service-name> host-name <hostname> + + Setup the dynamic DNS hostname `<hostname>` associated with the DynDNS + provider identified by `<service-name>`. +``` + +```{eval-rst} +.. cfgcmd:: set service dns dynamic name <service-name> username <username> + + Configure `<username>` used when authenticating the update request for + DynDNS service identified by `<service-name>`. +``` + +```{eval-rst} +.. cfgcmd:: set service dns dynamic name <service-name> password <password> + + Configure `<password>` used when authenticating the update request for + DynDNS service identified by `<service-name>`. +``` + +```{eval-rst} +.. cfgcmd:: set service dns dynamic name <service-name> protocol <protocol> + + When a ``custom`` DynDNS provider is used, the protocol used for communicating + to the provider must be specified under `<protocol>`. See the embedded + completion helper when entering above command for available protocols. +``` + +```{eval-rst} +.. cfgcmd:: set service dns dynamic name <service-name> server <server> + + When a ``custom`` DynDNS provider is used the `<server>` where update + requests are being sent to must be specified. +``` + +```{eval-rst} +.. cfgcmd:: set service dns dynamic name <service-name> ip-version 'ipv6' + + Allow explicit IPv6 address for the interface. + +``` + +#### Example: + +Use deSEC (dedyn.io) as your preferred provider: + +```none +set service dns dynamic name dedyn description 'deSEC dynamic dns service' +set service dns dynamic name dedyn username 'myusername' +set service dns dynamic name dedyn password 'mypassword' +set service dns dynamic name dedyn host-name 'myhostname.dedyn.io' +set service dns dynamic name dedyn protocol 'dyndns2' +set service dns dynamic name dedyn server 'update.dedyn.io' +set service dns dynamic name dedyn address interface 'eth0' +``` + +:::{note} +Multiple services can be used per interface. Just specify as many +services per interface as you like! +::: + +#### Example IPv6 only: + +```none +set service dns dynamic name dedyn description 'deSEC ipv6 dynamic dns service' +set service dns dynamic name dedyn username 'myusername' +set service dns dynamic name dedyn password 'mypassword' +set service dns dynamic name dedyn host-name 'myhostname.dedyn.io' +set service dns dynamic name dedyn protocol 'dyndns2' +set service dns dynamic name dedyn ip-version 'ipv6' +set service dns dynamic name dedyn server 'update6.dedyn.io' +set service dns dynamic name dedyn address interface 'eth0' +``` + +### Running 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: + +```{eval-rst} +.. cfgcmd:: set service dns dynamic name <service-name> address web <url> + + Use configured `<url>` to determine your IP address. ddclient_ will load + `<url>` and tries to extract your IP address from the response. +``` + +```{eval-rst} +.. cfgcmd:: set service dns dynamic name <service-name> address web skip <pattern> + + ddclient_ will skip any address located before the string set in `<pattern>`. +``` + +[ddclient]: https://github.com/ddclient/ddclient diff --git a/docs/configuration/service/md-eventhandler.md b/docs/configuration/service/md-eventhandler.md new file mode 100644 index 00000000..0d764aba --- /dev/null +++ b/docs/configuration/service/md-eventhandler.md @@ -0,0 +1,122 @@ +(event-handler)= + +# Event Handler + +## Event Handler Technology Overview + +Event handler allows you to execute scripts when a string that matches a regex or a regex with +a service name appears in journald logs. You can pass variables, arguments, and a full matching string to the script. + +## How to configure Event Handler + +> [1. Create an event handler] +> +> [2. Add regex to the script] +> +> [3. Add a full path to the script] +> +> [4. Add optional parameters] + +## Event Handler Configuration Steps + +### 1. Create an event handler + +> ```{eval-rst} +> .. cfgcmd:: set service event-handler event <event-handler name> +> ``` +> +> This is an optional command because the event handler will be automatically created after any of the next commands. + +### 2. Add regex to the script + +> ```{eval-rst} +> .. cfgcmd:: set service event-handler event <event-handler name> filter pattern <regex> +> ``` +> +> This is a mandatory command. Sets regular expression to match against log string message. +> +> :::{note} +> The regular expression matches if and only if the entire string matches the pattern. +> ::: + +### 3. Add a full path to the script + +> ```{eval-rst} +> .. cfgcmd:: set service event-handler event <event-handler name> script path <path to script> +> ``` +> +> This is a mandatory command. Sets the full path to the script. The script file must be executable. + +### 4. Add optional parameters + +> ```{eval-rst} +> .. cfgcmd:: set service event-handler event <event-handler name> filter syslog-identifier <sylogid name> +> ``` +> +> This is an optional command. Filters log messages by syslog-identifier. +> +> ```{eval-rst} +> .. cfgcmd:: set service event-handler event <event-handler name> script environment <env name> value <env value> +> ``` +> +> This is an optional command. Adds environment and its value to the script. Use separate commands for each environment. +> +> One implicit environment exists. +> +> - `message`: Full message that has triggered the script. +> +> ```{eval-rst} +> .. cfgcmd:: set service event-handler event <event-handler name> script arguments <arguments> +> ``` +> +> This is an optional command. Adds arguments to the script. Arguments must be separated by spaces. +> +> :::{note} +> We don't recomend to use arguments. Using environments is more preffereble. +> ::: + +## Example + +> Event handler that monitors the state of interface eth0. +> +> ```none +> set service event-handler event INTERFACE_STATE_DOWN filter pattern '.*eth0.*,RUNNING,.*->.*' +> set service event-handler event INTERFACE_STATE_DOWN filter syslog-identifier 'netplugd' +> set service event-handler event INTERFACE_STATE_DOWN script environment interface_action value 'down' +> set service event-handler event INTERFACE_STATE_DOWN script environment interface_name value 'eth2' +> set service event-handler event INTERFACE_STATE_DOWN script path '/config/scripts/eventhandler.py' +> ``` +> +> Event handler script +> +> ```none +> #!/usr/bin/env python3 +> # +> # VyOS event-handler script example +> from os import environ +> import subprocess +> from sys import exit +> +> # Perform actions according to requirements +> def process_event() -> None: +> # Get variables +> message_text = environ.get('message') +> interface_name = environ.get('interface_name') +> interface_action = environ.get('interface_action') +> # Print the message that triggered this script +> print(f'Logged message: {message_text}') +> # Prepare a command to run +> command = f'sudo ip link set {interface_name} {interface_action}'.split() +> # Execute a command +> subprocess.run(command) +> +> if __name__ == '__main__': +> try: +> # Run script actions and exit +> process_event() +> exit(0) +> except Exception as err: +> # Exit properly in case if something in the script goes wrong +> print(f'Error running script: {err}') +> exit(1) +> ``` diff --git a/docs/configuration/service/md-https.md b/docs/configuration/service/md-https.md new file mode 100644 index 00000000..c2e97453 --- /dev/null +++ b/docs/configuration/service/md-https.md @@ -0,0 +1,100 @@ +(http-api)= + +# HTTP API + +VyOS provide an HTTP API. You can use it to execute op-mode commands, +update VyOS, set or delete config. + +Please take a look at the {ref}`vyosapi` page for an detailed how-to. + +## Configuration + +```{eval-rst} +.. cfgcmd:: set service https allow-client address <address> + + Only allow certain IP addresses or prefixes to access the https + webserver. +``` + +```{eval-rst} +.. cfgcmd:: set service https certificates ca-certificate <name> + + Use CA certificate from PKI subsystem +``` + +```{eval-rst} +.. cfgcmd:: set service https certificates certificate <name> + + Use certificate from PKI subsystem +``` + +```{eval-rst} +.. cfgcmd:: set service https certificates dh-params <name> + + Use {abbr}`DH (Diffie–Hellman)` parameters from PKI subsystem. + Must be at least 2048 bits in length. +``` + +```{eval-rst} +.. cfgcmd:: set service https listen-address <address> + + Webserver should only listen on specified IP address +``` + +```{eval-rst} +.. cfgcmd:: set service https port <number> + + Webserver should listen on specified port. + + Default: 443 +``` + +```{eval-rst} +.. cfgcmd:: set service https enable-http-redirect + + Enable automatic redirect from http to https. +``` + +```{eval-rst} +.. cfgcmd:: set service https tls-version <1.2 | 1.3> + + Select TLS version used. + + This defaults to both 1.2 and 1.3. +``` + +```{eval-rst} +.. cfgcmd:: set service https vrf <name> + + Start Webserver in given VRF. +``` + +### API + +```{eval-rst} +.. cfgcmd:: set service https api keys id <name> key <apikey> + + Set a named api key. Every key has the same, full permissions + on the system. +``` + +```{eval-rst} +.. cfgcmd:: set service https api debug + + To enable debug messages. Available via {opcmd}`show log` or + {opcmd}`monitor log` +``` + +```{eval-rst} +.. cfgcmd:: set service https api strict + + Enforce strict path checking +``` + +## Example Configuration + +Set an API-KEY is the minimal configuration to get a working API Endpoint. + +```none +set service https api keys id MY-HTTPS-API-ID key MY-HTTPS-API-PLAINTEXT-KEY +``` diff --git a/docs/configuration/service/md-ids.md b/docs/configuration/service/md-ids.md new file mode 100644 index 00000000..813c7ca4 --- /dev/null +++ b/docs/configuration/service/md-ids.md @@ -0,0 +1,200 @@ +(ids)= + +# DDoS Protection + +## FastNetMon + +FastNetMon is a high-performance DDoS detector/sensor built on top of multiple +packet capture engines: NetFlow, IPFIX, sFlow, AF_PACKET (port mirror). It can +detect hosts in the deployed network sending or receiving large volumes of +traffic, packets/bytes/flows per second and perform a configurable action to +handle that event, such as calling a custom script. + +VyOS includes the FastNetMon Community Edition. + +### Configuration + +```{eval-rst} +.. cfgcmd:: set service ids ddos-protection alert-script <text> + + Configure alert script that will be executed when an attack is detected. +``` + +```{eval-rst} +.. cfgcmd:: set service ids ddos-protection ban-time <1-4294967294> + + Configure how long an IP (attacker) should be kept in blocked state. + Default value is 1900. +``` + +```{eval-rst} +.. cfgcmd:: set service ids ddos-protection direction [in | out] + + Configure direction for processing traffic. +``` + +```{eval-rst} +.. cfgcmd:: set service ids ddos-protection exclude-network <x.x.x.x/x> +``` + +```{eval-rst} +.. cfgcmd:: set service ids ddos-protection exlude-network <h:h:h:h:h:h:h:h/x> + + Specify IPv4 and/or IPv6 networks which are going to be excluded. +``` + +```{eval-rst} +.. cfgcmd:: set service ids ddos-protection listen-interface <text> + + Configure listen interface for mirroring traffic. +``` + +```{eval-rst} +.. cfgcmd:: set service ids ddos-protection mode [mirror | sflow] + + Configure traffic capture mode. +``` + +```{eval-rst} +.. cfgcmd:: set service ids ddos-protection network <x.x.x.x/x> +``` + +```{eval-rst} +.. cfgcmd:: set service ids ddos-protection network <h:h:h:h:h:h:h:h/x> + + Specify IPv4 and/or IPv6 networks that should be protected/monitored. +``` + +```{eval-rst} +.. cfgcmd:: set service ids ddos-protection sflow listen-address <x.x.x.x> + + Configure local IPv4 address to listen for sflow. +``` + +```{eval-rst} +.. cfgcmd:: set service ids ddos-protection sflow port <1-65535> + + Configure port number to be used for sflow conection. Default port is 6343. +``` + +```{eval-rst} +.. cfgcmd:: set service ids ddos-protection threshold general + [fps | mbps | pps] <0-4294967294> + + Configure general threshold parameters. +``` + +```{eval-rst} +.. cfgcmd:: set service ids ddos-protection threshold icmp + [fps | mbps | pps] <0-4294967294> + + Configure ICMP threshold parameters. +``` + +```{eval-rst} +.. cfgcmd:: set service ids ddos-protection threshold tcp + [fps | mbps | pps] <0-4294967294> + + Configure TCP threshold parameters +``` + +```{eval-rst} +.. cfgcmd:: set service ids ddos-protection threshold udp + [fps | mbps | pps] <0-4294967294> + + Configure UDP threshold parameters +``` + +### Example + +A configuration example can be found in this section. +In this simplified scenario, main things to be considered are: + +> - Network to be protected: 192.0.2.0/24 (public IPs use by +> customers) +> - **ban-time** and **threshold**: these values are kept very low in order +> to easily identify and generate and attack. +> - Direction: **in** and **out**. Protect public network from external +> attacks, and identify internal attacks towards internet. +> - Interface **eth0** used to connect to upstream. + +Since we are analyzing attacks to and from our internal network, two types +of attacks can be identified, and differents actions are needed: + +> - External attack: an attack from the internet towards an internal IP +> is identify. In this case, all connections towards such IP will be +> blocked +> - Internal attack: an attack from the internal network (generated by a +> customer) towards the internet is identify. In this case, all connections +> from this particular IP/Customer will be blocked. + +So, firewall configuration needed for this setup: + +```none +set firewall group address-group FNMS-DST-Block +set firewall group address-group FNMS-SRC-Block + +set firewall ipv4 forward filter rule 10 action 'drop' +set firewall ipv4 forward filter rule 10 description 'FNMS - block destination' +set firewall ipv4 forward filter rule 10 destination group address-group 'FNMS-DST-Block' + +set firewall ipv4 forward filter rule 20 action 'drop' +set firewall ipv4 forward filter rule 20 description 'FNMS - Block source' +set firewall ipv4 forward filter rule 20 source group address-group 'FNMS-SRC-Block' +``` + +Then, FastNetMon configuration: + +```none +set service ids ddos-protection alert-script '/config/scripts/fnm-alert.sh' +set service ids ddos-protection ban-time '10' +set service ids ddos-protection direction 'in' +set service ids ddos-protection direction 'out' +set service ids ddos-protection listen-interface 'eth0' +set service ids ddos-protection mode 'mirror' +set service ids ddos-protection network '192.0.2.0/24' +set service ids ddos-protection threshold general pps '100' +``` + +And content of the script: + +```none +#!/bin/bash + +# alert-script is called twice. +# When an attack occurs, the program calls a bash script twice: +# 1st time when threshold exceed +# 2nd when we collect 100 packets for detailed audit of what happened. + +# Do nothing if “attack_details” is passed as an argument +if [ "${4}" == "attack_details" ]; then + # Do nothing + exit +fi +# Arguments: +ip=$1 +direction=$2 +pps_rate=$3 +action=$4 + +logger -t FNMS "** Start - Running alert script **" + +if [ "${direction}" == "incoming" ] ; then + group="FNMS-DST-Block" + origin="external" +else + group="FNMS-SRC-Block" + origin="internal" +fi + +if [ "${action}" == "ban" ] ; then + logger -t FNMS "Attack detected for IP ${ip} and ${direction} direction from ${origin} network. Need to block IP address." + logger -t FNMS "Adding IP address ${ip} to firewall group ${group}." + sudo nft add element ip vyos_filter A_${group} { ${ip} } +else + logger -t FNMS "Timeout for IP ${ip}, removing it from group ${group}." + sudo nft delete element ip vyos_filter A_${group} { ${ip} } +fi +logger -t FNMS "** End - Running alert script **" +exit +``` diff --git a/docs/configuration/service/md-index.md b/docs/configuration/service/md-index.md new file mode 100644 index 00000000..4c11daaf --- /dev/null +++ b/docs/configuration/service/md-index.md @@ -0,0 +1,30 @@ +# Service + +```{eval-rst} +.. toctree:: + :maxdepth: 1 + :includehidden: + + broadcast-relay + config-sync + conntrack-sync + console-server + dhcp-relay + dhcp-server + dns + eventhandler + https + ids + ipoe-server + lldp + mdns + monitoring + ntp + pppoe-server + router-advert + salt-minion + snmp + ssh + tftp-server + webproxy +``` diff --git a/docs/configuration/service/md-ipoe-server.md b/docs/configuration/service/md-ipoe-server.md new file mode 100644 index 00000000..bdb55973 --- /dev/null +++ b/docs/configuration/service/md-ipoe-server.md @@ -0,0 +1,531 @@ +(ipoe-server)= + +# IPoE Server + +VyOS utilizes [accel-ppp] to provide {abbr}`IPoE (Internet Protocol over +Ethernet)` server functionality. It can be used with local authentication +(mac-address) or a connected RADIUS server. + +IPoE is a method of delivering an IP payload over an Ethernet-based access +network or an access network using bridged Ethernet over Asynchronous Transfer +Mode (ATM) without using PPPoE. It directly encapsulates the IP datagrams in +Ethernet frames, using the standard {rfc}`894` encapsulation. + +The use of IPoE addresses the disadvantage that PPP is unsuited for multicast +delivery to multiple users. Typically, IPoE uses Dynamic Host Configuration +Protocol and Extensible Authentication Protocol to provide the same +functionality as PPPoE, but in a less robust manner. + +:::{note} +Please be aware, due to an upstream bug, config changes/commits +will restart the ppp daemon and will reset existing IPoE sessions, +in order to become effective. +::: + +## Configuring IPoE Server + +IPoE can be configure on different interfaces, it will depend on each specific +situation which interface will provide IPoE to clients. The clients mac address +and the incoming interface is being used as control parameter, to authenticate +a client. + +The example configuration below will assign an IP to the client on the incoming +interface eth2 with the client mac address 08:00:27:2f:d8:06. Other DHCP +discovery requests will be ignored, unless the client mac has been enabled in +the configuration. + +```none +set interfaces ethernet eth1 address '192.168.0.1/24' +set service ipoe-server authentication interface eth1.100 mac 00:50:79:66:68:00 +set service ipoe-server authentication interface eth1.101 mac 00:50:79:66:68:01 +set service ipoe-server authentication mode 'local' +set service ipoe-server client-ip-pool IPOE-POOL range '192.168.0.2-192.168.0.254' +set service ipoe-server default-pool 'IPOE-POOL' +set service ipoe-server gateway-address '192.168.0.1/24' +set service ipoe-server interface eth1 mode 'l2' +set service ipoe-server interface eth1 network 'vlan' +set service ipoe-server interface eth1 vlan '100-200' +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server authentication interface <interface> mac <MAC> + + Creates local IPoE user with username=**<interface>** and + password=**<MAC>** (mac-address) +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server authentication mode <local | radius> + + Set authentication backend. The configured authentication backend is used + for all queries. + + * **radius**: All authentication queries are handled by a configured RADIUS + server. + * **local**: All authentication queries are handled locally. + * **noauth**: Authentication disabled +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server client-ip-pool <POOL-NAME> range <x.x.x.x-x.x.x.x | x.x.x.x/x> + + Use this command to define the first IP address of a pool of + addresses to be given to IPoE clients. If notation ``x.x.x.x-x.x.x.x``, + it must be within a /24 subnet. If notation ``x.x.x.x/x`` is + used there is possibility to set host/netmask. +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server default-pool <POOL-NAME> + + Use this command to define default address pool name. +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server gateway-address <x.x.x.x/x> + + Specifies address to be used as server ip address if radius can assign + only client address. In such case if client address is matched network + and mask then specified address and mask will be used. You can specify + multiple such options. +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server interface <interface> mode <l2 | l3> + + Set authentication backend. The configured authentication backend is used + for all queries. + + * **l2**: It means that clients are on same network where interface + is.**(default)** + * **local**: It means that client are behind some router. +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server interface <interface> network <shared | vlan> + + Specify where interface is shared by multiple users or it is vlan-per-user. + + * **shared**: Multiple clients share the same network. **(default)** + * **vlan**: One VLAN per client. +``` + +```none +vyos@vyos:~$ show ipoe-server sessions + + ifname | username | calling-sid | ip | rate-limit | type | comp | state | uptime +--------+----------+-------------------+-------------+------------+------+------+--------+---------- + ipoe0 | eth1.100 | 00:50:79:66:68:00 | 192.168.0.2 | | ipoe | | active | 00:04:55 + ipoe1 | eth1.101 | 00:50:79:66:68:01 | 192.168.0.3 | | ipoe | | active | 00:04:44 +``` + +## Configuring RADIUS authentication + +To enable RADIUS based authentication, the authentication mode needs to be +changed within the configuration. Previous settings like the local users, still +exists within the configuration, however they are not used if the mode has been +changed from local to radius. Once changed back to local, it will use all local +accounts again. + +```none +set service ipoe-server authentication mode radius +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server authentication radius server <server> key <secret> + + Configure RADIUS `<server>` and its required shared `<secret>` for + communicating with the RADIUS server. +``` + +Since the RADIUS server would be a single point of failure, multiple RADIUS +servers can be setup and will be used subsequentially. +For example: + +```none +set service ipoe-server authentication radius server 10.0.0.1 key 'foo' +set service ipoe-server authentication radius server 10.0.0.2 key 'foo' +``` + +:::{note} +Some RADIUS severs use an access control list which allows or denies +queries, make sure to add your VyOS router to the allowed client list. +::: + +### RADIUS source address + +If you are using OSPF as IGP, always the closest interface connected to 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. + +```{eval-rst} +.. cfgcmd:: set service ipoe-server authentication radius source-address <address> + + Source IPv4 address used in all RADIUS server queires. +``` + +:::{note} +The `source-address` must be configured on one of VyOS interface. +Best practice would be a loopback or dummy interface. +::: + +### RADIUS advanced options + +```{eval-rst} +.. cfgcmd:: set service ipoe-server authentication radius server <server> port <port> + + Configure RADIUS `<server>` and its required port for authentication requests. +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server authentication radius server <server> fail-time <time> + + Mark RADIUS server as offline for this given `<time>` in seconds. +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server authentication radius server <server> disable + + Temporary disable this RADIUS server. +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server authentication radius acct-timeout <timeout> + + Timeout to wait reply for Interim-Update packets. (default 3 seconds) +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server authentication radius dynamic-author server <address> + + Specifies IP address for Dynamic Authorization Extension server (DM/CoA) +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server authentication radius dynamic-author port <port> + + Port for Dynamic Authorization Extension server (DM/CoA) +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server authentication radius dynamic-author key <secret> + + Secret for Dynamic Authorization Extension server (DM/CoA) +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server authentication radius max-try <number> + + Maximum number of tries to send Access-Request/Accounting-Request queries +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server authentication radius timeout <timeout> + + Timeout to wait response from server (seconds) +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server authentication radius nas-identifier <identifier> + + Value to send to RADIUS server in NAS-Identifier attribute and to be matched + in DM/CoA requests. +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server authentication radius nas-ip-address <address> + + Value to send to RADIUS server in NAS-IP-Address attribute and to be matched + in DM/CoA requests. Also DM/CoA server will bind to that address. +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server authentication radius source-address <address> + + Source IPv4 address used in all RADIUS server queires. +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server authentication radius rate-limit attribute <attribute> + + Specifies which RADIUS server attribute contains the rate limit information. + The default attribute is `Filter-Id`. +``` + +:::{note} +If you set a custom RADIUS attribute you must define it on both +dictionaries at RADIUS server and client. +::: + +```{eval-rst} +.. cfgcmd:: set service ipoe-server authentication radius rate-limit enable + + Enables bandwidth shaping via RADIUS. +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server authentication radius rate-limit vendor + + Specifies the vendor dictionary, dictionary needs to be in + /usr/share/accel-ppp/radius. +``` + +Received RADIUS attributes have a higher priority than parameters defined within +the CLI configuration, refer to the explanation below. + +### Allocation clients ip addresses by RADIUS + +If the RADIUS server sends the attribute `Framed-IP-Address` then this IP +address will be allocated to the client and the option `default-pool` within the CLI +config is being ignored. + +If the RADIUS server sends the attribute `Framed-Pool`, IP address will be allocated +from a predefined IP pool whose name equals the attribute value. + +If the RADIUS server sends the attribute `Stateful-IPv6-Address-Pool`, IPv6 address +will be allocated from a predefined IPv6 pool `prefix` whose name equals the attribute value. + +If the RADIUS server sends the attribute `Delegated-IPv6-Prefix-Pool`, IPv6 +delegation pefix will be allocated from a predefined IPv6 pool `delegate` +whose name equals the attribute value. + +:::{note} +`Stateful-IPv6-Address-Pool` and `Delegated-IPv6-Prefix-Pool` are defined in +RFC6911. If they are not defined in your RADIUS server, add new [dictionary]. +::: + +User interface can be put to VRF context via RADIUS Access-Accept packet, or change +it via RADIUS CoA. `Accel-VRF-Name` is used from these purposes. It is custom [ACCEL-PPP attribute]. +Define it in your RADIUS server. + +## IPv6 + +```{eval-rst} +.. cfgcmd:: set service ipoe-server client-ipv6-pool <IPv6-POOL-NAME> prefix <address> + mask <number-of-bits> + + Use this comand to set the IPv6 address pool from which an IPoE client + will get an IPv6 prefix of your defined length (mask) to terminate the + IPoE endpoint at their side. The mask length can be set from 48 to 128 + bit long, the default value is 64. +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server client-ipv6-pool <IPv6-POOL-NAME> delegate <address> + delegation-prefix <number-of-bits> + + Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on + IPoE. You will have to set your IPv6 pool and the length of the + delegation prefix. From the defined IPv6 pool you will be handing out + networks of the defined length (delegation-prefix). The length of the + delegation prefix can be set from 32 to 64 bit long. +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server default-ipv6-pool <IPv6-POOL-NAME> + + Use this command to define default IPv6 address pool name. +``` + +```none +set service ipoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' +set service ipoe-server client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' +set service ipoe-server default-ipv6-pool IPv6-POOL +``` + +## Scripting + +```{eval-rst} +.. cfgcmd:: set service ipoe-server extended-scripts on-change <path_to_script> + + Script to run when session interface changed by RADIUS CoA handling +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server extended-scripts on-down <path_to_script> + + Script to run when session interface going to terminate +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server extended-scripts on-pre-up <path_to_script> + + Script to run before session interface comes up +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server extended-scripts on-up <path_to_script> + + Script to run when session interface is completely configured and started +``` + +## Advanced Options + +### Authentication Advanced Options + +```{eval-rst} +.. cfgcmd:: set service ipoe-server authentication interface <interface> mac <MAC> vlan + <vlan-id> + + VLAN monitor for automatic creation of VLAN interfaces for specific user on specific <interface> +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server authentication interface <interface> mac <MAC> rate-limit + download <bandwidth> + + Download bandwidth limit in kbit/s for user on interface `<interface>`. +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server authentication interface <interface> mac <MAC> rate-limit + upload <bandwidth> + + Upload bandwidth limit in kbit/s for for user on interface `<interface>`. +``` + +### Client IP Pool Advanced Options + +```{eval-rst} +.. cfgcmd:: set service ipoe-server client-ip-pool <POOL-NAME> next-pool <NEXT-POOL-NAME> + + Use this command to define the next address pool name. +``` + +### Advanced Interface Options + +```{eval-rst} +.. cfgcmd:: set service ipoe-server interface <interface> client-subnet <x.x.x.x/x> + + Specify local range of ip address to give to dhcp clients. First IP in range is router IP. + If you need more customization use `client-ip-pool` +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server interface <interface> external-dhcp dhcp-relay <x.x.x.x> + + Specify DHCPv4 relay IP address to pass requests to. If specified giaddr is also needed. +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server interface <interface> external-dhcp giaddr <x.x.x.x> + + Specifies relay agent IP addre + +``` + +### Global Advanced options + +```{eval-rst} +.. cfgcmd:: set service ipoe-server description <description> + + Set description. +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server limits burst <value> + + Burst count +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server limits connection-limit <value> + + Acceptable rate of connections (e.g. 1/min, 60/sec) +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server limits timeout <value> + + Timeout in seconds +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server max-concurrent-sessions + + Maximum number of concurrent session start attempts +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server name-server <address> + + Connected client should use `<address>` as their DNS server. This + command accepts both IPv4 and IPv6 addresses. Up to two nameservers + can be configured for IPv4, up to three for IPv6. +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server shaper fwmark <1-2147483647> + + Match firewall mark value +``` + +```{eval-rst} +.. cfgcmd:: set service ipoe-server snmp master-agent + + Enable SNMP +``` + +## Monitoring + +```{eval-rst} +.. opcmd:: show ipoe-server sessions + + Use this command to locally check the active sessions in the IPoE + server. +``` + +```none +vyos@vyos:~$ show ipoe-server sessions +ifname | username | calling-sid | ip | rate-limit | type | comp | state | uptime +----------+----------+-------------------+-------------+------------+------+------+--------+---------- + eth1.100 | eth1.100 | 0c:98:bd:b8:00:01 | 192.168.0.3 | | ipoe | | active | 03:03:58 +``` + +```none +vyos@vyos:~$ show ipoe-server statistics +uptime: 0.03:31:36 +cpu: 0% +mem(rss/virt): 6044/101360 kB +core: + mempool_allocated: 148628 + mempool_available: 144748 + thread_count: 1 + thread_active: 1 + context_count: 10 + context_sleeping: 0 + context_pending: 0 + md_handler_count: 6 + md_handler_pending: 0 + timer_count: 1 + timer_pending: 0 +sessions: + starting: 0 + active: 1 + finishing: 0 +ipoe: + starting: 0 + active: 1 + delayed: 0 +``` + +## Toubleshooting + +```none +vyos@vyos:~$sudo journalctl -u accel-ppp@ipoe -b 0 + +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:: recv [DHCPv4 Discover xid=55df9228 chaddr=0c:98:bd:b8:00:01 <Message-Type Discover> <Request-IP 192.168.0.3> <Host-Name vyos> <Request-List Subnet,Broadcast,Router,DNS,Classless-Route,Domain-Name,MTU>] +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: eth1.100: authentication succeeded +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: send [DHCPv4 Offer xid=55df9228 yiaddr=192.168.0.4 chaddr=0c:98:bd:b8:00:01 <Message-Type Offer> <Server-ID 192.168.0.1> <Lease-Time 600> <T1 300> <T2 525> <Router 192.168.0.1> <Subnet 255.255.255.0>] +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: recv [DHCPv4 Request xid=55df9228 chaddr=0c:98:bd:b8:00:01 <Message-Type Request> <Server-ID 192.168.0.1> <Request-IP 192.168.0.4> <Host-Name vyos> <Request-List Subnet,Broadcast,Router,DNS,Classless-Route,Domain-Name,MTU>] +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: ipoe: activate session +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: ipoe: no free IPv6 address +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: ipoe: session started +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: send [DHCPv4 Ack xid=55df9228 yiaddr=192.168.0.4 chaddr=0c:98:bd:b8:00:01 <Message-Type Ack> <Server-ID 192.168.0.1> <Lease-Time 600> <T1 300> <T2 525> <Router 192.168.0.1> <Subnet 255.255.255.0>] +``` + +```{include} /_include/common-references.txt +``` + +[accel-ppp attribute]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel +[dictionary]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911 diff --git a/docs/configuration/service/md-lldp.md b/docs/configuration/service/md-lldp.md new file mode 100644 index 00000000..cb287dbf --- /dev/null +++ b/docs/configuration/service/md-lldp.md @@ -0,0 +1,158 @@ +(lldp)= + +# LLDP + +{abbr}`LLDP (Link Layer Discovery Protocol)` 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. 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 +{abbr}`CDP (Cisco Discovery Protocol)`, +{abbr}`FDP (Foundry Discovery Protocol)`, +{abbr}`NDP (Nortel Discovery Protocol)` and {abbr}`LLTD (Link Layer Topology +Discovery)`. + +Information gathered with LLDP is stored in the device as a {abbr}`MIB +(Management Information Database)` and can be queried with {abbr}`SNMP (Simple +Network Management Protocol)` 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 + +```{eval-rst} +.. cfgcmd:: set service lldp + + Enable LLDP service +``` + +```{eval-rst} +.. cfgcmd:: set service lldp management-address <address> + + Define IPv4/IPv6 management address transmitted via LLDP. Multiple addresses + can be defined. Only addresses connected to the system will be transmitted. +``` + +```{eval-rst} +.. cfgcmd:: set service lldp interface <interface> + + Enable transmission of LLDP information on given `<interface>`. You can also + say ``all`` here so LLDP is turned on on every interface. +``` + +```{eval-rst} +.. cfgcmd:: set service lldp interface <interface> disable + + Disable transmit of LLDP frames on given `<interface>`. Useful to exclude + certain interfaces from LLDP when ``all`` have been enabled. +``` + +```{eval-rst} +.. cfgcmd:: set service lldp snmp + + Enable SNMP queries of the LLDP database +``` + +```{eval-rst} +.. cfgcmd:: set service lldp legacy-protocols <cdp|edp|fdp|sonmp> + + Enable given legacy protocol on this LLDP instance. Legacy protocols include: + + * ``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 +``` + +## Operation + +```{eval-rst} +.. opcmd:: show lldp neighbors + + Displays information about all neighbors discovered via LLDP. + + .. 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 + --------- ----- ----- --- -------- ------- + BR2.vyos.net eth0 LLDP R VyOS 1.2.4 eth1 + BR3.vyos.net eth0 LLDP RB VyOS 1.2.4 eth2 + SW1.vyos.net eth0 LLDP B Cisco IOS Software GigabitEthernet0/6 +``` + +```{eval-rst} +.. opcmd:: show lldp neighbors detail + + Get detailed information about LLDP neighbors. + + .. code-block:: none + + vyos@vyos:~$ show lldp neighbors detail + ------------------------------------------------------------------------------- + LLDP neighbors: + ------------------------------------------------------------------------------- + Interface: eth0, via: LLDP, RID: 28, Time: 0 day, 00:24:33 + Chassis: + ChassisID: mac 00:53:00:01:02:c9 + SysName: BR2.vyos.net + SysDescr: VyOS 1.3-rolling-201912230217 + MgmtIP: 192.0.2.1 + MgmtIP: 2001:db8::ffff + Capability: Bridge, on + Capability: Router, on + Capability: Wlan, off + Capability: Station, off + Port: + PortID: mac 00:53:00:01:02:c9 + PortDescr: eth0 + TTL: 120 + PMD autoneg: supported: no, enabled: no + MAU oper type: 10GigBaseCX4 - X copper over 8 pair 100-Ohm balanced cable + VLAN: 201 eth0.201 + VLAN: 205 eth0.205 + LLDP-MED: + Device Type: Network Connectivity Device + Capability: Capabilities, yes + Capability: Policy, yes + Capability: Location, yes + Capability: MDI/PSE, yes + Capability: MDI/PD, yes + Capability: Inventory, yes + Inventory: + Hardware Revision: None + Software Revision: 4.19.89-amd64-vyos + Firmware Revision: 6.00 + Serial Number: VMware-42 1d 83 b9 fe c1 bd b2-7 + Manufacturer: VMware, Inc. + Model: VMware Virtual Platform + Asset ID: No Asset Tag + ------------------------------------------------------------------------------- +``` + +```{eval-rst} +.. opcmd:: show lldp neighbors interface <interface> + + Show LLDP neighbors connected via interface `<interface>`. +``` + +```{eval-rst} +.. opcmd:: show log lldp + + Used for troubleshooting. +``` diff --git a/docs/configuration/service/md-mdns.md b/docs/configuration/service/md-mdns.md new file mode 100644 index 00000000..6ff1804b --- /dev/null +++ b/docs/configuration/service/md-mdns.md @@ -0,0 +1,138 @@ +# mDNS Repeater + +Starting with VyOS 1.2 a {abbr}`mDNS (Multicast DNS)` repeater functionality is +provided. Additional information can be obtained from +<https://en.wikipedia.org/wiki/Multicast_DNS>. + +Multicast DNS uses the reserved address `224.0.0.251`, which is +`"administratively scoped"` and does not leave the subnet. mDNS repeater +retransmits mDNS packets from one interface to other interfaces. This enables +support for devices using mDNS discovery (like network printers, Apple Airplay, +Chromecast, various IP based home-automation devices etc) across multiple VLANs. + +Since the mDNS protocol sends the {abbr}`AA(Authoritative Answer)` records in +the packet itself, the repeater does not need to forge the source address. +Instead, the source address is of the interface that repeats the packet. + +:::{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! +::: + +## Configuration + +```{eval-rst} +.. cfgcmd:: set service mdns repeater interface <interface> + + To enable mDNS repeater you need to configure at least two interfaces so that + all incoming mDNS packets from one interface configured here can be + re-broadcasted to any other interface(s) configured under this section. +``` + +```{eval-rst} +.. cfgcmd:: set service mdns repeater disable + + mDNS repeater can be temporarily disabled without deleting the service using +``` + +```{eval-rst} +.. cfgcmd:: set service mdns repeater ip-version <ipv4 | ipv6 | both> + + mDNS repeater can be enabled either on IPv4 socket or on IPv6 socket or both + to re-broadcast. By default, mDNS repeater will listen on both IPv4 and IPv6. +``` + +```{eval-rst} +.. cfgcmd:: set service mdns repeater allow-service <service> + + mDNS repeater can be configured to re-broadcast only specific services. By + default, all services are re-broadcasted. +``` + +```{eval-rst} +.. cfgcmd:: set service mdns repeater browse-domain <domain> + + Allow listing additional custom domains to be browsed (in addition to the + default ``local``) so that they can be reflected. +``` + +```{eval-rst} +.. cfgcmd:: set service mdns repeater cache-entries <entries> + + Specify how many resource records are cached per interface. Bigger values + allow mDNS work correctly in large LANs but also increase memory consumption. + + Defaults to: 4096 +``` + +## Firewall recommendations + +Unlike typical routed traffic, mDNS packets relayed between interfaces do not +traverse the FORWARD hook chain in the firewall. Instead, they are processed +through the following hooks: + +> - **INPUT**: For packets received by the local system +> - **OUTPUT**: For packets sent from the local system + +To control or allow mDNS packet forwarding via the relay, you must define +appropriate rules in the INPUT and OUTPUT directions. Rules in the FORWARD +direction will have no effect on mDNS relay traffic. + +```none +set firewall ipv4 input filter rule 10 action 'accept' +set firewall ipv4 input filter rule 10 destination address '224.0.0.251' +set firewall ipv4 input filter rule 10 destination port '5353' +set firewall ipv4 input filter rule 10 protocol 'udp' +set firewall ipv4 output filter rule 10 action 'accept' +set firewall ipv4 output filter rule 10 destination address '224.0.0.251' +set firewall ipv4 output filter rule 10 destination port '5353' +set firewall ipv4 output filter rule 10 protocol 'udp' +``` + +## Example + +To listen on both `eth0` and `eth1` mDNS packets and also repeat packets +received on `eth0` to `eth1` (and vice-versa) use the following commands: + +```none +set service mdns repeater interface 'eth0' +set service mdns repeater interface 'eth1' +``` + +To allow only specific services, for example `_airplay._tcp` or `_ipp._tcp`, +(instead of all services) to be re-broadcasted, use the following command: + +```none +set service mdns repeater allow-service '_airplay._tcp' +set service mdns repeater allow-service '_ipp._tcp' +``` + +To allow listing additional custom domain, for example +`openthread.thread.home.arpa`, so that it can reflected in addition to the +default `local`, use the following command: + +```none +set service mdns repeater browse-domain 'openthread.thread.home.arpa' +``` + +## Operation + +```{eval-rst} +.. opcmd:: restart mdns repeater + + Restart mDNS repeater service. +``` + +```{eval-rst} +.. opcmd:: show log mdns repeater + + Show logs for mDNS repeater service. +``` + +```{eval-rst} +.. opcmd:: monitor log mdns repeater + + Follow the logs for mDNS repeater service. +``` + +[multicast dns]: https://en.wikipedia.org/wiki/Multicast_DNS diff --git a/docs/configuration/service/md-monitoring.md b/docs/configuration/service/md-monitoring.md new file mode 100644 index 00000000..0e5d92f9 --- /dev/null +++ b/docs/configuration/service/md-monitoring.md @@ -0,0 +1,191 @@ +# Monitoring + +## Azure-data-explorer + +Telegraf output plugin [azure-data-explorer] + +```{eval-rst} +.. cfgcmd:: set service monitoring telegraf azure-data-explorer authentication client-id <client-id> + + Authentication application client-id. +``` + +```{eval-rst} +.. cfgcmd:: set service monitoring telegraf azure-data-explorer authentication client-secret <client-secret> + + Authentication application client-secret. +``` + +```{eval-rst} +.. cfgcmd:: set service monitoring telegraf azure-data-explorer authentication tenant-id <tenant-id> + + Authentication application tenant-id +``` + +```{eval-rst} +.. cfgcmd:: set service monitoring telegraf azure-data-explorer database <name> + + Remote database name. +``` + +```{eval-rst} +.. cfgcmd:: set service monitoring telegraf azure-data-explorer group-metrics <single-table | table-per-metric> + + Type of metrics grouping when push to Azure Data Explorer. The default is + ``table-per-metric``. +``` + +```{eval-rst} +.. cfgcmd:: set service monitoring telegraf azure-data-explorer table <name> + + Name of the single table Only if set group-metrics single-table. +``` + +```{eval-rst} +.. cfgcmd:: set service monitoring telegraf azure-data-explorer url <url> + + Remote URL. +``` + +## Prometheus-client + +Telegraf output plugin [prometheus-client] + +```{eval-rst} +.. cfgcmd:: set service monitoring telegraf prometheus-client + + Output plugin Prometheus client +``` + +```{eval-rst} +.. cfgcmd:: set service monitoring telegraf prometheus-client allow-from <prefix> + + Networks allowed to query this server +``` + +```{eval-rst} +.. cfgcmd:: set service monitoring telegraf prometheus-client authentication username <username> + + HTTP basic authentication username +``` + +```{eval-rst} +.. cfgcmd:: set service monitoring telegraf prometheus-client authentication password <password> + + HTTP basic authentication username +``` + +```{eval-rst} +.. cfgcmd:: set service monitoring telegraf prometheus-client listen-address <address> + + Local IP addresses to listen on +``` + +```{eval-rst} +.. cfgcmd:: set service monitoring telegraf prometheus-client metric-version <1 | 2> + + Metris version, the default is ``2`` +``` + +```{eval-rst} +.. cfgcmd:: set service monitoring telegraf prometheus-client port <port> + + Port number used by connection, default is ``9273`` +``` + +Example: + +```none +set service monitoring telegraf prometheus-client +``` + +```none +vyos@r14:~$ curl --silent localhost:9273/metrics | egrep -v "#" | grep cpu_usage_system +cpu_usage_system{cpu="cpu-total",host="r14"} 0.20040080160320556 +cpu_usage_system{cpu="cpu0",host="r14"} 0.17182130584191915 +cpu_usage_system{cpu="cpu1",host="r14"} 0.22896393817971655 +``` + +## Splunk + +Telegraf output plugin [splunk]. HTTP Event Collector. + +```{eval-rst} +.. cfgcmd:: set service monitoring telegraf splunk authentication insecure + + Use TLS but skip host validation +``` + +```{eval-rst} +.. cfgcmd:: set service monitoring telegraf splunk authentication token <token> + + Authorization token +``` + +```{eval-rst} +.. cfgcmd:: set service monitoring telegraf splunk authentication url <url> + + Remote URL to Splunk collector +``` + +Example: + +```none +set service monitoring telegraf splunk authentication insecure +set service monitoring telegraf splunk authentication token 'xxxxf5b8-xxxx-452a-xxxx-43828911xxxx' +set service monitoring telegraf splunk url 'https://192.0.2.10:8088/services/collector' +``` + +## Telegraf + +Monitoring functionality with `telegraf` and `InfluxDB 2` is provided. +Telegraf is the open source server agent to help you collect metrics, events +and logs from your routers. + +```{eval-rst} +.. cfgcmd:: set service monitoring telegraf influxdb authentication organization <organization> + + Authentication organization name +``` + +```{eval-rst} +.. cfgcmd:: set service monitoring telegraf influxdb authentication token <token> + + Authentication token +``` + +```{eval-rst} +.. cfgcmd:: set service monitoring telegraf bucket <bucket> + + Remote ``InfluxDB`` bucket name +``` + +```{eval-rst} +.. cfgcmd:: set service monitoring telegraf influxdb port <port> + + Remote port +``` + +```{eval-rst} +.. cfgcmd:: set service monitoring telegraf influxdb url <url> + + Remote URL + +``` + +## Example + +An example of a configuration that sends `telegraf` metrics to remote +`InfluxDB 2` + +```none +set service monitoring telegraf influxdb authentication organization 'vyos' +set service monitoring telegraf influxdb authentication token 'ZAml9Uy5wrhA...==' +set service monitoring telegraf influxdb bucket 'bucket_vyos' +set service monitoring telegraf influxdb port '8086' +set service monitoring telegraf influxdb url 'http://r1.influxdb2.local' +``` + +[azure-data-explorer]: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/azure_data_explorer +[prometheus-client]: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/prometheus_client +[splunk]: https://www.splunk.com/en_us/blog/it/splunk-metrics-via-telegraf.html diff --git a/docs/configuration/service/md-ntp.md b/docs/configuration/service/md-ntp.md new file mode 100644 index 00000000..e0f6b3ab --- /dev/null +++ b/docs/configuration/service/md-ntp.md @@ -0,0 +1,124 @@ +(ntp)= + +# NTP + +{abbr}`NTP (Network Time Protocol`) is a networking protocol for clock +synchronization between computer systems over packet-switched, variable-latency +data networks. In operation since before 1985, NTP is one of the oldest Internet +protocols in current use. + +NTP is intended to synchronize all participating computers to within a few +milliseconds of {abbr}`UTC (Coordinated Universal Time)`. It uses the +intersection algorithm, a modified version of Marzullo's algorithm, to select +accurate time servers and is designed to mitigate the effects of variable +network latency. NTP can usually maintain time to within tens of milliseconds +over the public Internet, and can achieve better than one millisecond accuracy +in local area networks under ideal conditions. Asymmetric routes and network +congestion can cause errors of 100 ms or more. + +The protocol is usually described in terms of a client-server model, but can as +easily be used in peer-to-peer relationships where both peers consider the other +to be a potential time source. Implementations send and receive timestamps using +{abbr}`UDP (User Datagram Protocol)` on port number 123. + +NTP supplies a warning of any impending leap second adjustment, but no +information about local time zones or daylight saving time is transmitted. + +The current protocol is version 4 (NTPv4), which is a proposed standard as +documented in {rfc}`5905`. It is backward compatible with version 3, specified +in {rfc}`1305`. + +:::{note} +VyOS 1.4 uses chrony instead of ntpd (see {vytask}`T3008`) which will +no longer accept anonymous NTP requests as in VyOS 1.3. All configurations +will be migrated to keep the anonymous functionality. For new setups if you +have clients using your VyOS installation as NTP server, you must specify +the `allow-client` directive. +::: + +## Configuration + +```{eval-rst} +.. cfgcmd:: set service ntp server <address> + + Configure one or more servers for synchronisation. Server name can be either + an IP address or {abbr}`FQDN (Fully Qualified Domain Name)`. + + There are 3 default NTP server set. You are able to change them. + + * ``time1.vyos.net`` + * ``time2.vyos.net`` + * ``time3.vyos.net`` +``` + +```{eval-rst} +.. cfgcmd:: set service ntp server <address> <noselect | nts | pool | prefer> + + Configure one or more attributes to the given NTP server. + + * ``noselect`` marks the server as unused, except for display purposes. The + server is discarded by the selection algorithm. + + * ``nts`` enables Network Time Security (NTS) for the server as specified + in {rfc}`8915` + + * ``pool`` mobilizes persistent client mode association with a number of + remote servers. + + * ``prefer`` marks the server as preferred. All other things being equal, + this host will be chosen for synchronization among a set of correctly + operating hosts. +``` + +```{eval-rst} +.. cfgcmd:: set service ntp listen-address <address> + + NTP process will only listen on the specified IP address. You must specify + the `<address>` and optionally the permitted clients. Multiple listen + addresses for same IP family is no longer supported. Only one IPv4 and one + IPv6 address can be configured, using separate commands for each. +``` + +```{eval-rst} +.. cfgcmd:: set service ntp allow-client address <address> + + List of networks or client addresses permitted to contact this NTP server. + + Multiple networks/client IP addresses can be configured. +``` + +```{eval-rst} +.. cfgcmd:: set service ntp vrf <name> + + Specify name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance. +``` + +```{eval-rst} +.. cfgcmd:: set service ntp leap-second [ignore|smear|system|timezone] + + Define how to handle leap-seconds. + + * `ignore`: No correction is applied to the clock for the leap second. The + clock will be corrected later in normal operation when new measurements are + made and the estimated offset includes the one second error. + + * `smear`: When smearing a leap second, the leap status is suppressed on the + server and the served time is corrected slowly by slewing instead of + stepping. The clients do not need any special configuration as they do not + know there is any leap second and they follow the server time which + eventually brings them back to UTC. Care must be taken to ensure they use + only NTP servers which smear the leap second in exactly the same way for + synchronisation. + + * `system`: When inserting a leap second, the kernel steps the system clock + backwards by one second when the clock gets to 00:00:00 UTC. When deleting + a leap second, it steps forward by one second when the clock gets to + 23:59:59 UTC. + + * `timezone`: This directive specifies a timezone in the system timezone + database which chronyd can use to determine when will the next leap second + occur and what is the current offset between TAI and UTC. It will + periodically check if 23:59:59 and 23:59:60 are valid times in the + timezone. This normally works with the right/UTC timezone which is the + default +``` diff --git a/docs/configuration/service/md-pppoe-server.md b/docs/configuration/service/md-pppoe-server.md new file mode 100644 index 00000000..d0c72f00 --- /dev/null +++ b/docs/configuration/service/md-pppoe-server.md @@ -0,0 +1,789 @@ +--- +lastproofread: '2022-09-17' +--- + +(pppoe-server)= + +# 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. +::: + +## Configuring PPPoE Server + +```none +set service pppoe-server access-concentrator PPPoE-Server +set service pppoe-server authentication mode local +set service pppoe-server authentication local-users username test password 'test' +set service pppoe-server client-ip-pool PPPOE-POOL range 192.168.255.2-192.168.255.254 +set service pppoe-server default-pool 'PPPOE-POOL' +set service pppoe-server gateway-address 192.168.255.1 +set service pppoe-server interface eth0 +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server access-concentrator <name> + + Use this command to set a name for this PPPoE-server access + concentrator. +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server authentication mode <local | radius> + + Set authentication backend. The configured authentication backend is used + for all queries. + + * **radius**: All authentication queries are handled by a configured RADIUS + server. + * **local**: All authentication queries are handled locally. + * **noauth**: Authentication disabled. +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server authentication local-users username + <name> password <password> + + Create `<user>` for local authentication on this system. The users password + will be set to `<pass>`. +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server client-ip-pool <POOL-NAME> + range <x.x.x.x-x.x.x.x | x.x.x.x/x> + + Use this command to define the first IP address of a pool of + addresses to be given to pppoe clients. If notation ``x.x.x.x-x.x.x.x``, + it must be within a /24 subnet. If notation ``x.x.x.x/x`` is + used there is possibility to set host/netmask. +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server default-pool <POOL-NAME> + + Use this command to define default address pool name. +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server interface <interface> + + Use this command to define the interface the PPPoE server will use to + listen for PPPoE clients. +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server gateway-address <address> + + Specifies single `<gateway>` IP address to be used as local address of PPP + interfaces. + +``` + +## Configuring RADIUS authentication + +To enable RADIUS based authentication, the authentication mode needs to be +changed within the configuration. Previous settings like the local users, still +exists within the configuration, however they are not used if the mode has been +changed from local to radius. Once changed back to local, it will use all local +accounts again. + +```none +set service pppoe-server authentication mode radius +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server authentication radius + server <server> key <secret> + + Configure RADIUS `<server>` and its required shared `<secret>` for + communicating with the RADIUS server. +``` + +Since the RADIUS server would be a single point of failure, multiple RADIUS +servers can be setup and will be used subsequentially. +For example: + +```none +set service pppoe-server authentication radius server 10.0.0.1 key 'foo' +set service pppoe-server authentication radius server 10.0.0.2 key 'foo' +``` + +:::{note} +Some RADIUS severs use an access control list which allows or denies +queries, make sure to add your VyOS router to the allowed client list. +::: + +### RADIUS source address + +If you are using OSPF as IGP, always the closest interface connected to 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. + +```{eval-rst} +.. cfgcmd:: set service pppoe-server authentication radius + source-address <address> + + Source IPv4 address used in all RADIUS server queires. +``` + +:::{note} +The `source-address` must be configured on one of VyOS interface. +Best practice would be a loopback or dummy interface. +::: + +### RADIUS advanced options + +```{eval-rst} +.. cfgcmd:: set service pppoe-server authentication radius + server <server> port <port> + + Configure RADIUS `<server>` and its required port for authentication requests. +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server authentication radius + server <server> fail-time <time> + + Mark RADIUS server as offline for this given `<time>` in seconds. +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server authentication radius + server <server> disable + + Temporary disable this RADIUS server. +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server authentication radius + acct-timeout <timeout> + + Timeout to wait reply for Interim-Update packets. (default 3 seconds) +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server authentication radius + dynamic-author server <address> + + Specifies IP address for Dynamic Authorization Extension server (DM/CoA) +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server authentication radius + dynamic-author port <port> + + Port for Dynamic Authorization Extension server (DM/CoA) +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server authentication radius dynamic-author + key <secret> + + Secret for Dynamic Authorization Extension server (DM/CoA) +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server authentication radius + max-try <number> + + Maximum number of tries to send Access-Request/Accounting-Request queries +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server authentication radius + timeout <timeout> + + Timeout to wait response from server (seconds) +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server authentication radius + nas-identifier <identifier> + + Value to send to RADIUS server in NAS-Identifier attribute and to be matched + in DM/CoA requests. +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server authentication radius + nas-ip-address <address> + + Value to send to RADIUS server in NAS-IP-Address attribute and to be matched + in DM/CoA requests. Also DM/CoA server will bind to that address. +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server authentication radius + source-address <address> + + Source IPv4 address used in all RADIUS server queires. +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server authentication radius + rate-limit attribute <attribute> + + Specifies which RADIUS server attribute contains the rate limit information. + The default attribute is ``Filter-Id``. +``` + +:::{note} +If you set a custom RADIUS attribute you must define it on both +dictionaries at RADIUS server and client. +::: + +```{eval-rst} +.. cfgcmd:: set service pppoe-server authentication radius + rate-limit enable + + Enables bandwidth shaping via RADIUS. +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server authentication radius + rate-limit vendor + + Specifies the vendor dictionary, dictionary needs to be in + /usr/share/accel-ppp/radius. +``` + +Received RADIUS attributes have a higher priority than parameters defined within +the CLI configuration, refer to the explanation below. + +### Allocation clients ip addresses by RADIUS + +If the RADIUS server sends the attribute `Framed-IP-Address` then this IP +address will be allocated to the client and the option `default-pool` +within the CLI config is being ignored. + +If the RADIUS server sends the attribute `Framed-Pool`, IP address will +be allocated from a predefined IP pool whose name equals the attribute value. + +If the RADIUS server sends the attribute `Stateful-IPv6-Address-Pool`, +IPv6 address will be allocated from a predefined IPv6 pool `prefix` +whose name equals the attribute value. + +If the RADIUS server sends the attribute `Delegated-IPv6-Prefix-Pool`, +IPv6 delegation pefix will be allocated from a predefined IPv6 pool `delegate` +whose name equals the attribute value. + +:::{note} +`Stateful-IPv6-Address-Pool` and `Delegated-IPv6-Prefix-Pool` +are defined in RFC6911. If they are not defined in your RADIUS server, +add new [dictionary]. +::: + +User interface can be put to VRF context via RADIUS Access-Accept packet, +or change it via RADIUS CoA. `Accel-VRF-Name` is used from these purposes. +It is custom [ACCEL-PPP attribute]. Define it in your RADIUS server. + +### Renaming clients interfaces by RADIUS + +If the RADIUS server uses the attribute `NAS-Port-Id`, ppp tunnels will be +renamed. + +:::{note} +The value of the attribute `NAS-Port-Id` must be less than 16 +characters, otherwise the interface won't be renamed. +::: + +## Automatic VLAN Creation + +```{eval-rst} +.. cfgcmd:: set service pppoe-server interface <interface> vlan <id | range> + + VLAN's can be created by Accel-ppp on the fly via the use of a Kernel module + named ``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. + + When configured, PPPoE will create the necessary VLANs when required. Once + the user session has been cancelled and the VLAN is not needed anymore, VyOS + will remove it again. +``` + +```none +set service pppoe-server interface eth3 vlan 100 +set service pppoe-server interface eth3 vlan 200 +set service pppoe-server interface eth3 vlan 500-1000 +set service pppoe-server interface eth3 vlan 2000-3000 +``` + +## Bandwidth Shaping + +Bandwidth rate limits can be set for local users or RADIUS based +attributes. + +### For Local Users + +```{eval-rst} +.. cfgcmd:: set service pppoe-server authentication local-users username + <user> rate-limit download <bandwidth> + + Download bandwidth limit in kbit/s for `<user>`. +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server authentication local-users username + <user> rate-limit upload <bandwidth> + + Upload bandwidth limit in kbit/s for `<user>`. + +``` + +```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 IP-POOL range '10.1.1.100/24' +set service pppoe-server default-pool 'IP-POOL' +set service pppoe-server name-server '10.100.100.1' +set service pppoe-server name-server '10.100.200.1' +set service pppoe-server interface 'eth1' +set service pppoe-server gateway-address '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`. + +```none +show pppoe-server sessions +ifname | username | ip | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes +-------+----------+------------+-------------------+-------------+--------+----------+----------+---------- +ppp0 | foo | 10.1.1.100 | 00:53:00:ba:db:15 | 20480/10240 | active | 00:00:11 | 214 B | 76 B +``` + +### For RADIUS users + +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. + +```{eval-rst} +.. cfgcmd:: set service pppoe-server authentication radius rate-limit enable + + Use this command to enable bandwidth shaping via RADIUS. +``` + +Other attributes can be used, but they have to be in one of the +dictionaries in */usr/share/accel-ppp/radius*. + +## Load Balancing + +```{eval-rst} +.. cfgcmd:: set service pppoe-server pado-delay <number-of-ms> + sessions <number-of-sessions> + + Use this command to enable the delay of PADO (PPPoE Active Discovery + Offer) packets, which can be used as a session balancing mechanism + with other PPPoE servers. +``` + +```none +set service pppoe-server pado-delay 50 sessions '500' +set service pppoe-server pado-delay 100 sessions '1000' +set service pppoe-server pado-delay 300 sessions '3000' +``` + +In the example above, the first 499 sessions connect without delay. PADO +packets will be delayed 50 ms for connection from 500 to 999, this trick +allows other PPPoE servers send PADO faster and clients will connect to +other servers. Last command says that this PPPoE server can serve only +3000 clients. + +## IPv6 + +```{eval-rst} +.. cfgcmd:: set service pppoe-server ppp-options + ipv6 <require | prefer | allow | deny> + + Specifies IPv6 negotiation preference. + + * **require** - Require IPv6 negotiation + * **prefer** - Ask client for IPv6 negotiation, do not fail if it rejects + * **allow** - Negotiate IPv6 only if client requests + * **deny** - Do not negotiate IPv6 (default value) +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server client-ipv6-pool <IPv6-POOL-NAME> + prefix <address> mask <number-of-bits> + + Use this comand to set the IPv6 address pool from which an PPPoE client + will get an IPv6 prefix of your defined length (mask) to terminate the + PPPoE endpoint at their side. The mask length can be set from 48 to 128 + bit long, the default value is 64. +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server client-ipv6-pool <IPv6-POOL-NAME> + delegate <address> delegation-prefix <number-of-bits> + + Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on + PPPoE. You will have to set your IPv6 pool and the length of the + delegation prefix. From the defined IPv6 pool you will be handing out + networks of the defined length (delegation-prefix). The length of the + delegation prefix can be set from 32 to 64 bit long. +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server default-ipv6-pool <IPv6-POOL-NAME> + + Use this command to define default IPv6 address pool name. +``` + +```none +set service pppoe-server ppp-options ipv6 allow +set service pppoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' +set service pppoe-server client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' +set service pppoe-server default-ipv6-pool IPv6-POOL +``` + +### IPv6 Advanced Options + +```{eval-rst} +.. cfgcmd:: set service pppoe-server ppp-options ipv6-accept-peer-interface-id + + Accept peer interface identifier. By default is not defined. +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server ppp-options ipv6-interface-id + <random | x:x:x:x> + + Specifies fixed or random interface identifier for IPv6. + By default is fixed. + + * **random** - Random interface identifier for IPv6 + * **x:x:x:x** - Specify interface identifier for IPv6 +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server ppp-options ipv6-interface-id + <random | x:x:x:x> + + Specifies peer interface identifier for IPv6. By default is fixed. + + * **random** - Random interface identifier for IPv6 + * **x:x:x:x** - Specify interface identifier for IPv6 + * **ipv4-addr** - Calculate interface identifier from IPv4 address. + * **calling-sid** - Calculate interface identifier from calling-station-id. +``` + +## Scripting + +```{eval-rst} +.. cfgcmd:: set service pppoe-server extended-scripts on-change <path_to_script> + + Script to run when session interface changed by RADIUS CoA handling +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server extended-scripts on-down <path_to_script> + + Script to run when session interface going to terminate +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server extended-scripts on-pre-up <path_to_script> + + Script to run before session interface comes up +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server extended-scripts on-up <path_to_script> + + Script to run when session interface is completely configured and started +``` + +## Advanced Options + +### Authentication Advanced Options + +```{eval-rst} +.. cfgcmd:: set service pppoe-server authentication local-users + username <user> disable + + Disable `<user>` account. +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server authentication local-users + username <user> static-ip <address> + + Assign static IP address to `<user>` account. +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server authentication protocols + <pap | chap | mschap | mschap-v2> + + Require the peer to authenticate itself using one of the following protocols: + pap, chap, mschap, mschap-v2. +``` + +### Client IP Pool Advanced Options + +```{eval-rst} +.. cfgcmd:: set service pppoe-server client-ip-pool <POOL-NAME> + next-pool <NEXT-POOL-NAME> + + Use this command to define the next address pool name. +``` + +### PPP Advanced Options + +```{eval-rst} +.. cfgcmd:: set service pppoe-server ppp-options disable-ccp + + Disable Compression Control Protocol (CCP). + CCP is enabled by default. +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server ppp-options interface-cache <number> + + Specifies number of interfaces to keep in cache. It means that don’t + destroy interface after corresponding session is destroyed, instead + place it to cache and use it later for new sessions repeatedly. + This should reduce kernel-level interface creation/deletion rate lack. + Default value is **0**. +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server ppp-options ipv4 + <require | prefer | allow | deny> + + Specifies IPv4 negotiation preference. + + * **require** - Require IPv4 negotiation + * **prefer** - Ask client for IPv4 negotiation, do not fail if it rejects + * **allow** - Negotiate IPv4 only if client requests (Default value) + * **deny** - Do not negotiate IPv4 +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server ppp-options lcp-echo-failure <number> + + Defines the maximum `<number>` of unanswered echo requests. Upon reaching the + value `<number>`, the session will be reset. Default value is **3**. +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server ppp-options lcp-echo-interval <interval> + + If this option is specified and is greater than 0, then the PPP module will + send LCP pings of the echo request every `<interval>` seconds. + Default value is **30**. +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server ppp-options lcp-echo-timeout + + Specifies timeout in seconds to wait for any peer activity. If this option + specified it turns on adaptive lcp echo functionality and "lcp-echo-failure" + is not used. Default value is **0**. +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server ppp-options min-mtu <number> + + Defines minimum acceptable MTU. If client will try to negotiate less then + specified MTU then it will be NAKed or disconnected if rejects greater MTU. + Default value is **100**. +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server ppp-options mppe <require | prefer | deny> + + Specifies {abbr}`MPPE (Microsoft Point-to-Point Encryption)` negotiation + preference. + + * **require** - ask client for mppe, if it rejects drop connection + * **prefer** - ask client for mppe, if it rejects don't fail. (Default value) + * **deny** - deny mppe + + Default behavior - don't ask client for mppe, but allow it if client wants. + Please note that RADIUS may override this option by MS-MPPE-Encryption-Policy + attribute. +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server ppp-options mru <number> + + Defines preferred MRU. By default is not defined. +``` + +### Global Advanced options + +```{eval-rst} +.. cfgcmd:: set service pppoe-server description <description> + + Set description. +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server limits burst <value> + + Burst count +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server limits connection-limit <value> + + Acceptable rate of connections (e.g. 1/min, 60/sec) +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server limits timeout <value> + + Timeout in seconds +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server mtu + + Maximum Transmission Unit (MTU) (default: **1492**) +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server max-concurrent-sessions + + Maximum number of concurrent session start attempts +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server name-server <address> + + Connected client should use `<address>` as their DNS server. This + command accepts both IPv4 and IPv6 addresses. Up to two nameservers + can be configured for IPv4, up to three for IPv6. +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server service-name <names> + + Specifies Service-Name to respond. If absent any Service-Name is + acceptable and client’s Service-Name will be sent back. Also possible + set multiple service-names: `sn1,sn2,sn3` +``` + +Per default the user session is being replaced if a second +authentication request succeeds. Such session requests can be either +denied or allowed entirely, which would allow multiple sessions for a +user in the latter case. If it is denied, the second session is being +rejected even if the authentication succeeds, the user has to terminate +its first session and can then authentication again. + +```{eval-rst} +.. cfgcmd:: set service pppoe-server session-control + + * **disable**: Disables session control. + * **deny**: Deny second session authorization. + * **replace**: Terminate first session when second is authorized **(default)** +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server shaper fwmark <1-2147483647> + + Match firewall mark value +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server snmp master-agent + + Enable SNMP +``` + +```{eval-rst} +.. cfgcmd:: set service pppoe-server wins-server <address> + + Windows Internet Name Service (WINS) servers propagated to client +``` + +## Monitoring + +```{eval-rst} +.. opcmd:: show pppoe-server sessions + + Use this command to locally check the active sessions in the PPPoE + server. + +``` + +```none +show pppoe-server sessions +ifname | username | ip | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes +-------+----------+------------+-------------------+-------------+--------+----------+----------+---------- +ppp0 | foo | 10.1.1.100 | 00:53:00:ba:db:15 | 20480/10240 | active | 00:00:11 | 214 B | 76 B +``` + +## Examples + +### IPv4 + +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. + +```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 IP-POOL range '10.1.1.100-10.1.1.111' +set service pppoe-server default-pool 'IP-POOL' +set service pppoe-server interface eth1 +set service pppoe-server gateway-address '10.1.1.2' +set service pppoe-server name-server '10.100.100.1' +set service pppoe-server name-server '10.100.200.1' +``` + +### Dual-Stack IPv4/IPv6 provisioning with Prefix Delegation + +The example below covers a dual-stack configuration. + +```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 IP-POOL range '192.168.0.1/24' +set service pppoe-server default-pool 'IP-POOL' +set service pppoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' +set service pppoe-server client-ipv6-pool IPV6-POOL prefix '2001:db8:8002::/48' mask '64' +set service pppoe-server default-ipv6-pool IPv6-POOL +set service pppoe-server ppp-options ipv6 allow +set service pppoe-server name-server '10.1.1.1' +set service pppoe-server name-server '2001:db8:4860::8888' +set service pppoe-server interface 'eth2' +set service pppoe-server gateway-address '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. + +```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 | 00:53:00:12:42:eb | | active | 00:00:49 | 875 B | 2.1 KiB +``` + +```{include} /_include/common-references.txt +``` + +[accel-ppp attribute]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel +[dictionary]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911 diff --git a/docs/configuration/service/md-router-advert.md b/docs/configuration/service/md-router-advert.md new file mode 100644 index 00000000..73a9718a --- /dev/null +++ b/docs/configuration/service/md-router-advert.md @@ -0,0 +1,125 @@ +(router-advert)= + +# Router Advertisements + +{abbr}`RAs (Router advertisements)` are described in {rfc}`4861#section-4.6.2`. +They are part of what is known as {abbr}`SLAAC (Stateless Address +Autoconfiguration)`. + +Supported interface types: + +> - bonding +> - bridge +> - ethernet +> - geneve +> - l2tpv3 +> - openvpn +> - pseudo-ethernet +> - tunnel +> - vxlan +> - wireguard +> - wireless +> - wwan + +## Configuration + +```{eval-rst} +.. cfgcmd:: set service router-advert interface <interface> ... +``` + + +```{csv-table} +:header: '"Field", "VyOS Option", "Description"' +:widths: 10, 10, 20 + +"Cur Hop Limit", "hop-limit", "Hop count field of the outgoing RA packets" +"""Managed address configuration"" flag", "managed-flag", "Tell hosts to use the administered stateful protocol (i.e. DHCP) for autoconfiguration" +"""Other configuration"" flag", "other-config-flag", "Tell hosts to use the administered (stateful) protocol (i.e. DHCP) for autoconfiguration of other (non-address) information" +"MTU","link-mtu","Link MTU value placed in RAs, exluded in RAs if unset" +"Router Lifetime","default-lifetime","Lifetime associated with the default router in units of seconds" +"Reachable Time","reachable-time","Time, in milliseconds, that a node assumes a neighbor is reachable after having received a reachability confirmation" +"Retransmit Timer","retrans-timer","Time in milliseconds between retransmitted Neighbor Solicitation messages" +"Default Router Preference","default-preference","Preference associated with the default router" +"Interval", "interval", "Min and max intervals between unsolicited multicast RAs" +"DNSSL", "dnssl", "DNS search list to advertise" +"Name Server", "name-server", "Advertise DNS server per https://tools.ietf.org/html/rfc6106" +``` + + +### Advertising a Prefix + +```{eval-rst} +.. cfgcmd:: set service router-advert interface <interface> prefix <prefix/mask> + + .. note:: You can also opt for using `::/64` as prefix for your {abbr}`RAs (Router + Advertisements)`. This will take the IPv6 GUA prefix assigned to the interface, + which comes in handy when using DHCPv6-PD. +``` + + +```{csv-table} +:header: '"VyOS Field", "Description"' +:widths: 10,30 + +"decrement-lifetime", "Lifetime is decremented by the number of seconds since the last RA - use in conjunction with a DHCPv6-PD prefix" +"deprecate-prefix", "Upon shutdown, this option will deprecate the prefix by announcing it in the shutdown RA" +"no-autonomous-flag","Prefix can not be used for stateless address auto-configuration" +"no-on-link-flag","Prefix can not be used for on-link determination" +"preferred-lifetime","Time in seconds that the prefix will remain preferred (default 4 hours)" +"valid-lifetime","Time in seconds that the prefix will remain valid (default: 30 days)" +``` + + +### Advertising a NAT64 Prefix + +```{eval-rst} +.. cfgcmd:: set service router-advert interface <interface> nat64prefix <prefix/mask> + + Enable PREF64 option as outlined in {rfc}`8781`. + + NAT64 prefix mask must be one of: /32, /40, /48, /56, /64 or 96. + + .. note:: The well known NAT64 prefix is ``64:ff9b::/96`` +``` + + +```{csv-table} +:header: '"VyOS Field", "Description"' +:widths: 10,30 + +"valid-lifetime","Time in seconds that the prefix will remain valid (default: 65528 seconds)" +``` + + +### Disabling Advertisements + +To disable advertisements without deleting the configuration: + +```{eval-rst} +.. cfgcmd:: set service router-advert interface <interface> no-send-advert + + If set, the router will no longer send periodic router advertisements and + will not respond to router solicitations. +``` + +```{eval-rst} +.. cfgcmd:: set service router-advert interface <interface> no-send-interval + + Advertisement Interval Option (specified by Mobile IPv6) is always included in + Router Advertisements unless this option is set. +``` + +## Example + +Your LAN connected on eth0 uses prefix `2001:db8:beef:2::/64` with the router +beeing `2001:db8:beef:2::1` + +```none +set interfaces ethernet eth0 address 2001:db8:beef:2::1/64 + +set service router-advert interface eth0 default-preference 'high' +set service router-advert interface eth0 name-server '2001:db8::1' +set service router-advert interface eth0 name-server '2001:db8::2' +set service router-advert interface eth0 other-config-flag +set service router-advert interface eth0 prefix 2001:db8:beef:2::/64 +``` diff --git a/docs/configuration/service/md-salt-minion.md b/docs/configuration/service/md-salt-minion.md new file mode 100644 index 00000000..8490783f --- /dev/null +++ b/docs/configuration/service/md-salt-minion.md @@ -0,0 +1,53 @@ +(saltminion)= + +# Salt-Minion + +[SaltStack] is Python-based, open-source +software for event-driven IT automation, remote task execution, and +configuration management. Supporting the "infrastructure as code" +approach to data center system and network deployment and management, +configuration automation, SecOps orchestration, vulnerability remediation, +and hybrid cloud control. + +## Requirements + +To use the Salt-Minion, a running Salt-Master is required. You can find more +in the [Salt Poject Documentaion](https://docs.saltproject.io/en/latest/contents.html) + +## Configuration + +```{eval-rst} +.. cfgcmd:: set service salt-minion hash <type> + + The hash type used when discovering file on master server (default: sha256) +``` + +```{eval-rst} +.. cfgcmd:: set service salt-minion id <id> + + Explicitly declare ID for this minion to use (default: hostname) +``` + +```{eval-rst} +.. cfgcmd:: set service salt-minion interval <1-1440> + + Interval in minutes between updates (default: 60) +``` + +```{eval-rst} +.. cfgcmd:: set service salt-minion master <hostname | IP> + + The hostname or IP address of the master +``` + +```{eval-rst} +.. cfgcmd:: set service salt-minion master-key <key> + + URL with signature of master for auth reply verification + +``` + +Please take a look in the Automation section to find some usefull +Examples. + +[saltstack]: https://saltproject.io/ diff --git a/docs/configuration/service/md-snmp.md b/docs/configuration/service/md-snmp.md new file mode 100644 index 00000000..c4976318 --- /dev/null +++ b/docs/configuration/service/md-snmp.md @@ -0,0 +1,259 @@ +(snmp)= + +# SNMP + +{abbr}`SNMP (Simple Network Management Protocol)` 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 +:alt: Principle of SNMP Communication +:scale: 20 % + +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 + +```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 security approach in SNMPv3 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. + +(snmp-v3-example)= + +#### Example + +- Let SNMP daemon listen only on IP address 192.0.2.1 +- Configure new SNMP user named "vyos" with password "vyos12345678" +- New user will use SHA/AES for authentication and privacy + +```none +set service snmp listen-address 192.0.2.1 +set service snmp location 'VyOS Datacenter' +set service snmp v3 engineid '000000000000000000000002' +set service snmp v3 group default mode 'ro' +set service snmp v3 group default view 'default' +set service snmp v3 user vyos auth plaintext-password 'vyos12345678' +set service snmp v3 user vyos auth type 'sha' +set service snmp v3 user vyos group 'default' +set service snmp v3 user vyos privacy plaintext-password 'vyos12345678' +set service snmp v3 user vyos privacy type 'aes' +set service snmp v3 view default oid 1 +``` + +After commit the plaintext passwords will be hashed and stored in your +configuration. The resulting CLI config will look like: + +```none +vyos@vyos# show service snmp + listen-address 192.0.2.1 { + } + location "VyOS Datacenter" + v3 { + engineid 000000000000000000000002 + group default { + mode ro + view default + } + user vyos { + auth { + encrypted-password 4e52fe55fd011c9c51ae2c65f4b78ca93dcafdfe + type sha + } + group default + privacy { + encrypted-password 4e52fe55fd011c9c51ae2c65f4b78ca93dcafdfe + type aes + } + } + view default { + oid 1 { + } + } + } +``` + +You can test the SNMPv3 functionality from any linux based system, just run the +following command: `snmpwalk -v 3 -u vyos -a SHA -A vyos12345678 -x AES +-X vyos12345678 -l authPriv 192.0.2.1 .1` + +## VyOS MIBs + +All SNMP MIBs are located in each image of VyOS here: `/usr/share/snmp/mibs/` + +You are be able to download the files using SCP, once the SSH service +has been activated like so + +```none +scp -r vyos@your_router:/usr/share/snmp/mibs /your_folder/mibs +``` + +## 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 extensioncommands`. 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. + +```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. + + +```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: + +```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> +``` + + +[mib]: https://en.wikipedia.org/wiki/Management_information_base +[snmpv2]: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_2 +[snmpv3]: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_3 diff --git a/docs/configuration/service/md-ssh.md b/docs/configuration/service/md-ssh.md new file mode 100644 index 00000000..c038e27d --- /dev/null +++ b/docs/configuration/service/md-ssh.md @@ -0,0 +1,304 @@ +(ssh)= + +# SSH + +{abbr}`SSH (Secure Shell)` is a cryptographic network protocol for operating +network services securely over an unsecured network. 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. + +:::{note} +VyOS 1.1 supported login as user `root`. This has been removed due +to tighter security in VyOS 1.2. +::: + +```{eval-rst} +.. seealso:: SSH {ref}`ssh_key_based_authentication` +``` + +## Configuration + +```{eval-rst} +.. cfgcmd:: set service ssh port <port> + + Enabling SSH only requires you to specify the port ``<port>`` you want SSH to + listen on. By default, SSH runs on port 22. +``` + +```{eval-rst} +.. cfgcmd:: set service ssh listen-address <address> + + Specify IPv4/IPv6 listen address of SSH server. Multiple addresses can be + defined. +``` + +```{eval-rst} +.. cfgcmd:: set service ssh ciphers <cipher> + + Define allowed ciphers used for the SSH connection. A number of allowed + ciphers can be specified, use multiple occurrences to allow multiple ciphers. + + List of supported ciphers: ``3des-cbc``, ``aes128-cbc``, ``aes192-cbc``, + ``aes256-cbc``, ``aes128-ctr``, ``aes192-ctr``, ``aes256-ctr``, + ``aes128-gcm@openssh.com``, ``aes256-gcm@openssh.com``, + ``chacha20-poly1305@openssh.com`` +``` + +```{eval-rst} +.. cfgcmd:: set service ssh disable-password-authentication + + Disable password based authentication. Login via SSH keys only. This hardens + security! +``` + +```{eval-rst} +.. cfgcmd:: set service ssh disable-host-validation + + Disable the host validation through reverse DNS lookups - can speedup login + time when reverse lookup is not possible. +``` + +```{eval-rst} +.. cfgcmd:: set service ssh mac <mac> + + Specifies the available {abbr}`MAC (Message Authentication Code)` algorithms. + The MAC algorithm is used in protocol version 2 for data integrity protection. + Multiple algorithms can be provided by using multiple commands, defining + one algorithm per command. + + List of 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`` +``` + +```{eval-rst} +.. cfgcmd:: set service ssh access-control <allow | deny> <group | user> <name> + + Add access-control directive to allow or deny users and groups. Directives + are processed in the following order of precedence: ``deny-users``, + ``allow-users``, ``deny-groups`` and ``allow-groups``. +``` + +```{eval-rst} +.. cfgcmd:: set service ssh client-keepalive-interval <interval> + + Specify timeout interval for keepalive message in seconds. +``` + +```{eval-rst} +.. cfgcmd:: set service ssh key-exchange <kex> + + Specify allowed {abbr}`KEX (Key Exchange)` algorithms. + + List of supported algorithms: ``diffie-hellman-group1-sha1``, + ``diffie-hellman-group14-sha1``, ``diffie-hellman-group14-sha256``, + ``diffie-hellman-group16-sha512``, ``diffie-hellman-group18-sha512``, + ``diffie-hellman-group-exchange-sha1``, + ``diffie-hellman-group-exchange-sha256``, + ``ecdh-sha2-nistp256``, ``ecdh-sha2-nistp384``, ``ecdh-sha2-nistp521``, + ``curve25519-sha256`` and ``curve25519-sha256@libssh.org``. +``` + +```{eval-rst} +.. cfgcmd:: set service ssh loglevel <quiet | fatal | error | info | verbose> + + Set the ``sshd`` log level. The default is ``info``. +``` + +```{eval-rst} +.. cfgcmd:: set service ssh vrf <name> + + Specify name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance. +``` + +## Dynamic-protection + +Protects host from brute-force attacks against +SSH. Log messages are parsed, line-by-line, for recognized patterns. If an +attack, such as several login failures within a few seconds, is detected, the +offending IP is blocked. Offenders are unblocked after a set interval. + +```{eval-rst} +.. cfgcmd:: set service ssh dynamic-protection + + Allow ``ssh`` dynamic-protection. +``` + +```{eval-rst} +.. cfgcmd:: set service ssh dynamic-protection allow-from <address | prefix> + + Whitelist of addresses and networks. Always allow inbound connections from + these systems. +``` + +```{eval-rst} +.. cfgcmd:: set service ssh dynamic-protection block-time <sec> + + Block source IP in seconds. Subsequent blocks increase by a factor of 1.5 + The default is 120. +``` + +```{eval-rst} +.. cfgcmd:: set service ssh dynamic-protection detect-time <sec> + + Remember source IP in seconds before reset their score. The default is 1800. +``` + +```{eval-rst} +.. cfgcmd:: set service ssh dynamic-protection threshold <sec> + + Block source IP when their cumulative attack score exceeds threshold. The + default is 30. +``` + +(ssh_operation)= + +## Operation + +```{eval-rst} +.. opcmd:: restart ssh + + Restart the SSH daemon process, the current session is not affected, only the + background daemon is restarted. +``` + +```{eval-rst} +.. opcmd:: generate ssh server-key + + Re-generated the public/private keyportion which SSH uses to secure + connections. + + .. note:: Already learned known_hosts files of clients need an update as the + public key will change. +``` + +```{eval-rst} +.. opcmd:: generate ssh client-key /path/to/private_key + + Re-generated a known pub/private keyfile which can be used to connect to + other services (e.g. RPKI cache). + + Example: + + .. code-block:: none + + vyos@vyos:~$ generate ssh client-key /config/auth/id_rsa_rpki + Generating public/private rsa key pair. + Your identification has been saved in /config/auth/id_rsa_rpki. + Your public key has been saved in /config/auth/id_rsa_rpki.pub. + The key fingerprint is: + SHA256:XGv2PpdOzVCzpmEzJZga8hTRq7B/ZYL3fXaioLFLS5Q vyos@vyos + The key's randomart image is: + +---[RSA 2048]----+ + | oo | + | ..o | + | . o.o.. o.| + | o+ooo o.o| + | Eo* =.o | + | o = +.o*+ | + | = o *.o.o| + | o * +.o+.+| + | =.. o=.oo| + +----[SHA256]-----+ + + Two new files ``/config/auth/id_rsa_rpki`` and + ``/config/auth/id_rsa_rpki.pub`` + will be created. +``` + +```{eval-rst} +.. opcmd:: generate public-key-command user <username> path <location> + + Generate the configuration mode commands to add a public key for + {ref}`ssh_key_based_authentication`. + ``<location>`` can be a local path or a URL pointing at a remote file. + + Supported remote protocols are FTP, FTPS, HTTP, HTTPS, SCP/SFTP and TFTP. + + Example: + + .. code-block:: none + + alyssa@vyos:~$ generate public-key-command user alyssa path sftp://example.net/home/alyssa/.ssh/id_rsa.pub + # To add this key as an embedded key, run the following commands: + configure + set system login user alyssa authentication public-keys alyssa@example.net key AAA... + set system login user alyssa authentication public-keys alyssa@example.net type ssh-rsa + commit + save + exit + + ben@vyos:~$ generate public-key-command user ben path ~/.ssh/id_rsa.pub + # To add this key as an embedded key, run the following commands: + configure + set system login user ben authentication public-keys ben@vyos key AAA... + set system login user ben authentication public-keys ben@vyos type ssh-dss + commit + save + exit +``` + +```{eval-rst} +.. opcmd:: show log ssh + + Show SSH server log. +``` + +```{eval-rst} +.. opcmd:: monitor log ssh + + Follow the SSH server log. +``` + +```{eval-rst} +.. opcmd:: show log ssh dynamic-protection + + Show SSH dynamic-protection log. +``` + +```{eval-rst} +.. opcmd:: monitor log ssh dynamic-protection + + Follow the SSH dynamic-protection log. +``` + +```{eval-rst} +.. opcmd:: show ssh dynamic-protection + + Show list of IPs currently blocked by SSH dynamic-protection. +``` + +```{eval-rst} +.. opcmd:: show ssh fingerprints + + Show SSH server public key fingerprints. +``` + +```{eval-rst} +.. opcmd:: show ssh fingerprints ascii + + Show SSH server public key fingerprints, including a visual ASCII art representation. +``` diff --git a/docs/configuration/service/md-tftp-server.md b/docs/configuration/service/md-tftp-server.md new file mode 100644 index 00000000..f4a6c34c --- /dev/null +++ b/docs/configuration/service/md-tftp-server.md @@ -0,0 +1,78 @@ +(tftp-server)= + +# TFTP Server + +{abbr}`TFTP (Trivial File Transfer Protocol)` 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. + +## Configuration + +```{cfgcmd} set service tftp-server directory \<directory\> + +Enable TFTP service by specifying the `<directory>` which will be used to serve +files. +``` + +:::{hint} +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. +::: + +```{cfgcmd} set service tftp-server listen-address \<address\> + +Configure the IPv4 or IPv6 listen address of the TFTP server. Multiple IPv4 and +IPv6 addresses can be given. There will be one TFTP server instances listening +on each IP address. +``` + +```{cfgcmd} set service tftp-server listen-address \<address\> vrf \<name\> +``` + +Additional option to run TFTP server in the {abbr}`VRF (Virtual Routing and Forwarding)` context + +:::{note} +Configuring a listen-address is essential for the service to work. +::: +```{cfgcmd} set service tftp-server allow-upload + +Optional, if you want to enable uploads, else TFTP server will act as a +read-only server. +``` + +### Example + +Provide TFTP server listening on both IPv4 and IPv6 addresses `192.0.2.1` and +`2001:db8::1` serving the content from `/config/tftpboot`. Uploading via +TFTP to this server is disabled. + +The resulting configuration will look like: + +```none +vyos@vyos# show service + tftp-server { + directory /config/tftpboot + listen-address 2001:db8::1 + listen-address 192.0.2.1 + } +``` + +### Verification + +Client: + +```none +vyos@RTR2:~$ tftp -p -l /config/config.boot -r backup 192.0.2.1 +backup1 100% |******************************| 723 0:00:00 ETA +``` + +Server: + +```none +vyos@RTR1# ls -ltr /config/tftpboot/ +total 1 +-rw-rw-rw- 1 tftp tftp 1995 May 19 16:02 backup +``` diff --git a/docs/configuration/service/md-webproxy.md b/docs/configuration/service/md-webproxy.md new file mode 100644 index 00000000..28156b2b --- /dev/null +++ b/docs/configuration/service/md-webproxy.md @@ -0,0 +1,459 @@ +(webproxy)= + +# Webproxy + +The proxy service in VyOS is based on [Squid] 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. + +URL Filtering is provided by [SquidGuard]. + +## Configuration + +```{cfgcmd} set service webproxy append-domain \<domain\> + +Use this command to specify a domain name to be appended to domain-names +within URLs that do not include a dot ``.`` the domain is appended. + +Example: to be appended is set to ``vyos.net`` and the URL received is +``www/foo.html``, the system will use the generated, final URL of +``www.vyos.net/foo.html``. + +:::{code-block} none +set service webproxy append-domain vyos.net +::: +``` + + +```{cfgcmd} set service webproxy cache-size \<size\> + +The size of the on-disk Proxy cache is user configurable. The Proxies default +cache-size is configured to 100 MB. + +Unit of this command is MB. + +:::{code-block} none +set service webproxy cache-size 1024 +::: +``` + + +```{cfgcmd} set service webproxy default-port \<port\> + +Specify the port used on which the proxy service is listening for requests. +This port is the default port used for the specified listen-address. + +Default port is 3128. + +:::{code-block} none +set service webproxy default-port 8080 +::: +``` + + +```{cfgcmd} set service webproxy domain-block \<domain\> + +Used to block specific domains by the Proxy. Specifying "vyos.net" will block +all access to vyos.net, and specifying ".xxx" will block all access to URLs +having an URL ending on .xxx. + +:::{code-block} none +set service webproxy domain-block vyos.net +::: +``` + + +```{cfgcmd} set service webproxy domain-noncache \<domain\> + +Allow access to sites in a domain without retrieving them from the Proxy +cache. Specifying "vyos.net" will allow access to vyos.net but the pages +accessed will not be cached. It useful for working around problems with +"If-Modified-Since" checking at certain sites. + +:::{code-block} none +set service webproxy domain-noncache vyos.net +::: +``` + + +```{cfgcmd} set service webproxy listen-address \<address\> + +Specifies proxy service listening address. The listen address is the IP +address on which the web proxy service listens for client requests. + +For security, the listen address should only be used on internal/trusted +networks! + +:::{code-block} none +set service webproxy listen-address 192.0.2.1 +::: +``` + + +```{cfgcmd} set service webproxy listen-address \<address\> disable-transparent + +Disables web proxy transparent mode at a listening address. + +In transparent proxy mode, all traffic arriving on port 80 and destined for +the Internet is automatically forwarded through the proxy. This allows +immediate proxy forwarding without configuring client browsers. + +Non-transparent proxying requires that the client browsers be configured with +the proxy settings before requests are redirected. The advantage of this is +that the client web browser can detect that a proxy is in use and can behave +accordingly. In addition, web-transmitted malware can sometimes be blocked by +a non-transparent web proxy, since they are not aware of the proxy settings. + +:::{code-block} none +set service webproxy listen-address 192.0.2.1 disable-transparent +::: +``` + + +```{cfgcmd} set service webproxy listen-address \<address\> port \<port\> + +Sets the listening port for a listening address. This overrides the default +port of 3128 on the specific listen address. + +:::{code-block} none +set service webproxy listen-address 192.0.2.1 port 8080 +::: +``` +```{cfgcmd} set service webproxy reply-block-mime \<mime\> + +Used to block a specific mime-type. + +:::{code-block} none +# block all PDFs +set service webproxy reply-block-mime application/pdf +::: +``` +```{cfgcmd} set service webproxy reply-body-max-size \<size\> + +Specifies the maximum size of a reply body in KB, used to limit the reply +size. + +All reply sizes are accepted by default. + +:::{code-block} none +set service webproxy reply-body-max-size 2048 +::: +``` + + +```{cfgcmd} set service webproxy safe-ports \<port\> + +Add new port to Safe-ports acl. Ports included by default in Safe-ports acl: +21, 70, 80, 210, 280, 443, 488, 591, 777, 873, 1025-65535 +``` + + +```{cfgcmd} set service webproxy ssl-safe-ports \<port\> + +Add new port to SSL-ports acl. Ports included by default in SSL-ports acl: +443 +``` + +### 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. + +```{cfgcmd} set service webproxy authentication children \<number\> + +Maximum number of authenticator processes to spawn. If you start too few +Squid will have to wait for them to process a backlog of credential +verifications, slowing it down. When password verifications are done via a +(slow) network you are likely to need lots of authenticator processes. + +This defaults to 5. + +:::{code-block} none +set service webproxy authentication children 10 +::: +``` + + +```{cfgcmd} set service webproxy authentication credentials-ttl \<time\> + +Specifies how long squid assumes an externally validated username:password +pair is valid for - in other words how often the helper program is called for +that user. Set this low to force revalidation with short lived passwords. + +Time is in minutes and defaults to 60. + +:::{code-block} none +set service webproxy authentication credentials-ttl 120 +::: +``` +```{cfgcmd} set service webproxy authentication method \<ldap\> + +Proxy authentication method, currently only LDAP is supported. + +:::{code-block} none +set service webproxy authentication method ldap +::: +``` + + +```{cfgcmd} set service webproxy authentication realm + +Specifies the protection scope (aka realm name) which is to be reported to +the client for the authentication scheme. It is commonly part of the text +the user will see when prompted for their username and password. + +:::{code-block} none +set service webproxy authentication realm "VyOS proxy auth" +::: +``` + +#### LDAP + +```{cfgcmd} set service webproxy authentication ldap base-dn \<base-dn\> + +Specifies the base DN under which the users are located. + +:::{code-block} none +set service webproxy authentication ldap base-dn DC=vyos,DC=net +::: +``` +```{cfgcmd} set service webproxy authentication ldap bind-dn \<bind-dn\> + +The DN and password to bind as while performing searches. + +:::{code-block} none +set service webproxy authentication ldap bind-dn CN=proxyuser,CN=Users,DC=vyos,DC=net +::: +``` + + +```{cfgcmd} set service webproxy authentication ldap filter-expression \<expr\> + +LDAP search filter to locate the user DN. Required if the users are in a +hierarchy below the base DN, or if the login name is not what builds the user +specific part of the users DN. + +The search filter can contain up to 15 occurrences of %s which will be +replaced by the username, as in "uid=%s" for {rfc}`2037` directories. For a +detailed description of LDAP search filter syntax see {rfc}`2254`. + +:::{code-block} none +set service webproxy authentication ldap filter-expression (cn=%s) +::: +``` + + +```{cfgcmd} set service webproxy authentication ldap password \<password\> + +The DN and password to bind as while performing searches. As the password +needs to be printed in plain text in your Squid configuration it is strongly +recommended to use a account with minimal associated privileges. This to limit +the damage in case someone could get hold of a copy of your Squid +configuration file. + +:::{code-block} none +set service webproxy authentication ldap password vyos +::: +``` + + +```{cfgcmd} set service webproxy authentication ldap persistent-connection + +Use a persistent LDAP connection. Normally the LDAP connection is only open +while validating a username to preserve resources at the LDAP server. This +option causes the LDAP connection to be kept open, allowing it to be reused +for further user validations. + +Recommended for larger installations. + +:::{code-block} none +set service webproxy authentication ldap persistent-connection +::: +``` + + +```{cfgcmd} set service webproxy authentication ldap port \<port\> + +Specify an alternate TCP port where the ldap server is listening if other than +the default LDAP port 389. + +:::{code-block} none +set service webproxy authentication ldap port 389 +::: +``` + + +```{cfgcmd} set service webproxy authentication ldap server \<server\> + +Specify the LDAP server to connect to. + +:::{code-block} none +set service webproxy authentication ldap server ldap.vyos.net +::: +``` +```{cfgcmd} set service webproxy authentication ldap use-ssl + +Use TLS encryption. + +:::{code-block} none +set service webproxy authentication ldap use-ssl +::: +``` +```{cfgcmd} set service webproxy authentication ldap username-attribute \<attr\> + +Specifies the name of the DN attribute that contains the username/login. +Combined with the base DN to construct the users DN when no search filter is +specified (filter-expression). + +Defaults to 'uid' + +:::{note} +This can only be done if all your users are located directly under +the same position in the LDAP tree and the login name is used for naming +each user object. If your LDAP tree does not match these criterias or if you +want to filter who are valid users then you need to use a search filter to +search for your users DN (filter-expression). +::: + +:::{code-block} none +set service webproxy authentication ldap username-attribute uid +::: +``` + + +```{cfgcmd} set service webproxy authentication ldap version \<2 | 3\> + +LDAP protocol version. Defaults to 3 if not specified. + +:::{code-block} none +set service webproxy authentication ldap version 2 +::: +``` + +### URL filtering + +```{include} /_include/need_improvement.txt +``` +```{cfgcmd} set service webproxy url-filtering disable + +Disables web filtering without discarding configuration. + +:::{code-block} none +set service webproxy url-filtering disable +::: +``` + +## Operation + +```{include} /_include/need_improvement.txt +``` + +### Filtering +#### Update + +If you want to use existing blacklists you have to create/download a database +first. Otherwise you will not be able to commit the config changes. + +```{opcmd} update webproxy blacklists + +Download/Update complete blacklist + +:::{code-block} none +vyos@vyos:~$ update webproxy blacklists +Warning: No url-filtering blacklist installed +Would you like to download a default blacklist? [confirm][y] +Connecting to ftp.univ-tlse1.fr (193.49.48.249:21) +blacklists.gz 100% |*************************************************************************************************************| 17.0M 0:00:00 ETA +Uncompressing blacklist... +Checking permissions... +Skip link for [ads] -> [publicite] +Building DB for [adult/domains] - 2467177 entries +Building DB for [adult/urls] - 67798 entries +Skip link for [aggressive] -> [agressif] +Building DB for [agressif/domains] - 348 entries +Building DB for [agressif/urls] - 36 entries +Building DB for [arjel/domains] - 69 entries +... +Building DB for [webmail/domains] - 374 entries +Building DB for [webmail/urls] - 9 entries +The webproxy daemon must be restarted +Would you like to restart it now? [confirm][y] +[ ok ] Restarting squid (via systemctl): squid.service. +vyos@vyos:~$ +::: +``` +```{opcmd} update webproxy blacklists category \<category\> + +Download/Update partial blacklist. + +Use tab completion to get a list of categories. +``` + +- To auto update the blacklist files + + `set service webproxy url-filtering squidguard auto-update update-hour 23` + +- To configure blocking add the following to the configuration + + `set service webproxy url-filtering squidguard block-category ads` + + `set service webproxy url-filtering squidguard block-category malware` + +#### Bypassing the webproxy + +```{include} /_include/need_improvement.txt +``` + +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: + + `set service webproxy whitelist destination-address 198.51.100.33` + + `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: + + `set service webproxy whitelist source-address 192.168.1.2` + + `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.) + +## Examples + +```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 + } +``` + +[squid]: http://www.squid-cache.org/ +[squidguard]: http://www.squidguard.org/ diff --git a/docs/configuration/system/md-acceleration.md b/docs/configuration/system/md-acceleration.md new file mode 100644 index 00000000..871129e6 --- /dev/null +++ b/docs/configuration/system/md-acceleration.md @@ -0,0 +1,158 @@ +(acceleration)= + +# Acceleration + +In this command tree, all hardware acceleration options will be handled. +At the moment only [Intel® QAT] is supported + +## Intel® QAT + +```{opcmd} show system acceleration qat + +use this command to check if there is an Intel® QAT supported Processor in your system. + +:::{code-block} none +vyos@vyos:~$ show system acceleration qat +01:00.0 Co-processor [0b40]: Intel Corporation Atom Processor C3000 Series QuickAssist Technology [8086:19e2] (rev 11) +::: + +if there is non device the command will show `` `No QAT device found` `` +``` + +```{cfgcmd} set system acceleration qat + +if there is a supported device, enable Intel® QAT +``` + + +```{opcmd} show system acceleration qat status + +Check if the Intel® QAT device is up and ready to do the job. + +:::{code-block} none +vyos@vyos:~$ show system acceleration qat status +Checking status of all devices. +There is 1 QAT acceleration device(s) in the system: +qat_dev0 - type: c3xxx, inst_id: 0, node_id: 0, bsf: 0000:01:00.0, #accel: 3 #engines: 6 state: up +::: +``` + + +### Operation Mode + +```{opcmd} show system acceleration qat device \<device\> config + +Show the full config uploaded to the QAT device. +``` + + +```{opcmd} show system acceleration qat device \<device\> flows + +Get an overview over the encryption counters. +``` + + +```{opcmd} show system acceleration qat interrupts + +Show binded qat device interrupts to certain core. +``` + + +### Example + +Let's build a simple VPN between 2 Intel® QAT ready devices. + +Side A: + +``` +set interfaces vti vti1 address '192.168.1.2/24' +set vpn ipsec authentication psk right id '10.10.10.2' +set vpn ipsec authentication psk right id '10.10.10.1' +set vpn ipsec authentication psk right secret 'Qwerty123' +set vpn ipsec esp-group MyESPGroup proposal 1 encryption 'aes256' +set vpn ipsec esp-group MyESPGroup proposal 1 hash 'sha256' +set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group '14' +set vpn ipsec ike-group MyIKEGroup proposal 1 encryption 'aes256' +set vpn ipsec ike-group MyIKEGroup proposal 1 hash 'sha256' +set vpn ipsec interface 'eth0' +set vpn ipsec site-to-site peer right authentication local-id '10.10.10.2' +set vpn ipsec site-to-site peer right authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer right authentication remote-id '10.10.10.1' +set vpn ipsec site-to-site peer right connection-type 'initiate' +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 '10.10.10.2' +set vpn ipsec site-to-site peer right remote-address '10.10.10.1' +set vpn ipsec site-to-site peer right vti bind 'vti1' +``` + +Side B: + +``` +set interfaces vti vti1 address '192.168.1.1/24' +set vpn ipsec authentication psk left id '10.10.10.2' +set vpn ipsec authentication psk left id '10.10.10.1' +set vpn ipsec authentication psk left secret 'Qwerty123' +set vpn ipsec esp-group MyESPGroup proposal 1 encryption 'aes256' +set vpn ipsec esp-group MyESPGroup proposal 1 hash 'sha256' +set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group '14' +set vpn ipsec ike-group MyIKEGroup proposal 1 encryption 'aes256' +set vpn ipsec ike-group MyIKEGroup proposal 1 hash 'sha256' +set vpn ipsec interface 'eth0' +set vpn ipsec site-to-site peer left authentication local-id '10.10.10.1' +set vpn ipsec site-to-site peer left authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer left authentication remote-id '10.10.10.2' +set vpn ipsec site-to-site peer left connection-type 'initiate' +set vpn ipsec site-to-site peer left default-esp-group 'MyESPGroup' +set vpn ipsec site-to-site peer left ike-group 'MyIKEGroup' +set vpn ipsec site-to-site peer left local-address '10.10.10.1' +set vpn ipsec site-to-site peer left remote-address '10.10.10.2' +set vpn ipsec site-to-site peer left vti bind 'vti1' +``` + +a bandwidth test over the VPN got these results: + +``` +Connecting to host 192.168.1.2, port 5201 +[ 9] local 192.168.1.1 port 51344 connected to 192.168.1.2 port 5201 +[ ID] Interval Transfer Bitrate Retr Cwnd +[ 9] 0.00-1.01 sec 32.3 MBytes 268 Mbits/sec 0 196 KBytes +[ 9] 1.01-2.03 sec 32.5 MBytes 268 Mbits/sec 0 208 KBytes +[ 9] 2.03-3.03 sec 32.5 MBytes 271 Mbits/sec 0 208 KBytes +[ 9] 3.03-4.04 sec 32.5 MBytes 272 Mbits/sec 0 208 KBytes +[ 9] 4.04-5.00 sec 31.2 MBytes 272 Mbits/sec 0 208 KBytes +[ 9] 5.00-6.01 sec 32.5 MBytes 272 Mbits/sec 0 234 KBytes +[ 9] 6.01-7.04 sec 32.5 MBytes 265 Mbits/sec 0 234 KBytes +[ 9] 7.04-8.04 sec 32.5 MBytes 272 Mbits/sec 0 234 KBytes +[ 9] 8.04-9.04 sec 32.5 MBytes 273 Mbits/sec 0 336 KBytes +[ 9] 9.04-10.00 sec 31.2 MBytes 272 Mbits/sec 0 336 KBytes +- - - - - - - - - - - - - - - - - - - - - - - - - +[ ID] Interval Transfer Bitrate Retr +[ 9] 0.00-10.00 sec 322 MBytes 270 Mbits/sec 0 sender +[ 9] 0.00-10.00 sec 322 MBytes 270 Mbits/sec receiver +``` + +with {cfgcmd}`set system acceleration qat` on both systems the bandwidth +increases. + +``` +Connecting to host 192.168.1.2, port 5201 +[ 9] local 192.168.1.1 port 51340 connected to 192.168.1.2 port 5201 +[ ID] Interval Transfer Bitrate Retr Cwnd +[ 9] 0.00-1.00 sec 97.3 MBytes 817 Mbits/sec 0 1000 KBytes +[ 9] 1.00-2.00 sec 92.5 MBytes 776 Mbits/sec 0 1.07 MBytes +[ 9] 2.00-3.00 sec 92.5 MBytes 776 Mbits/sec 0 820 KBytes +[ 9] 3.00-4.00 sec 92.5 MBytes 776 Mbits/sec 0 899 KBytes +[ 9] 4.00-5.00 sec 91.2 MBytes 765 Mbits/sec 0 972 KBytes +[ 9] 5.00-6.00 sec 92.5 MBytes 776 Mbits/sec 0 1.02 MBytes +[ 9] 6.00-7.00 sec 92.5 MBytes 776 Mbits/sec 0 1.08 MBytes +[ 9] 7.00-8.00 sec 92.5 MBytes 776 Mbits/sec 0 1.14 MBytes +[ 9] 8.00-9.00 sec 91.2 MBytes 765 Mbits/sec 0 915 KBytes +[ 9] 9.00-10.00 sec 92.5 MBytes 776 Mbits/sec 0 1000 KBytes +- - - - - - - - - - - - - - - - - - - - - - - - - +[ ID] Interval Transfer Bitrate Retr +[ 9] 0.00-10.00 sec 927 MBytes 778 Mbits/sec 0 sender +[ 9] 0.00-10.01 sec 925 MBytes 775 Mbits/sec receiver +``` + +[intel® qat]: https://www.intel.com/content/www/us/en/architecture-and-technology/intel-quick-assist-technology-overview.html diff --git a/docs/configuration/system/md-conntrack.md b/docs/configuration/system/md-conntrack.md new file mode 100644 index 00000000..b5f926b7 --- /dev/null +++ b/docs/configuration/system/md-conntrack.md @@ -0,0 +1,365 @@ +# Conntrack + +VyOS can be configured to track connections using the connection +tracking subsystem. Connection tracking becomes operational once either +stateful firewall or NAT is configured. + +## Configure + +```{eval-rst} +.. cfgcmd:: set system conntrack table-size <1-50000000> + :defaultvalue: + + The connection tracking table contains one entry for each connection being + tracked by the system. +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack expect-table-size <1-50000000> + :defaultvalue: + + The connection tracking expect table contains one entry for each expected + connection related to an existing connection. These are generally used by + “connection tracking helper” modules such as FTP. + The default size of the expect table is 2048 entries. +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack hash-size <1-50000000> + :defaultvalue: + + Set the size of the hash table. The connection tracking hash table makes + searching the connection tracking table faster. The hash table uses + “buckets” to record entries in the connection tracking table. +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack modules ftp +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack modules h323 +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack modules nfs +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack modules pptp +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack modules sip +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack modules sqlnet +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack modules tftp + + Configure the connection tracking protocol helper modules. + All modules are enable by default. + + | Use `delete system conntrack modules` to deactive all modules. + | Or, for example ftp, `delete system conntrack modules ftp`. + +``` + +### Define Conection Timeouts + +VyOS supports setting timeouts for connections according to the +connection type. You can set timeout values for generic connections, for ICMP +connections, UDP connections, or for TCP connections in a number of different +states. + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout icmp <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout other <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout tcp close <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout tcp close-wait <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout tcp established <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout tcp fin-wait <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout tcp last-ack <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout tcp syn-recv <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout tcp syn-sent <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout tcp time-wait <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout udp other <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout udp stream <1-21474836> + :defaultvalue: + + Set the timeout in secounds for a protocol or state. + +``` + +You can also define custom timeout values to apply to a specific subset of +connections, based on a packet and flow selector. To do this, you need to +create a rule defining the packet and flow selector. + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> description <test> + + Set a rule description. + +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> destination address <ip-address> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> source address <ip-address> + + set a destination and/or source address. Accepted input: + + .. code-block:: none + + <x.x.x.x> IP address to match + <x.x.x.x/x> Subnet to match + <x.x.x.x>-<x.x.x.x> + IP range to match + !<x.x.x.x> Match everything except the specified address + !<x.x.x.x/x> Match everything except the specified subnet + !<x.x.x.x>-<x.x.x.x> + Match everything except the specified range +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> destination port <value> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> source port <value> + + Set a destination and/or source port. Accepted input: + + .. code-block:: none + + <port name> Named port (any name in /etc/services, e.g., http) + <1-65535> Numbered port + <start>-<end> Numbered port range (e.g., 1001-1005) + + Multiple destination ports can be specified as a comma-separated list. + The whole list can also be "negated" using '!'. For example: + `!22,telnet,http,123,1001-1005`` + + +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol icmp <1-21474836> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol other <1-21474836> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp close <1-21474836> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp close-wait <1-21474836> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp established <1-21474836> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp fin-wait <1-21474836> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp last-ack <1-21474836> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp syn-recv <1-21474836> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp syn-sent <1-21474836> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp time-wait <1-21474836> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol udp other <1-21474836> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol udp stream <1-21474836> + + Set the timeout in secounds for a protocol or state in a custom rule. + +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack tcp half-open-connections <1-21474836> + :defaultvalue: + + Set the maximum number of TCP half-open connections. +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack tcp loose <enable | disable> + :defaultvalue: + + Policy to track previously established connections. +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack tcp max-retrans <1-2147483647> + :defaultvalue: + + Set the number of TCP maximum retransmit attempts. +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack ignore rule <1-9999> description <text> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack ignore rule <1-9999> destination address <ip-address> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack ignore rule <1-9999> destination port <port> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack ignore rule <1-9999> inbound-interface <interface> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack ignore rule <1-9999> protocol <protocol> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack ignore rule <1-9999> source address <ip-address> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack ignore rule <1-9999> source port <port> + + Customized ignore rules, based on a packet and flow selector. +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log icmp destroy +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log icmp new +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log icmp update +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log other destroy +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log other new +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log other update +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log tcp destroy +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log tcp new +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log tcp update close-wait +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log tcp update established +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log tcp update fin-wait +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log tcp update last-ack +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log tcp update syn-received +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log tcp update time-wait +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log udp destroy +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log udp new +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log udp update + + Log the connection tracking events per protocol. +``` diff --git a/docs/configuration/system/md-console.md b/docs/configuration/system/md-console.md new file mode 100644 index 00000000..adcaef8c --- /dev/null +++ b/docs/configuration/system/md-console.md @@ -0,0 +1,47 @@ +(serial-console)= + +# Serial Console + +For the average user a serial console has no advantage over a console offered +by a directly attached keyboard and screen. Serial consoles are much slower, +taking up to a second to fill a 80 column by 24 line screen. Serial consoles +generally only support non-proportional ASCII text, with limited support for +languages other than English. + +There are some scenarios where serial consoles are useful. System administration +of remote computers is usually done using {ref}`ssh`, but there are times when +access to the console is the only way to diagnose and correct software failures. +Major upgrades to the installed distribution may also require console access. + +```{eval-rst} +.. cfgcmd:: set system console device <device> + + Defines the specified device as a system console. Available console devices + can be (see completion helper): + + * ``ttySN`` - Serial device name + * ``ttyUSBX`` - USB Serial device name + * ``hvc0`` - Xen console +``` + +```{eval-rst} +.. cfgcmd:: set system console device <device> speed <speed> + + The speed (baudrate) of the console device. Supported values are: + + * ``1200`` - 1200 bps + * ``2400`` - 2400 bps + * ``4800`` - 4800 bps + * ``9600`` - 9600 bps + * ``19200`` - 19,200 bps + * ``38400`` - 38,400 bps (default for Xen console) + * ``57600`` - 57,600 bps + * ``115200`` - 115,200 bps (default for serial console) + + .. note:: If you use USB to serial converters for connecting to your VyOS + appliance please note that most of them use software emulation without flow + control. This means you should start with a common baud rate (most likely + 9600 baud) as otherwise you probably can not connect to the device using + high speed baud rates as your serial converter simply can not process this + data rate. +``` diff --git a/docs/configuration/system/md-default-route.md b/docs/configuration/system/md-default-route.md new file mode 100644 index 00000000..9f2793d1 --- /dev/null +++ b/docs/configuration/system/md-default-route.md @@ -0,0 +1,40 @@ +(default-gateway)= + +# Default Gateway/Route + +In the past (VyOS 1.1) used a gateway-address configured under the system tree +({cfgcmd}`set system gateway-address <address>`), this is no longer supported +and existing configurations are migrated to the new CLI command. + +## Configuration + +```{cfgcmd} set protocols static route 0.0.0.0/0 next-hop \<address\> + +Specify static route into the routing table sending all non local traffic +to the nexthop address \<address\>. +``` + +```{cfgcmd} delete protocols static route 0.0.0.0/0 + +Delete default route from the system. +``` + + +## Operation + +```{opcmd} show ip route 0.0.0.0 + +Show routing table entry for the 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 10, metric 0, best +Last update 09:46:30 ago +* 172.18.201.254, via eth0.201 +::: +``` + +:::{seealso} +Configuration of {ref}`routing-static` +::: diff --git a/docs/configuration/system/md-flow-accounting.md b/docs/configuration/system/md-flow-accounting.md new file mode 100644 index 00000000..9b328fff --- /dev/null +++ b/docs/configuration/system/md-flow-accounting.md @@ -0,0 +1,248 @@ +(flow-accounting)= + +# Flow Accounting + +VyOS supports flow-accounting for both IPv4 and IPv6 traffic. The system acts +as a flow exporter, and you are free to use it with any compatible collector. + +Flows can be exported via two different protocols: NetFlow (versions 5, 9 and +10/IPFIX) and sFlow. Additionally, you may save flows to an in-memory table +internally in a router. + +:::{warning} +You need to disable the in-memory table in production environments! +Using {abbr}`IMT (In-Memory Table)` may lead to heavy CPU overloading and +unstable flow-accounting behavior. +::: + +## NetFlow / IPFIX + +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: + +- **exporter**: aggregates packets into flows and exports flow records towards + one or more flow collectors +- **collector**: responsible for reception, storage and pre-processing of flow + data received from a flow exporter +- **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. + +## Configuration + +:::{warning} +Using NetFlow on routers with high traffic levels may lead to +high CPU usage and may affect the router's performance. In such cases, +consider using sFlow instead. +::: + +In order for flow accounting information to be collected and displayed for an +interface, the interface must be configured for flow accounting. + +```{eval-rst} +.. cfgcmd:: set system flow-accounting interface <interface> + + Configure and enable collection of flow information for the interface + identified by `<interface>`. + + You can configure multiple interfaces which whould participate in flow + accounting. +``` + +:::{note} +Will be recorded only packets/flows on **incoming** direction in +configured interfaces by default. +::: + +By default, recorded flows will be saved internally and can be listed with the +CLI command. You may disable using the local in-memory table with the command: + +```{eval-rst} +.. cfgcmd:: set system flow-accounting disable-imt + + If you need to sample also egress traffic, you may want to + configure egress flow-accounting: +``` + +```{eval-rst} +.. cfgcmd:: set system flow-accounting enable-egress + + Internally, in flow-accounting processes exist a buffer for data exchanging + between core process and plugins (each export target is a separated plugin). + If you have high traffic levels or noted some problems with missed records + or stopping exporting, you may try to increase a default buffer size (10 + MiB) with the next command: +``` + +```{eval-rst} +.. cfgcmd:: set system flow-accounting buffer-size <buffer size> + + In case, if you need to catch some logs from flow-accounting daemon, you may + configure logging facility: +``` + +```{eval-rst} +.. cfgcmd:: set system flow-accounting syslog-facility <facility> + + TBD +``` + +### Flow Export + +In addition to displaying flow accounting information locally, one can also +exported them to a collection server. + +#### NetFlow + +```{eval-rst} +.. cfgcmd:: set system flow-accounting netflow version <version> + + There are multiple versions available for the NetFlow data. The `<version>` + used in the exported flow data can be configured here. The following + versions are supported: + + * **5** - Most common version, but restricted to IPv4 flows only + * **9** - NetFlow version 9 (default) + * **10** - {abbr}`IPFIX (IP Flow Information Export)` as per {rfc}`3917` +``` + +```{eval-rst} +.. cfgcmd:: set system flow-accounting netflow server <address> + + Configure address of NetFlow collector. NetFlow server at `<address>` can + be both listening on an IPv4 or IPv6 address. +``` + +```{eval-rst} +.. cfgcmd:: set system flow-accounting netflow source-ip <address> + + IPv4 or IPv6 source address of NetFlow packets +``` + +```{eval-rst} +.. cfgcmd:: set system flow-accounting netflow engine-id <id> + + NetFlow engine-id which will appear in NetFlow data. The range is 0 to 255. +``` + +```{eval-rst} +.. cfgcmd:: set system flow-accounting netflow sampling-rate <rate> + + Use this command to configure the sampling rate for flow accounting. The + system samples one in every `<rate>` packets, where `<rate>` is the value + configured for the sampling-rate option. The advantage of sampling every n + packets, where n > 1, allows you to decrease the amount of processing + resources required for flow accounting. The disadvantage of not sampling + every packet is that the statistics produced are estimates of actual data + flows. + + Per default every packet is sampled (that is, the sampling rate is 1). +``` + +```{eval-rst} +.. cfgcmd:: set system flow-accounting netflow timeout expiry-interval + <interval> + + Specifies the interval at which Netflow data will be sent to a collector. As + per default, Netflow data will be sent every 60 seconds. + + You may also additionally configure timeouts for different types of + connections. +``` + +```{eval-rst} +.. cfgcmd:: set system flow-accounting netflow max-flows <n> + + If you want to change the maximum number of flows, which are tracking + simultaneously, you may do this with this command (default 8192). +``` + +#### sFlow + +:::{note} +Using `system sflow` is recommended in favor of +`system flow-accounting`. See [sflow](sflow.html) +::: + +```{eval-rst} +.. cfgcmd:: set system flow-accounting sflow server <address> + + Configure address of sFlow collector. sFlow server at `<address>` can + be an IPv4 or IPv6 address. But you cannot export to both IPv4 and + IPv6 collectors at the same time! +``` + +```{eval-rst} +.. cfgcmd:: set system flow-accounting sflow sampling-rate <rate> + + Enable sampling of packets, which will be transmitted to sFlow collectors. +``` + +```{eval-rst} +.. cfgcmd:: set system flow-accounting sflow agent-address <address> + + Configure a sFlow agent address. It can be IPv4 or IPv6 address, but you + must set the same protocol, which is used for sFlow collector addresses. By + default, using router-id from BGP or OSPF protocol, or the primary IP + address from the first interface. +``` + +### Example: + +NetFlow v5 example: + +```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 +``` + +## Operation + +Once flow accounting is configured on an interfaces it provides the ability to +display captured network traffic information for all configured interfaces. + +```{eval-rst} +.. opcmd:: show flow-accounting interface <interface> + + Show flow accounting information for given `<interface>`. + + .. code-block:: none + + vyos@vyos:~$ show flow-accounting interface eth0 + IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES + ---------- ----------------- ----------------- ------------------------ --------------- ---------- ---------- ---------- ----- --------- ------- ------- + eth0 00:53:01:a8:28:ac ff:ff:ff:ff:ff:ff 192.0.2.2 255.255.255.255 5678 5678 udp 0 1 1 178 + eth0 00:53:01:b2:2f:34 33:33:ff:00:00:00 fe80::253:01ff:feb2:2f34 ff02::1:ff00:0 0 0 ipv6-icmp 0 2 1 144 + eth0 00:53:01:1a:b4:53 33:33:ff:00:00:00 fe80::253:01ff:fe1a:b453 ff02::1:ff00:0 0 0 ipv6-icmp 0 1 1 72 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 39 1 2064 + eth0 00:53:01:c8:33:af ff:ff:ff:ff:ff:ff 192.0.2.3 255.255.255.255 5678 5678 udp 0 1 1 154 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 146 1 9444 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 27 1 4455 +``` + +```{eval-rst} +.. opcmd:: show flow-accounting interface <interface> host <address> + + Show flow accounting information for given `<interface>` for a specific host + only. + + .. code-block:: none + + vyos@vyos:~$ show flow-accounting interface eth0 host 192.0.2.14 + IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES + ---------- ----------------- ----------------- ----------- ---------- ---------- ---------- ---------- ----- --------- ------- ------- + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 197 2 12940 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 94 1 4924 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 36 1 5877 +``` diff --git a/docs/configuration/system/md-frr.md b/docs/configuration/system/md-frr.md new file mode 100644 index 00000000..37e6e502 --- /dev/null +++ b/docs/configuration/system/md-frr.md @@ -0,0 +1,44 @@ +(system-frr)= + +# FRR + +VyOS uses \[FRRouting\](<https://frrouting.org/>) as the control plane for dynamic +and static routing. The routing daemon behavior can be adjusted during runtime, +but require either a restart of the routing daemon, or a reboot of the system. + +```{eval-rst} +.. cfgcmd:: set system frr bmp + + Enable {abbr}`BMP (BGP Monitoring Protocol)` support +``` + +```{eval-rst} +.. cfgcmd:: set system frr descriptors <numer> + + This allows the operator to control the number of open file descriptors + each daemon is allowed to start with. If the operator plans to run bgp with + several thousands of peers then this is where we would modify FRR to allow + this to happen. +``` + +```{eval-rst} +.. cfgcmd:: set system frr irdp + + Enable ICMP Router Discovery Protocol support +``` + +```{eval-rst} +.. cfgcmd:: set system frr snmp <daemon> + + Enable SNMP support for an individual routing daemon. + + Supported daemons: + + - bgpd + - isisd + - ldpd + - ospf6d + - ospfd + - ripd + - zebra +``` diff --git a/docs/configuration/system/md-host-name.md b/docs/configuration/system/md-host-name.md new file mode 100644 index 00000000..81840d1f --- /dev/null +++ b/docs/configuration/system/md-host-name.md @@ -0,0 +1,70 @@ +(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 +- Aliases + +## Hostname + +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. On the other hand this will be the name which appears on +the command line prompt. + +```{cfgcmd} set system host-name \<hostname\> + + The hostname can be up to 63 characters. A hostname + must start and end with a letter or digit, and have as interior characters + only letters, digits, or a hyphen. + + The default hostname used is `vyos`. +``` + +## Domain Name + + +A domain name is the label (name) assigned to a computer network and is thus +unique. VyOS appends the domain name as a suffix to any unqualified name. For +example, if you set the domain name `example.com`, and you would ping the +unqualified name of `crux`, then VyOS qualifies the name to `crux.example.com`. + +```{cfgcmd} set system domain-name \<domain\> + +Configure system domain name. A domain name must start and end with a letter +or digit, and have as interior characters only letters, digits, or a hyphen. +``` + +## Static Hostname Mapping + + +How an IP address is assigned to an interface in {ref}`ethernet-interface`. +This section shows how to statically map an IP address to a hostname for local +(meaning on this VyOS instance) name resolution. This is the VyOS equivalent to +`/etc/hosts` file entries. + + +:::{note} +Do *not* manually edit `/etc/hosts`. This file will automatically be +regenerated on boot based on the settings in this section, which means you'll +lose all your manual edits. Instead, configure static host mappings as follows. +::: + +```{cfgcmd} set system static-host-mapping host-name \<hostname\> inet \<address\> + +Create a static hostname mapping which will always resolve the name +`<hostname>` to IP address `<address>`. +``` +```{cfgcmd} set system static-host-mapping host-name \<hostname\> alias \<alias\> + +Create named `<alias>` for the configured static mapping for `<hostname>`. +Thus the address configured as {cfgcmd}`set system static-host-mapping +host-name <hostname> inet <address>` can be reached via multiple names. + +Multiple aliases can be specified per host-name. +```
\ No newline at end of file diff --git a/docs/configuration/system/md-index.md b/docs/configuration/system/md-index.md new file mode 100644 index 00000000..624a8434 --- /dev/null +++ b/docs/configuration/system/md-index.md @@ -0,0 +1,36 @@ +# System + +```{eval-rst} +.. toctree:: + :maxdepth: 1 + :includehidden: + + acceleration + conntrack + console + flow-accounting + frr + host-name + ip + ipv6 + lcd + login + name-server + option + proxy + sflow + syslog + sysctl + task-scheduler + time-zone + updates + +``` + +```{eval-rst} +.. toctree:: + :maxdepth: 1 + :includehidden: + + default-route +``` diff --git a/docs/configuration/system/md-ip.md b/docs/configuration/system/md-ip.md new file mode 100644 index 00000000..2445509d --- /dev/null +++ b/docs/configuration/system/md-ip.md @@ -0,0 +1,110 @@ +# IP + +## System configuration commands + +```{eval-rst} +.. cfgcmd:: set system ip disable-forwarding + + Use this command to disable IPv4 forwarding on all interfaces. +``` + +```{eval-rst} +.. cfgcmd:: set system ip disable-directed-broadcast + + Use this command to disable IPv4 directed broadcast forwarding on all + interfaces. + + If set, IPv4 directed broadcast forwarding will be completely disabled + regardless of whether per-interface directed broadcast forwarding is + enabled or not. +``` + +```{eval-rst} +.. 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). +``` + +```{eval-rst} +.. cfgcmd:: set system ip multipath layer4-hashing + + Use this command to use Layer 4 information for IPv4 ECMP hashing. +``` + +### Zebra/Kernel route filtering + +Zebra supports prefix-lists and Route Mapss to match routes received from +other FRR components. The permit/deny facilities provided by these commands +can be used to filter which routes zebra will install in the kernel. + +```{eval-rst} +.. cfgcmd:: set system ip protocol <protocol> route-map <route-map> + + Apply a route-map filter to routes for the specified protocol. The following + protocols can be used: any, babel, bgp, connected, eigrp, isis, kernel, + ospf, rip, static, table + + .. note:: If you choose any as the option that will cause all protocols that + are sending routes to zebra. +``` + +### Nexthop Tracking + +Nexthop tracking resolve nexthops via the default route by default. This is enabled +by default for a traditional profile of FRR which we use. It and can be disabled if +you do not wan't to e.g. allow BGP to peer across the default route. + +```{eval-rst} +.. cfgcmd:: set system ip nht no-resolve-via-default + + Do not allow IPv4 nexthop tracking to resolve via the default route. This + parameter is configured per-VRF, so the command is also available in the VRF + subnode. +``` + +## Operational commands + +### show commands + +See below the different parameters available for the IPv4 **show** command: + +```none +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: + +```none +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/md-ipv6.md b/docs/configuration/system/md-ipv6.md new file mode 100644 index 00000000..80f0e33a --- /dev/null +++ b/docs/configuration/system/md-ipv6.md @@ -0,0 +1,235 @@ +# IPv6 + +## System configuration commands + +```{eval-rst} +.. cfgcmd:: set system ipv6 disable-forwarding + + Use this command to disable IPv6 forwarding on all interfaces. +``` + +```{eval-rst} +.. 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). +``` + +```{eval-rst} +.. cfgcmd:: set system ipv6 strict-dad + + Use this command to disable IPv6 operation on interface when + Duplicate Address Detection fails on Link-Local address. +``` + +```{eval-rst} +.. cfgcmd:: set system ipv6 multipath layer4-hashing + + Use this command to user Layer 4 information for ECMP hashing. +``` + +### Zebra/Kernel route filtering + +Zebra supports prefix-lists and Route Mapss to match routes received from +other FRR components. The permit/deny facilities provided by these commands +can be used to filter which routes zebra will install in the kernel. + +```{eval-rst} +.. cfgcmd:: set system ipv6 protocol <protocol> route-map <route-map> + + Apply a route-map filter to routes for the specified protocol. The following + protocols can be used: any, babel, bgp, connected, isis, kernel, ospfv3, + ripng, static, table + + .. note:: If you choose any as the option that will cause all protocols that + are sending routes to zebra. +``` + +### Nexthop Tracking + +Nexthop tracking resolve nexthops via the default route by default. This is enabled +by default for a traditional profile of FRR which we use. It and can be disabled if +you do not wan't to e.g. allow BGP to peer across the default route. + +```{eval-rst} +.. cfgcmd:: set system ipv6 nht no-resolve-via-default + + Do not allow IPv6 nexthop tracking to resolve via the default route. This + parameter is configured per-VRF, so the command is also available in the VRF + subnode. +``` + +## Operational commands + +### Show commands + +```{eval-rst} +.. opcmd:: show ipv6 neighbors + + Use this command to show IPv6 Neighbor Discovery Protocol information. +``` + +```{eval-rst} +.. opcmd:: show ipv6 groups + + Use this command to show IPv6 multicast group membership. +``` + +```{eval-rst} +.. opcmd:: show ipv6 forwarding + + Use this command to show IPv6 forwarding status. +``` + +```{eval-rst} +.. 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 + vrf Show IPv6 routes in VRF + +``` + +```{eval-rst} +.. 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 +``` + +```{eval-rst} +.. 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 +``` + +```{eval-rst} +.. 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 + route-map Show BGP routes matching the specified route map + summary Show summary of BGP neighbor status + +``` + +```{eval-rst} +.. 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 +``` + +```{eval-rst} +.. opcmd:: show ipv6 ripng + + Use this command to get information about the RIPNG protocol +``` + +```{eval-rst} +.. opcmd:: show ipv6 ripng status + + Use this command to show the status of the RIPNG protocol + +``` + +### Reset commands + +```{eval-rst} +.. opcmd:: reset bgp ipv6 <address> + + Use this command to clear Border Gateway Protocol statistics or + status. + +``` + +```{eval-rst} +.. opcmd:: reset ipv6 neighbors <address | interface> + + Use this command to reset IPv6 Neighbor Discovery Protocol cache for + an address or interface. +``` + +```{eval-rst} +.. 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/md-lcd.md b/docs/configuration/system/md-lcd.md new file mode 100644 index 00000000..c857ae34 --- /dev/null +++ b/docs/configuration/system/md-lcd.md @@ -0,0 +1,46 @@ +(system-display)= + +# System Display (LCD) + +The system LCD {abbr}`LCD (Liquid-crystal display)` option is for users running +VyOS on hardware that features an LCD display. This is typically a small display +built in an 19 inch rack-mountable appliance. Those displays are used to show +runtime data. + +To configure your LCD display you must first identify the used hardware, and +connectivity of the display to your system. This can be any serial port +(`ttySxx`) or serial via USB or even old parallel port interfaces. + +## Configuration + +```{eval-rst} +.. cfgcmd:: set system lcd device <device> + + This is the name of the physical interface used to connect to your LCD + display. Tab completion is supported and it will list you all available + serial interface. + + For serial via USB port information please refor to: {ref}`hardware_usb`. +``` + +```{eval-rst} +.. cfgcmd:: set system lcd model <model> + + This is the LCD model used in your system. + + At the time of this writing the following displays are supported: + + * Crystalfontz CFA-533 + + * Crystalfontz CFA-631 + + * Crystalfontz CFA-633 + + * Crystalfontz CFA-635 + + .. note:: We can't support all displays from the beginning. If your display + type is missing, please create a feature request via Phabricator_. +``` + +```{include} /_include/common-references.txt +``` diff --git a/docs/configuration/system/md-login.md b/docs/configuration/system/md-login.md new file mode 100644 index 00000000..562ed419 --- /dev/null +++ b/docs/configuration/system/md-login.md @@ -0,0 +1,474 @@ +--- +lastproofread: '2022-10-15' +--- + +(user-management)= + +# Login/User Management + +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. + +Both local administered and remote administered {abbr}`RADIUS (Remote +Authentication Dial-In User Service)` accounts are supported. + +## Local + +```{eval-rst} +.. cfgcmd:: set system login user <name> full-name "<string>" + + Create new system user with username `<name>` and real-name specified by + `<string>`. +``` + +```{eval-rst} +.. cfgcmd:: set system login user <name> authentication plaintext-password + <password> + + Specify the plaintext password user by user `<name>` on this system. The + plaintext password will be automatically transferred into a secure hashed + password and not saved anywhere in plaintext. +``` + +```{eval-rst} +.. cfgcmd:: set system login user <name> authentication encrypted-password + <password> + + Setup encrypted password for given username. This is useful for + transferring a hashed password from system to system. +``` + +```{eval-rst} +.. cfgcmd:: set system login user <name> disable + + Disable (lock) account. User will not be able to log in. +``` + +(ssh_key_based_authentication)= + +### Key Based 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`. + +Every SSH key comes in three parts: + +`ssh-rsa AAAAB3NzaC1yc2EAAAABAA...VBD5lKwEWB 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. + +```{eval-rst} +.. seealso:: SSH {ref}`ssh_operation` +``` + +```{eval-rst} +.. cfgcmd:: set system login user <username> authentication public-keys + <identifier> key <key> + + Assign the SSH public key portion `<key>` identified by per-key + `<identifier>` to the local user `<username>`. +``` + +```{eval-rst} +.. cfgcmd:: set system login user <username> authentication public-keys + <identifier> type <type> + + Every SSH public key portion referenced by `<identifier>` requires the + configuration of the `<type>` of public-key used. This type can be any of: + + * ``ecdsa-sha2-nistp256`` + * ``ecdsa-sha2-nistp384`` + * ``ecdsa-sha2-nistp521`` + * ``ssh-dss`` + * ``ssh-ed25519`` + * ``ssh-rsa`` + + .. note:: You can assign multiple keys to the same user by using a unique + identifier per SSH key. +``` + +```{eval-rst} +.. cfgcmd:: set system login user <username> authentication public-keys + <identifier> options <options> + + Set the options for this public key. See the ssh ``authorized_keys`` man + page for details of what you can specify here. To place a ``"`` + character in the options field, use ``"``, for example + ``from="10.0.0.0/24"`` to restrict where the user + may connect from when using this key. +``` + +### MFA/2FA authentication using OTP (one time passwords) + +It is possible to enhance authentication security by using the {abbr}`2FA +(Two-factor authentication)`/{abbr}`MFA (Multi-factor authentication)` feature +together with {abbr}`OTP (One-Time-Pad)` on VyOS. {abbr}`2FA (Two-factor +authentication)`/{abbr}`MFA (Multi-factor authentication)` is configured +independently per each user. If an OTP key is configured for a user, 2FA/MFA +is automatically enabled for that particular user. If a user does not have an +OTP key configured, there is no 2FA/MFA check for that user. + +```{eval-rst} +.. cfgcmd:: set system login user <username> authentication otp key <key> + + Enable OTP 2FA for user `username` with default settings, using the BASE32 + encoded 2FA/MFA key specified by `<key>`. +``` + +#### Optional/default settings + +```{eval-rst} +.. cfgcmd:: set system login user <username> authentication otp rate-limit <limit> + :defaultvalue: + + Limit logins to `<limit>` per every ``rate-time`` seconds. Rate limit + must be between 1 and 10 attempts. +``` + +```{eval-rst} +.. cfgcmd:: set system login user <username> authentication otp rate-time <seconds> + :defaultvalue: + + Limit logins to ``rate-limit`` attemps per every `<seconds>`. Rate time must + be between 15 and 600 seconds. +``` + +```{eval-rst} +.. cfgcmd:: set system login user <username> authentication otp window-size <size> + :defaultvalue: + + Set window of concurrently valid codes. + + By default, a new token is generated every 30 seconds by the mobile + application. In order to compensate for possible time-skew between + the client and the server, an extra token before and after the current + time is allowed. This allows for a time skew of up to 30 seconds + between authentication server and client. + + For example, if problems with poor time synchronization are experienced, + the window can be increased from its default size of 3 permitted codes + (one previous code, the current code, the next code) to 17 permitted codes + (the 8 previous codes, the current code, and the 8 next codes). This will + permit for a time skew of up to 4 minutes between client and server. + + The window size must be between 1 and 21. +``` + +#### OTP-key generation + +The following command can be used to generate the OTP key as well +as the CLI commands to configure them: + +```{eval-rst} +.. cfgcmd:: generate system login username <username> otp-key hotp-time + rate-limit <1-10> rate-time <15-600> window-size <1-21> +``` + +An example of key generation: + +```none +vyos@vyos:~$ generate system login username otptester otp-key hotp-time rate-limit 2 rate-time 20 window-size 5 +# You can share it with the user, he just needs to scan the QR in his OTP app +# username: otptester +# OTP KEY: J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY +# OTP URL: otpauth://totp/otptester@vyos?secret=J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY&digits=6&period=30 +█████████████████████████████████████████████ +█████████████████████████████████████████████ +████ ▄▄▄▄▄ █▀█ █▄ ▀▄▀▄█▀▄ ▀█▀ █ ▄▄▄▄▄ ████ +████ █ █ █▀▀▀█ ▄▀ █▄▀ ▀▄ ▄ ▀ ▄█ █ █ ████ +████ █▄▄▄█ █▀ █▀▀██▄▄ █ █ ██ ▀▄▀ █ █▄▄▄█ ████ +████▄▄▄▄▄▄▄█▄▀ ▀▄█ █ ▀ █ █ █ █▄█▄█▄▄▄▄▄▄▄████ +████ ▄ █▄ ▄ ▀▄▀▀▀▀▄▀▄▀▄▄▄▀▀▄▄▄ █ █▄█ █████ +████▄▄ ██▀▄▄▄▀▀█▀ ▄ ▄▄▄ ▄▀ ▀ █ ▄ ▄ ██▄█ ████ +█████▄ ██▄▄▀█▄█▄█▄ ▀█▄▀▄ ▀█▀▄ █▄▄▄ ▄ ▄████ +████▀▀▄ ▄█▀▄▀ ▄█▀█▀▄▄▄▀█▄ ██▄▄▄ ▀█ █ ████ +████ ▄▀▄█▀▄▄█▀▀▄▀▀▀▀█ ▄▀▄▀ ▄█ ▀▄ ▄ ▄▀ █▄████ +████▄ ██ ▀▄▀▀ ▄█▀ ▄ ██ ▀█▄█ ▄█ ▄ ▀▄ ▄▄ ████ +████▄█▀▀▄ ▄▄ █▄█▄█▄ █▄▄▀▄▄▀▀▄▄██▀ ▄▀▄▄ ▀▄████ +████▀▄▀ ▄ ▄▀█ ▄ ▄█▀ █ ▀▄▄ ▄█▀ ▄▄ ▀▄▄ ████ +████ ▀███▄ █▄█▄▀▀▀▀▄ ▄█▄▄▀ ▀███ ▄▄█▄▄ ▄████ +████ ███▀ ▄▄▀▀██▀ ▄▀▄█▄▄▄ ██▄▄▀▄▀ ███▄ ▄████ +████▄████▄▄▄▀▄ █▄█▄▀▄▄▄▄██▀ ▄▀ ▄ ▄▄▄ █▄▄█████ +████ ▄▄▄▄▄ █▄▄▄ ▄█▀█▀▀▀▀█▀█▀ █▄█ █▄█ ▄█ ████ +████ █ █ █ ██▄▀▀▀▀▄▄▄▀ ▄▄▄ ▀ ▄ ▄ ▄▄████ +████ █▄▄▄█ █ ▀▀█▀ ▄▄█ █▄▄██▀▀█▀ █▄▀▄██▄█ ████ +████▄▄▄▄▄▄▄█▄█▄█▄█▄▄▄▄▄█▄▄▄█▄██████▄██▄▄▄████ +█████████████████████████████████████████████ +█████████████████████████████████████████████ +# To add this OTP key to configuration, run the following commands: +set system login user otptester authentication otp key 'J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY' +set system login user otptester authentication otp rate-limit '2' +set system login user otptester authentication otp rate-time '20' +set system login user otptester authentication otp window-size '5' +``` + +#### Display OTP key for user + +To display the configured OTP user key, use the command: + +```{eval-rst} +.. cfgcmd:: sh system login authentication user <username> otp + <full|key-b32|qrcode|uri> +``` + +An example: + +```none +vyos@vyos:~$ sh system login authentication user otptester otp full +# You can share it with the user, he just needs to scan the QR in his OTP app +# username: otptester +# OTP KEY: J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY +# OTP URL: otpauth://totp/otptester@vyos?secret=J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY&digits=6&period=30 +█████████████████████████████████████████████ +█████████████████████████████████████████████ +████ ▄▄▄▄▄ █▀█ █▄ ▀▄▀▄█▀▄ ▀█▀ █ ▄▄▄▄▄ ████ +████ █ █ █▀▀▀█ ▄▀ █▄▀ ▀▄ ▄ ▀ ▄█ █ █ ████ +████ █▄▄▄█ █▀ █▀▀██▄▄ █ █ ██ ▀▄▀ █ █▄▄▄█ ████ +████▄▄▄▄▄▄▄█▄▀ ▀▄█ █ ▀ █ █ █ █▄█▄█▄▄▄▄▄▄▄████ +████ ▄ █▄ ▄ ▀▄▀▀▀▀▄▀▄▀▄▄▄▀▀▄▄▄ █ █▄█ █████ +████▄▄ ██▀▄▄▄▀▀█▀ ▄ ▄▄▄ ▄▀ ▀ █ ▄ ▄ ██▄█ ████ +█████▄ ██▄▄▀█▄█▄█▄ ▀█▄▀▄ ▀█▀▄ █▄▄▄ ▄ ▄████ +████▀▀▄ ▄█▀▄▀ ▄█▀█▀▄▄▄▀█▄ ██▄▄▄ ▀█ █ ████ +████ ▄▀▄█▀▄▄█▀▀▄▀▀▀▀█ ▄▀▄▀ ▄█ ▀▄ ▄ ▄▀ █▄████ +████▄ ██ ▀▄▀▀ ▄█▀ ▄ ██ ▀█▄█ ▄█ ▄ ▀▄ ▄▄ ████ +████▄█▀▀▄ ▄▄ █▄█▄█▄ █▄▄▀▄▄▀▀▄▄██▀ ▄▀▄▄ ▀▄████ +████▀▄▀ ▄ ▄▀█ ▄ ▄█▀ █ ▀▄▄ ▄█▀ ▄▄ ▀▄▄ ████ +████ ▀███▄ █▄█▄▀▀▀▀▄ ▄█▄▄▀ ▀███ ▄▄█▄▄ ▄████ +████ ███▀ ▄▄▀▀██▀ ▄▀▄█▄▄▄ ██▄▄▀▄▀ ███▄ ▄████ +████▄████▄▄▄▀▄ █▄█▄▀▄▄▄▄██▀ ▄▀ ▄ ▄▄▄ █▄▄█████ +████ ▄▄▄▄▄ █▄▄▄ ▄█▀█▀▀▀▀█▀█▀ █▄█ █▄█ ▄█ ████ +████ █ █ █ ██▄▀▀▀▀▄▄▄▀ ▄▄▄ ▀ ▄ ▄ ▄▄████ +████ █▄▄▄█ █ ▀▀█▀ ▄▄█ █▄▄██▀▀█▀ █▄▀▄██▄█ ████ +████▄▄▄▄▄▄▄█▄█▄█▄█▄▄▄▄▄█▄▄▄█▄██████▄██▄▄▄████ +█████████████████████████████████████████████ +█████████████████████████████████████████████ +# To add this OTP key to configuration, run the following commands: +set system login user otptester authentication otp key 'J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY' +set system login user otptester authentication otp rate-limit '2' +set system login user otptester authentication otp rate-time '20' +set system login user otptester authentication otp window-size '5' +``` + +Once a user has 2FA/OTP configured against their account, they must login +using their password with the OTP code appended to it. +For example: If the users password is vyosrocks and the OTP code is 817454 +then they would enter their password as vyosrocks817454 + +## RADIUS + +In large deployments it is not reasonable to configure each user individually +on every system. VyOS supports using {abbr}`RADIUS (Remote Authentication +Dial-In User Service)` servers as backend for user authentication. + +### Configuration + +```{eval-rst} +.. cfgcmd:: set system login radius server <address> key <secret> + + Specify the IP `<address>` of the RADIUS server user with the pre-shared-secret + given in `<secret>`. + + Multiple servers can be specified. +``` + +```{eval-rst} +.. cfgcmd:: set system login radius server <address> port <port> + + Configure the discrete port under which the RADIUS server can be reached. + + This defaults to 1812. +``` + +```{eval-rst} +.. cfgcmd:: set system login radius server <address> disable + + Temporary disable this RADIUS server. It won't be queried. +``` + +```{eval-rst} +.. cfgcmd:: set system login radius server <address> timeout <timeout> + + Setup the `<timeout>` in seconds when querying the RADIUS server. +``` + +```{eval-rst} +.. cfgcmd:: set system login radius source-address <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 unset, incoming connections to the RADIUS server will use the nearest + interface address pointing towards the server - making it error prone on + e.g. OSPF networks when a link fails and a backup route is taken. +``` + +```{eval-rst} +.. cfgcmd:: set system login radius vrf <name> + + Source all connections to the RADIUS servers from given VRF `<name>`. +``` + +:::{hint} +If you want 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. +::: + +## TACACS+ + +In addition to {abbr}`RADIUS (Remote Authentication Dial-In User Service)`, +{abbr}`TACACS (Terminal Access Controller Access Control System)` can also be +found in large deployments. +VyOS only supports `Authentication` via `TACACS+` servers but does not support `Authorization` or `Accounting` yet + +TACACS is defined in {rfc}`8907`. + +(tacacs-configuration)= + +### Configuration + +```{eval-rst} +.. cfgcmd:: set system login tacas server <address> key <secret> + + Specify the IP `<address>` of the TACACS server user with the pre-shared-secret + given in `<secret>`. + + Multiple servers can be specified. +``` + +```{eval-rst} +.. cfgcmd:: set system login tacas server <address> port <port> + + Configure the discrete port under which the TACACS server can be reached. + + This defaults to 49. +``` + +```{eval-rst} +.. cfgcmd:: set system login tacas server <address> disable + + Temporary disable this TACACS server. It won't be queried. +``` + +```{eval-rst} +.. cfgcmd:: set system login tacas server <address> timeout <timeout> + + Setup the `<timeout>` in seconds when querying the TACACS server. +``` + +```{eval-rst} +.. cfgcmd:: set system login tacas source-address <address> + + TACACS servers could be hardened by only allowing certain IP addresses to + connect. As of this the source address of each TACACS query can be + configured. + + If unset, incoming connections to the TACACS server will use the nearest + interface address pointing towards the server - making it error prone on + e.g. OSPF networks when a link fails and a backup route is taken. +``` + +```{eval-rst} +.. cfgcmd:: set system login tacas vrf <name> + + Source all connections to the TACACS servers from given VRF `<name>`. + +``` + +## Login Banner + +You are able to set post-login or pre-login banner messages to display certain +information for this system. + +```{eval-rst} +.. cfgcmd:: set system login banner pre-login <message> + + Configure `<message>` which is shown during SSH connect and before a user is + logged in. +``` + +```{eval-rst} +.. cfgcmd:: set system login banner post-login <message> + + Configure `<message>` which is shown after user has logged in to the system. +``` + +:::{note} +To create a new line in your login message you need to escape the new +line character by using `\\n`. +::: + +## Limits + +Login limits + +```{eval-rst} +.. cfgcmd:: set system login max-login-session <number> + + Set a limit on the maximum number of concurrent logged-in users on + the system. + + This option must be used with ``timeout`` option. +``` + +```{eval-rst} +.. cfgcmd:: set system login timeout <timeout> + + Configure session timeout after which the user will be logged out. +``` + +## Example + +In the following example, both `User1` and `User2` will be able to SSH into +VyOS as user `vyos` using their very own keys. `User1` is restricted to only +be able to connect from a single IP address. In addition if password base login +is wanted for the `vyos` user a 2FA/MFA keycode is required in addition to +the password. + +```none +set system login user vyos authentication public-keys 'User1' key "AAAAB3Nz...KwEW" +set system login user vyos authentication public-keys 'User1' type ssh-rsa +set system login user vyos authentication public-keys 'User1' options "from="192.168.0.100"" + +set system login user vyos authentication public-keys 'User2' key "AAAAQ39x...fbV3" +set system login user vyos authentication public-keys 'User2' type ssh-rsa + +set system login user vyos authentication otp key OHZ3OJ7U2N25BK4G7SOFFJTZDTCFUUE2 +set system login user vyos authentication plaintext-password vyos +``` + +### TACACS Example + +We use a vontainer providing the TACACS serve rin this example. + +Load the container image in op-mode. + +```none +add container image lfkeitel/tacacs_plus:latest +``` + +```none +set container network tac-test prefix '100.64.0.0/24' + +set container name tacacs1 image 'lfkeitel/tacacs_plus:latest' +set container name tacacs1 network tac-test address '100.64.0.11' + +set container name tacacs2 image 'lfkeitel/tacacs_plus:latest' +set container name tacacs2 network tac-test address '100.64.0.12' + +set system login tacacs server 100.64.0.11 key 'tac_plus_key' +set system login tacacs server 100.64.0.12 key 'tac_plus_key' + +commit +``` + +You can now SSH into your system using admin/admin as a default user supplied +from the `lfkeitel/tacacs_plus:latest` container. diff --git a/docs/configuration/system/md-name-server.md b/docs/configuration/system/md-name-server.md new file mode 100644 index 00000000..9090ba5f --- /dev/null +++ b/docs/configuration/system/md-name-server.md @@ -0,0 +1,65 @@ +(system-dns)= + +# System DNS + +:::{warning} +If you are configuring a VRF for management purposes, there is +currently no way to force system DNS traffic via a specific VRF. +::: + +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: + +```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\> + +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. +::: + +(name-server-domain-search-order-example)= + +### Example + +The system is configured to attempt domain completion in the following +order: vyos.io (first), vyos.net (second) and vyos.network (last): + +```none +set system domain-search vyos.io +set system domain-search vyos.net +set system domain-search vyos.network +``` diff --git a/docs/configuration/system/md-option.md b/docs/configuration/system/md-option.md new file mode 100644 index 00000000..7fbf5d23 --- /dev/null +++ b/docs/configuration/system/md-option.md @@ -0,0 +1,186 @@ +(system-option)= + +# Option + +This chapter describe the possibilities of advanced system behavior. + +## General + +```{eval-rst} +.. cfgcmd:: set system option ctrl-alt-delete <ignore | reboot | poweroff> + + Action which will be run once the ctrl-alt-del keystroke is received. +``` + +```{eval-rst} +.. cfgcmd:: set system option reboot-on-panic + + Automatically reboot system on kernel panic after 60 seconds. +``` + +```{eval-rst} +.. cfgcmd:: set system option startup-beep + + Play an audible beep to the system speaker when system is ready. +``` + +```{eval-rst} +.. cfgcmd:: set system option root-partition-auto-resize + + Enables the root partition auto-extension and resizes to the maximum + available space on system boot. +``` + +### Kernel + +```{eval-rst} +.. cfgcmd:: set system option kernel disable-mitigations + + Disable all optional CPU mitigations. This improves system performance, + but it may also expose users to several CPU vulnerabilities. + + This will add the following option to the Kernel commandline: + + * ``mitigations=off`` + + .. note:: Setting will only become active with the next reboot! +``` + +```{eval-rst} +.. cfgcmd:: set system option kernel disable-power-saving + + This will add the following two options to the Kernel commandline: + + * ``intel_idle.max_cstate=0`` Disable intel_idle and fall back on acpi_idle + * ``processor.max_cstate=1`` Limit processor to maximum C-state 1 + + .. note:: Setting will only become active with the next reboot! +``` + +```{eval-rst} +.. cfgcmd:: set system option kernel amd-pstate-driver <mode> + + Enables and configures p-state driver for modern AMD Ryzen and Epyc CPUs. + + The available modes are: + + * ``active`` This is the low-level firmware control mode based on the profile + set and the system governor has no effect. + * ``passive`` The driver allows the system governor to manage CPU frequency + while providing available performance states. + * ``guided`` The driver allows to set desired performance levels and the firmware + selects a performance level in this range and fitting to the current workload. + + This will add the following two options to the Kernel commandline: + + * ``initcall_blacklist=acpi_cpufreq_init`` Disable default ACPI CPU frequency scale + * ``amd_pstate={mode}`` Sets the p-state mode + + .. note:: Setting will only become active with the next reboot! + + .. seealso:: https://docs.kernel.org/admin-guide/pm/amd-pstate.html +``` + +```{eval-rst} +.. cfgcmd:: set system option kernel quiet + + Suppress most kernel messages during boot. This is useful for systems with + embedded serial console interfaces to speed up the boot process. +``` + +## HTTP client + +```{eval-rst} +.. cfgcmd:: set system option http-client source-address <address> + + Several commands utilize cURL to initiate transfers. Configure the local + source IPv4/IPv6 address used for all cURL operations. +``` + +```{eval-rst} +.. cfgcmd:: set system option http-client source-interface <interface> + + Several commands utilize curl to initiate transfers. Configure the local + source interface used for all CURL operations. +``` + +:::{note} +`source-address` and `source-interface` can not be used at the same +time. +::: + +## SSH client + +```{eval-rst} +.. cfgcmd:: set system option ssh-client source-address <address> + + Use the specified address on the local machine as the source address of the + connection. Only useful on systems with more than one address. +``` + +```{eval-rst} +.. cfgcmd:: set system option ssh-client source-interface <interface> + + Use the address of the specified interface on the local machine as the + source address of the connection. +``` + +## Keyboard Layout + +When starting a VyOS live system (the installation CD) the configured keyboard +layout defaults to US. As this might not suite everyones use case you can adjust +the used keyboard layout on the system console. + +```{eval-rst} +.. cfgcmd:: set system option keyboard-layout <us | fr | de | fi | no | dk> + + Change system keyboard layout to given language. + + Defaults to ``us``. + + .. note:: Changing the keymap only has an effect on the system console, using + SSH or Serial remote access to the device is not affected as the keyboard + layout here corresponds to your access system. +``` + +(system-options-performance)= + +## Performance + +As more and more routers run on Hypervisors, expecially with a {abbr}`NOS +(Network Operating System)` as VyOS, it makes fewer and fewer sense to use +static resource bindings like `smp-affinity` as present in VyOS 1.2 and +earlier to pin certain interrupt handlers to specific CPUs. + +We now utilize `tuned` for dynamic resource balancing based on profiles. + + +```{eval-rst} +.. seealso:: https://access.redhat.com/sites/default/files/attachments/201501-perf-brief-low-latency-tuning-rhel7-v2.1.pdf +``` + + +```{eval-rst} +.. cfgcmd:: set system option performance < throughput | latency > + + Configure one of the predefined system performance profiles. + + * ``throughput``: A server profile focused on improving network throughput. + This profile favors performance over power savings by setting + ``intel_pstate`` and ``max_perf_pct=100`` and increasing kernel network + buffer sizes. + + It enables transparent huge pages, and uses cpupower to set the performance + cpufreq governor. It also sets ``kernel.sched_min_granularity_ns`` to 10 us, + ``kernel.sched_wakeup_granularity_ns`` to 15 uss, and ``vm.dirty_ratio`` to + 40%. + + * ``latency``: A server profile focused on lowering network latency. + This profile favors performance over power savings by setting + ``intel_pstate`` and ``min_perf_pct=100``. + + It disables transparent huge pages, and automatic NUMA balancing. It also + uses cpupower to set the performance cpufreq governor, and requests a + cpu_dma_latency value of 1. It also sets busy_read and busy_poll times to + 50 us, and tcp_fastopen to 3. +``` diff --git a/docs/configuration/system/md-proxy.md b/docs/configuration/system/md-proxy.md new file mode 100644 index 00000000..3b12634b --- /dev/null +++ b/docs/configuration/system/md-proxy.md @@ -0,0 +1,27 @@ +(system-proxy)= + +# System Proxy + +Some IT environments require the use of a proxy to connect to the Internet. +Without this configuration VyOS updates could not be installed directly by +using the {opcmd}`add system image` command ({ref}`update_vyos`). + +```{cfgcmd} set system proxy url \<url\> + +Set proxy for all connections initiated by VyOS, including HTTP, HTTPS, and +FTP (anonymous ftp). +``` +```{cfgcmd} set system proxy port \<port\> + +Configure proxy port if it does not listen to the default port 80. +``` +```{cfgcmd} set system proxy username \<username\> + +Some proxies require/support the "basic" HTTP authentication scheme as per +{rfc}`7617`, thus a username can be configured. +``` +```{cfgcmd} set system proxy password \<password\> + +Some proxies require/support the "basic" HTTP authentication scheme as per +{rfc}`7617`, thus a password can be configured. +```
\ No newline at end of file diff --git a/docs/configuration/system/md-sflow.md b/docs/configuration/system/md-sflow.md new file mode 100644 index 00000000..c63699db --- /dev/null +++ b/docs/configuration/system/md-sflow.md @@ -0,0 +1,71 @@ +# sFlow + +VyOS supports sFlow accounting for both IPv4 and IPv6 traffic. The system acts as a flow exporter, and you are free to use it with any compatible collector. + +sFlow is a technology that enables monitoring of network traffic by sending sampled packets to a collector device. + +The sFlow accounting based on hsflowd <https://sflow.net/> + +## Configuration + +```{eval-rst} +.. cfgcmd:: set system sflow agent-address <address> + + Configure sFlow agent IPv4 or IPv6 address + +``` + +```{eval-rst} +.. cfgcmd:: set system sflow agent-interface <interface> + + Configure agent IP address associated with this interface. + +``` + +```{eval-rst} +.. cfgcmd:: set system sflow drop-monitor-limit <limit> + + Dropped packets reported on DROPMON Netlink channel by Linux kernel are exported via the standard sFlow v5 extension for reporting dropped packets +``` + +```{eval-rst} +.. cfgcmd:: set system sflow interface <interface> + + Configure and enable collection of flow information for the interface identified by <interface>. + + You can configure multiple interfaces which whould participate in sflow accounting. + +``` + +```{eval-rst} +.. cfgcmd:: set system sflow polling <sec> + + Configure schedule counter-polling in seconds (default: 30) +``` + +```{eval-rst} +.. cfgcmd:: set system sflow sampling-rate <rate> + + Use this command to configure the sampling rate for sFlow accounting (default: 1000) +``` + +```{eval-rst} +.. cfgcmd:: set system sflow server <address> port <port> + + Configure address of sFlow collector. sFlow server at <address> can be both listening on an IPv4 or IPv6 address. + +``` + +## Example + +```none +set system sflow agent-address '192.0.2.14' +set system sflow agent-interface 'eth0' +set system sflow drop-monitor-limit '50' +set system sflow interface 'eth0' +set system sflow interface 'eth1' +set system sflow polling '30' +set system sflow sampling-rate '1000' +set system sflow server 192.0.2.1 port '6343' +set system sflow server 203.0.113.23 port '6343' +``` diff --git a/docs/configuration/system/md-sysctl.md b/docs/configuration/system/md-sysctl.md new file mode 100644 index 00000000..b815861b --- /dev/null +++ b/docs/configuration/system/md-sysctl.md @@ -0,0 +1,12 @@ +(sysctl)= + +# Sysctl + +This chapeter describes how to configure kernel parameters at runtime. + +`sysctl` is used to modify kernel parameters at runtime. The parameters +available are those listed under /proc/sys/. + +```{eval-rst} +.. cfgcmd:: set system sysctl parameter <parameter> value <value> +``` diff --git a/docs/configuration/system/md-syslog.md b/docs/configuration/system/md-syslog.md new file mode 100644 index 00000000..b4335c22 --- /dev/null +++ b/docs/configuration/system/md-syslog.md @@ -0,0 +1,365 @@ +(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 + +```{eval-rst} +.. 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)= + +### Custom File + +```{eval-rst} +.. cfgcmd:: set system syslog file <filename> facility <keyword> level <keyword> + + Log syslog messages to file specified via `<filename>`, for an explanation on + {ref}`syslog_facilities` keywords and {ref}`syslog_severity_level` keywords + see tables below. +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. 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. + +```{eval-rst} +.. 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 an explanation on + {ref}`syslog_facilities` keywords and {ref}`syslog_severity_level` + keywords see tables below. + +``` + +```{eval-rst} +.. 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. + +``` + +```{eval-rst} +.. cfgcmd:: set system syslog vrf <name> + + Specify name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance. +``` + +#### {abbr}`TLS (Transport Layer Security)`-encrypted remote logging + +VyOS supports {abbr}`TLS (Transport Layer Security)`-encrypted remote logging +over TCP to ensure secure transmission of syslog data to remote syslog servers. + +**Prerequisites**: Before configuring {abbr}`TLS (Transport Layer +Security)`-encrypted remote logging, ensure you have: + +- A valid remote syslog server address. + +- Valid {abbr}`CA (Certificate Authority)` and client certificates uploaded + to the local {abbr}`PKI (Public Key Infrastructure)` storage. + +- The **remote syslog transport protocol** is set to **TCP**: + + ```none + set system syslog remote <address> protocol tcp + ``` + +:::{note} +{abbr}`TLS (Transport Layer Security)`-encrypted remote logging is +**not supported** over **UDP**. +::: + +```{eval-rst} +.. cfgcmd:: set system syslog remote <address> tls + + Enable TLS-encrypted remote logging. +``` + +```{eval-rst} +.. cfgcmd:: set system syslog remote <address> tls ca-certificate <ca_name> + + **Configure the** {abbr}`CA (Certificate Authority)` **certificate.** + + The syslog client uses the {abbr}`CA (Certificate Authority)` certificate to + verify the identity of the remote syslog server. + + The {abbr}`CA (Certificate Authority)` certificate is required for **all** + authentication modes except ``anon``. +``` + +```{eval-rst} +.. cfgcmd:: set system syslog remote <address> tls certificate <cert_name> + + **Configure the client certificate.** + + The remote syslog server uses the client certificate to verify the identity + of the syslog client. + + The client certificate is required if the remote syslog server enforces + client certificate verification. +``` + +```{eval-rst} +.. cfgcmd:: set system syslog remote <address> tls auth-mode <anon | fingerprint + | certvalid | name> + + **Configure the authentication mode.** + + The authentication mode defines how the syslog client verifies the syslog + server's identity. + + The following authentication modes are available: + + * ``anon`` **(default)**: Allows encrypted connections without verifying the syslog + server's identity. This mode is **not recommended**, as it is vulnerable to + {abbr}`MITM (Man-in-the-Middle)` attacks. + * ``fingerprint``: Verifies the server’s certificate fingerprint against the + value preconfigured with: + + .. code-block:: none + + set system syslog remote <address> tls permitted-peer <peer> + + * ``certvalid``: Verifies the server certificate is signed by a trusted + {abbr}`CA (Certificate Authority)`, skipping {abbr}`CN (Common Name)` check. + * ``name``: Verifies that: + + * The server’s certificate is signed by a trusted {abbr}`CA (Certificate + Authority)`. + * The {abbr}`CN (Common Name)` in the certificate matches the value + preconfigured with: + + .. code-block:: none + + set system syslog remote <address> tls permitted-peer <peer> + + This is a **recommended** secure mode for production environments. +``` + +```{eval-rst} +.. cfgcmd:: set system syslog remote <address> tls permitted-peer <peer> + + **Configure the peer certificate identifiers.** + + The certificate identifier format depends on the authentication mode: + + * ``fingerprint``: Enter the expected certificate fingerprints (SHA-1 or + SHA-256). + * ``name``: Enter the expected certificate {abbr}`CNs (Common Names)`. + + For ``anon`` and ``certvalid`` authentication modes, certificate identifiers + are not required. +``` + +#### Examples: + +```none +# Example of 'anon' authentication mode +set system syslog host 10.10.2.3 facility all level debug +set system syslog host 10.10.2.3 port 6514 +set system syslog host 10.10.2.3 protocol tcp +set system syslog host 10.10.2.3 tls auth-mode anon +# or just use 'set system syslog host 10.10.2.3 tls' + +# Example of 'certvalid' authentication mode +set system syslog host elk.example.com facility all level debug +set system syslog host elk.example.com port 6514 +set system syslog host elk.example.com protocol tcp +set system syslog host elk.example.com tls ca-certificate my-ca +set system syslog host elk.example.com tls auth-mode certvalid + +# Example of 'fingerprint' authentication mode +set system syslog host syslog.example.com facility all level debug +set system syslog host syslog.example.com port 6514 +set system syslog host syslog.example.com protocol tcp +set system syslog host syslog.example.com tls ca-certificate my-ca +set system syslog host syslog.example.com tls auth-mode fingerprint +set system syslog host syslog.example.com tls permitted-peer 'SHA1:10:C4:26:...' + +# Example of 'name' authentication mode +set system syslog host graylog.example.com facility all level debug +set system syslog host graylog.example.com port 6514 +set system syslog host graylog.example.com protocol tcp +set system syslog host graylog.example.com tls ca-certificate my-ca +set system syslog host graylog.example.com tls certificate syslog-client +set system syslog host graylog.example.com tls auth-mode name +set system syslog host graylog.example.com tls permitted-peer 'graylog.example.com' +``` + +#### Security Notes + +- Always prefer `auth-mode name` for secure deployments, as it ensures + both CA trust and server hostname validation. +- `anon` mode should only be used for testing, because it does not + authenticate the server. +- Ensure private keys are stored and managed exclusively in the + {doc}`PKI system </configuration/pki/index>`. + +### Local User Account + +```{eval-rst} +.. 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 an 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 Code | Keyword | Description | +| ------------- | -------- | ---------------------------------------- | +| | 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 + +```{eval-rst} +.. 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`. + +```{eval-rst} +.. 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. + +:::{hint} +Use `show log | strip-private` if you want to hide private data +when sharing your logs. +::: + +## Delete Logs + +```{eval-rst} +.. opcmd:: delete log file <text> +``` + +Deletes the specified user-defined file \<text> in the /var/log/user directory + +Note that deleting the log file does not stop the system from logging events. +If you use this command while the system is logging events, old log events +will be deleted, but events after the delete operation will be recorded in +the new file. To delete the file altogether, first delete logging to the +file using system syslog {ref}`custom-file` command, and then delete the file. diff --git a/docs/configuration/system/md-task-scheduler.md b/docs/configuration/system/md-task-scheduler.md new file mode 100644 index 00000000..378a648d --- /dev/null +++ b/docs/configuration/system/md-task-scheduler.md @@ -0,0 +1,48 @@ +(task-scheduler)= + +# Task Scheduler + +The task scheduler allows you to execute tasks on a given schedule. It makes +use of UNIX [cron]. + +:::{note} +All scripts excecuted this way are executed as root user - this may +be dangerous. Together with {ref}`command-scripting` this can be used for +automating (re-)configuration. +::: + +```{eval-rst} +.. cfgcmd:: set system task-scheduler task <task> interval <interval> + + Specify the time interval when `<task>` should be executed. The interval + is specified as number with one of the following suffixes: + + * ``none`` - Execution interval in minutes + * ``m`` - Execution interval in minutes + * ``h`` - Execution interval in hours + * ``d`` - Execution interval in days + + .. note:: If suffix is omitted, minutes are implied. +``` + +```{eval-rst} +.. cfgcmd:: set system task-scheduler task <task> crontab-spec <spec> + + Set execution time in common cron_ time format. A cron `<spec>` of + ``30 */6 * * *`` would execute the `<task>` at minute 30 past every 6th hour. +``` + +```{eval-rst} +.. cfgcmd:: set system task-scheduler task <task> executable path <path> + + Specify absolute `<path>` to script which will be run when `<task>` is + executed. +``` + +```{eval-rst} +.. cfgcmd:: set system task-scheduler task <task> executable arguments <args> + + Arguments which will be passed to the executable. +``` + +[cron]: https://en.wikipedia.org/wiki/Cron diff --git a/docs/configuration/system/md-time-zone.md b/docs/configuration/system/md-time-zone.md new file mode 100644 index 00000000..2279a773 --- /dev/null +++ b/docs/configuration/system/md-time-zone.md @@ -0,0 +1,17 @@ +(timezone)= + +# Time Zone + +Time Zone setting is very important as e.g all your logfile entries will be +based on the configured zone. Without proper time zone configuration it will +be very difficult to compare logfiles from different systems. + +```{cfgcmd} set system time-zone \<timezone\> + +Specify the systems \<timezone\> as the Region/Location that best defines +your location. For example, specifying US/Pacific sets the time zone to US +Pacific time. + +Command completion can be used to list available time zones. The adjustment +for daylight time will take place automatically based on the time of year. +```
\ No newline at end of file diff --git a/docs/configuration/system/md-updates.md b/docs/configuration/system/md-updates.md new file mode 100644 index 00000000..05a9d189 --- /dev/null +++ b/docs/configuration/system/md-updates.md @@ -0,0 +1,37 @@ +# Updates + +VyOS supports online checking for updates + +## Configuration + +```{eval-rst} +.. cfgcmd:: set system update-check auto-check + + Configure auto-checking for new images + +``` + +```{eval-rst} +.. cfgcmd:: set system update-check url <url> + + Configure a URL that contains information about images. + +``` + +## Example + +```none +set system update-check auto-check +set system update-check url 'https://raw.githubusercontent.com/vyos/vyos-rolling-nightly-builds/main/version.json' +``` + +Check: + +```none +vyos@r4:~$ show system updates +Current version: 1.5-rolling-202312220023 + +Update available: 1.5-rolling-202312250024 +Update URL: https://github.com/vyos/vyos-rolling-nightly-builds/releases/download/1.5-rolling-202312250024/1.5-rolling-202312250024-amd64.iso +vyos@r4:~$ +``` diff --git a/docs/configuration/trafficpolicy/md-index.md b/docs/configuration/trafficpolicy/md-index.md new file mode 100644 index 00000000..02630e8c --- /dev/null +++ b/docs/configuration/trafficpolicy/md-index.md @@ -0,0 +1,1391 @@ +(qos)= + +# Traffic Policy + +## QoS + +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. + +> ```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. + +> ```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**, + +> ```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**. + +> ```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 number of a class in a Priority Queue it does not only +identify it, it also defines its priority. +::: + +```none +set qos 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: + +```none +set qos policy shaper MY-SHAPER class 30 match HTTP +set qos 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: + +```none +set qos policy shaper MY-SHAPER class 30 match HTTP ip protocol tcp +set qos 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. + +```none +vyos@vyos# set qos policy shaper MY-SHAPER class 30 match MY-FIRST-FILTER +Possible completions: + description Description + > ether Ethernet header match + interface Interface to use + > ip Match IP protocol header + > ipv6 Match IPV6 protocol 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: + +```none +set qos 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). + +IPv6 TCP filters will only match IPv6 packets with no header +extension, see <https://en.wikipedia.org/wiki/IPv6_packet#Extension_headers> +::: + +#### Traffic Match Group + +In some case where we need to have an organization of our matching selection, +in order to be more flexible and organize with our filter definition. We can +apply traffic match groups, allowing us to create distinct filter groups within +our policy and define various parameters for each group: + +```none +set qos traffic-match-group <group_name> match <match_name> +Possible completions: + description Description + > ip Match IP protocol header + > ipv6 Match IPv6 protocol header + mark Match on mark applied by firewall + vif Virtual Local Area Network (VLAN) ID for this match +``` + +inherit matches from another group + +```none +set qos traffic-match-group <group_name> match-group <match_group_name> +``` + +A match group can contain multiple criteria and inherit them in the same policy. + +For example: + +```none +set qos traffic-match-group Mission-Critical match AF31 ip dscp 'AF31' +set qos traffic-match-group Mission-Critical match AF32 ip dscp 'AF42' +set qos traffic-match-group Mission-Critical match CS3 ip dscp 'CS3' +set qos traffic-match-group Streaming-Video match AF11 ip dscp 'AF11' +set qos traffic-match-group Streaming-Video match AF41 ip dscp 'AF41' +set qos traffic-match-group Streaming-Video match AF43 ip dscp 'AF43' +set qos policy shaper VyOS-HTB class 10 bandwidth '30%' +set qos policy shaper VyOS-HTB class 10 description 'Multimedia' +set qos policy shaper VyOS-HTB class 10 match CS4 ip dscp 'CS4' +set qos policy shaper VyOS-HTB class 10 match-group 'Streaming-Video' +set qos policy shaper VyOS-HTB class 10 priority '1' +set qos policy shaper VyOS-HTB class 10 queue-type 'fair-queue' +set qos policy shaper VyOS-HTB class 20 description 'MC' +set qos policy shaper VyOS-HTB class 20 match-group 'Mission-Critical' +set qos policy shaper VyOS-HTB class 20 priority '2' +set qos policy shaper VyOS-HTB class 20 queue-type 'fair-queue' +set qos policy shaper VyOS-HTB default bandwidth '20%' +set qos policy shaper VyOS-HTB default queue-type 'fq-codel' +``` + +In this example, we can observe that different DSCP criteria are defined based +on our QoS configuration within the same policy group. + +#### 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. + +```none +vyos@vyos# set qos policy shaper MY-SHAPER class 30 +Possible completions: + bandwidth Available bandwidth for this policy (default: auto) + burst Burst size for this class (default: 15k) + ceiling Bandwidth limit for this class + codel-quantum + Deficit in the fair queuing algorithm (default 1514) + description Description + flows Number of flows into which the incoming packets are classified(default 1024) + interval Interval used to measure the delay (default 100) ++> match Class matching rule name + priority Priority for rule evaluation + queue-limit Maximum queue size + queue-type Queue type for default traffic (default: fq-codel) + set-dscp Change the Differentiated Services (DiffServ) field in the IP header + target Acceptable minimum standing/persistent queue delay (default: 5) +``` + +For instance, with {code}`set qos 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 value | Configured value | Drop rate | Description | +> | ------------ | ---------------- | --------- | ---------------------------- | +> | 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. + +```none +set qos policy shaper FQ-SHAPER bandwidth 4gbit +set qos policy shaper FQ-SHAPER default bandwidth 100% +set qos 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.** + +```{eval-rst} +.. cfgcmd:: set qos 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. + +```{eval-rst} +.. cfgcmd:: set qos 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. + +```{eval-rst} +.. cfgcmd:: set qos 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. + +```{eval-rst} +.. cfgcmd:: set qos 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. + +```{eval-rst} +.. cfgcmd:: set qos 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. +``` + +```{eval-rst} +.. cfgcmd:: set qos 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. +``` + +```{eval-rst} +.. cfgcmd:: set qos 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). +``` + +```{eval-rst} +.. cfgcmd:: set qos 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). +``` + +```{eval-rst} +.. cfgcmd:: set qos 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. + +```none +set qos policy shaper FQ-CODEL-SHAPER bandwidth 2gbit +set qos policy shaper FQ-CODEL-SHAPER default bandwidth 100% +set qos 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. +::: + +```{eval-rst} +.. cfgcmd:: set qos 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. + +```{eval-rst} +.. cfgcmd:: set qos 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. + +``` + +```{eval-rst} +.. cfgcmd:: set qos 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). + +``` + +```{eval-rst} +.. cfgcmd:: set qos 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. + +``` + +```{eval-rst} +.. cfgcmd:: set qos 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. + +``` + +```{eval-rst} +.. cfgcmd:: set qos 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. + +```{eval-rst} +.. cfgcmd:: set qos 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. +``` + +```{eval-rst} +.. cfgcmd:: set qos 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. +``` + +```{eval-rst} +.. cfgcmd:: set qos policy network-emulator <policy-name> 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. +``` + +```{eval-rst} +.. cfgcmd:: set qos policy network-emulator <policy-name> 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. +``` + +```{eval-rst} +.. cfgcmd:: set qos policy network-emulator <policy-name> 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. +``` + +```{eval-rst} +.. cfgcmd:: set traffic-policy network-emulator <policy-name> 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. +``` + +```{eval-rst} +.. 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: + +```none +vyos@vyos# set qos policy priority-queue MY-PRIO class 3 match MY-MATCH-RULE +Possible completions: + description Description + > ether Ethernet header match + interface Interface to use + > ip Match IP protocol header + > ipv6 Match IPV6 protocol 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: + +```none +vyos@vyos# set qos policy priority-queue MY-PRIO class 3 queue-type +Possible completions: + drop-tail First-In-First-Out (FIFO) (default) + fq-codel Fair Queue Codel + fair-queue Stochastic Fair Queue (SFQ) + priority Priority queueing + random-detect + Random Early Detection (RED) +``` + +```{eval-rst} +.. cfgcmd:: set qos 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. + +```{eval-rst} +.. cfgcmd:: set qos 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. +``` + +```{eval-rst} +.. cfgcmd:: set qos 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**. +::: + +```{eval-rst} +.. cfgcmd:: set qos 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). + +``` + +```{eval-rst} +.. cfgcmd:: set qos 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. +``` + +```{eval-rst} +.. cfgcmd:: set qos 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 | + +```{eval-rst} +.. cfgcmd:: set qos 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. + +```{eval-rst} +.. cfgcmd:: set qos 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. +``` + +```{eval-rst} +.. cfgcmd:: set qos 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. + +```{eval-rst} +.. cfgcmd:: set qos 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. + +```{eval-rst} +.. cfgcmd:: set qos 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. +``` + +```{eval-rst} +.. cfgcmd:: set qos 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. + +```none +vyos@vyos# set qos policy round-robin DRR class 10 queue-type +Possible completions: + drop-tail First-In-First-Out (FIFO) (default) + fq-codel Fair Queue Codel + fair-queue Stochastic Fair Queue (SFQ) + priority Priority queueing based + random-detect + Random Early Detection (RED) +``` + +(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. + +```{eval-rst} +.. cfgcmd:: set qos 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. + +``` + +```{eval-rst} +.. cfgcmd:: set qos 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. +``` + +```{eval-rst} +.. cfgcmd:: set qos 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). +``` + +```{eval-rst} +.. cfgcmd:: set qos 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. +``` + +```{eval-rst} +.. cfgcmd:: set qos 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. + +```none +vyos@vyos# set qos policy shaper HTB class 10 queue-type +Possible completions: + fq-codel Fair Queue Codel (default) + fair-queue Stochastic Fair Queue (SFQ) + drop-tail First-In-First-Out (FIFO) + priority Priority queueing + random-detect + Random Early Detection (RED) +``` + +```none +vyos@vyos# set qos policy shaper HTB class 10 +Possible completions: + bandwidth Available bandwidth for this policy (default: auto) + burst Burst size for this class (default: 15k) + ceiling Bandwidth limit for this class + codel-quantum + Deficit in the fair queuing algorithm (default 1514) + description Description + flows Number of flows into which the incoming packets are classified (default 1024) + interval Interval used to measure the delay (default 100) ++> match Class matching rule name + priority Priority for rule evaluation + queue-limit Maximum queue size (packets) + queue-type Queue type for default traffic (default: fq-codel) + set-dscp Change the Differentiated Services (DiffServ) field in the IP header + target Acceptable minimum standing/persistent queue delay (default: 5) +``` + +:::{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. +::: + +(traffic-policy-shaper-example)= + +##### Example + +A simple example of Shaper using priorities. + +```none +set qos policy shaper MY-HTB bandwidth '50mbit' +set qos policy shaper MY-HTB class 10 bandwidth '20%' +set qos policy shaper MY-HTB class 10 match DSCP ip dscp 'EF' +set qos policy shaper MY-HTB class 10 queue-type 'fq-codel' +set qos policy shaper MY-HTB class 20 bandwidth '10%' +set qos policy shaper MY-HTB class 20 ceiling '50%' +set qos policy shaper MY-HTB class 20 match PORT666 ip destination port '666' +set qos policy shaper MY-HTB class 20 priority '3' +set qos policy shaper MY-HTB class 20 queue-type 'fair-queue' +set qos policy shaper MY-HTB class 30 bandwidth '10%' +set qos policy shaper MY-HTB class 30 ceiling '50%' +set qos policy shaper MY-HTB class 30 match ADDRESS30 ip source address '192.168.30.0/24' +set qos policy shaper MY-HTB class 30 priority '5' +set qos policy shaper MY-HTB class 30 queue-type 'fair-queue' +set qos policy shaper MY-HTB default bandwidth '10%' +set qos policy shaper MY-HTB default ceiling '100%' +set qos policy shaper MY-HTB default priority '7' +set qos policy shaper MY-HTB default queue-type 'fair-queue' +``` + +(cake)= + +#### CAKE + +**Queueing discipline:** + + Deficit mode. + +**Applies to:** + + Outbound traffic. + +[Common Applications Kept Enhanced] (CAKE) is a comprehensive queue management +system, implemented as a queue discipline (qdisc) for the Linux kernel. It is +designed to replace and improve upon the complex hierarchy of simple qdiscs +presently required to effectively tackle the bufferbloat problem at the network +edge. + +```{eval-rst} +.. cfgcmd:: set qos policy cake <text> bandwidth <value> + + Set the shaper bandwidth, either as an explicit bitrate or a percentage + of the interface bandwidth. +``` + +```{eval-rst} +.. cfgcmd:: set qos policy cake <text> description + + Set a description for the shaper. +``` + +```{eval-rst} +.. cfgcmd:: set qos policy cake <text> flow-isolation blind + + Disables flow isolation, all traffic passes through a single queue. +``` + +```{eval-rst} +.. cfgcmd:: set qos policy cake <text> flow-isolation dst-host + + Flows are defined only by destination address. +``` + +```{eval-rst} +.. cfgcmd:: set qos policy cake <text> flow-isolation dual-dst-host + + Flows are defined by the 5-tuple. Fairness is applied first over destination + addresses, then over individual flows. +``` + +```{eval-rst} +.. cfgcmd:: set qos policy cake <text> flow-isolation dual-src-host + + Flows are defined by the 5-tuple. Fairness is applied first over source + addresses, then over individual flows. +``` + +```{eval-rst} +.. cfgcmd:: set qos policy cake <text> flow-isolation flow + + Flows are defined by the entire 5-tuple (source IP address, source port, + destination IP address, destination port, transport protocol). +``` + +```{eval-rst} +.. cfgcmd:: set qos policy cake <text> flow-isolation host + + Flows are defined by source-destination host pairs. +``` + +```{eval-rst} +.. cfgcmd:: set qos policy cake <text> flow-isolation nat + + Perform NAT lookup before applying flow-isolation rules. +``` + +```{eval-rst} +.. cfgcmd:: set qos policy cake <text> flow-isolation src-host + + Flows are defined only by source address. +``` + +```{eval-rst} +.. cfgcmd:: set qos policy cake <text> flow-isolation triple-isolate + + **(Default)** Flows are defined by the 5-tuple, fairness is applied over source and + destination addresses and also over individual flows. +``` + +```{eval-rst} +.. cfgcmd:: set qos policy cake <text> rtt + + Defines the round-trip time used for active queue management (AQM) in + milliseconds. The default value is 100. + +``` + +### Applying a traffic policy + +Once a traffic-policy is created, you can apply it to an interface: + +```none +set qos interface eth0 egress WAN-OUT +``` + +You can only apply one policy per interface and direction, but you could +reuse a policy on different interfaces and directions: + +```none +set qos interface eth0 ingress WAN-IN +set qos interface eth0 egress WAN-OUT +set qos interface eth1 ingress LAN-IN +set qos interface eth1 egress LAN-OUT +set qos interface eth2 ingress LAN-IN +set qos interface eth2 egress LAN-OUT +set qos interface eth3 ingress TWO-WAY-POLICY +set qos interface eth3 egress TWO-WAY-POLICY +set qos interface eth4 ingress TWO-WAY-POLICY +set qos interface eth4 egress TWO-WAY-POLICY +``` + +(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". + +```none +set qos policy shaper MY-INGRESS-SHAPING bandwidth 1000kbit +set qos policy shaper MY-INGRESS-SHAPING default bandwidth 1000kbit +set qos policy shaper MY-INGRESS-SHAPING default queue-type fair-queue + +set qos interface ifb0 egress 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`. +::: + + + +[common applications kept enhanced]: https://www.bufferbloat.net/projects/codel/wiki/Cake/ +[hfsc]: https://en.wikipedia.org/wiki/Hierarchical_fair-service_curve +[intermediate functional block]: https://www.linuxfoundation.org/collaborate/workgroups/networking/ifb +[tc]: https://en.wikipedia.org/wiki/Tc_(Linux) +[that can give you a great deal of flexibility]: https://blog.vyos.io/using-the-policy-route-and-packet-marking-for-custom-qos-matches +[tocken bucket]: https://en.wikipedia.org/wiki/Token_bucket diff --git a/docs/configuration/vpn/ipsec/md-index.md b/docs/configuration/vpn/ipsec/md-index.md new file mode 100644 index 00000000..ff2d0c05 --- /dev/null +++ b/docs/configuration/vpn/ipsec/md-index.md @@ -0,0 +1,20 @@ +# IPsec + +```{eval-rst} +.. toctree:: + :maxdepth: 1 + :includehidden: + + ipsec_general + site2site_ipsec + troubleshooting_ipsec +``` + +pages to sort + +```{eval-rst} +.. toctree:: + :maxdepth: 1 + :includehidden: + +``` diff --git a/docs/configuration/vpn/ipsec/md-ipsec_general.md b/docs/configuration/vpn/ipsec/md-ipsec_general.md new file mode 100644 index 00000000..ff8ac76e --- /dev/null +++ b/docs/configuration/vpn/ipsec/md-ipsec_general.md @@ -0,0 +1,347 @@ +(ipsec_general)= + +# IPsec General Information + +## Information about IPsec + +IPsec is the framework used to secure data. +IPsec accomplishes these goals by providing authentication, +encryption of IP network packets, key exchange, and key management. +VyOS uses strongSwan for its IPsec implementation. + +**Authentication Header (AH)** is defined in {rfc}`4302`. It creates +a hash using the IP header and data payload, and prepends it to the +packet. This hash is used to validate that the data has not been +changed during transfer over the network. + +**Encapsulating Security Payload (ESP)** is defined in {rfc}`4303`. +It provides encryption and authentication of the data. + +There are two IPsec modes: +: **IPsec Transport Mode**: + + : In transport mode, an IPSec header (AH or ESP) is inserted + between the IP header and the upper layer protocol header. + + **IPsec Tunnel Mode:** + + : In tunnel mode, the original IP packet is encapsulated in + another IP datagram, and an IPsec header (AH or ESP) is + inserted between the outer and inner headers. + +:::{figure} /_static/images/ESP_AH.png +:alt: AH and ESP in Transport Mode and Tunnel Mode +:scale: 80 % +::: + +## IKE (Internet Key Exchange) + +The default IPsec method for secure key negotiation is the Internet Key +Exchange (IKE) protocol. IKE is designed to provide mutual authentication +of systems, as well as to establish a shared secret key to create IPsec +security associations. A security association (SA) includes all relevant +attributes of the connection, including the cryptographic algorithm used, +the IPsec mode, the encryption key, and other parameters related to the +transmission of data over the VPN connection. + +### IKEv1 + +IKEv1 is the older version and is still used today. Nowadays, most +manufacturers recommend using IKEv2 protocol. + +IKEv1 is described in the next RFCs: {rfc}`2409` (IKE), {rfc}`3407` +(IPsec DOI), {rfc}`3947` (NAT-T), {rfc}`3948` (UDP Encapsulation +of ESP Packets), {rfc}`3706` (DPD) + +IKEv1 operates in two phases to establish these IKE and IPsec SAs: +: - **Phase 1** provides mutual authentication of the IKE peers and + establishment of the session key. This phase creates an IKE SA (a + security association for IKE) using a DH exchange, cookies, and an + ID exchange. Once an IKE SA is established, all IKE communication + between the initiator and responder is protected with encryption + and an integrity check that is authenticated. The purpose of IKE + phase 1 is to facilitate a secure channel between the peers so that + phase 2 negotiations can occur securely. IKE phase 1 offers two modes: + Main and Aggressive. + + > - **Main Mode** is used for site-to-site VPN connections. + > - **Aggressive Mode** is used for remote access VPN connections. + + - **Phase 2** provides for the negotiation and establishment of the + IPsec SAs using ESP or AH to protect IP data traffic. + +### IKEv2 + +IKEv2 is described in {rfc}`7296`. The biggest difference between IKEv1 and +IKEv2 is that IKEv2 is much simpler and more reliable than IKEv1 because +fewer messages are exchanged during the establishment of the VPN and +additional security capabilities are available. + +### IKE Authentication + +VyOS supports 3 authentication methods. +: - **Pre-shared keys**: In this method, both peers of the IPsec + tunnel must have the same preshared keys. + - **Digital certificates**: PKI is used in this method. + - **RSA-keys**: If the RSA-keys method is used in your IKE policy, + you need to make sure each peer has the other peer’s public keys. + +## DPD (Dead Peer Detection) + +This is a mechanism used to detect when a VPN peer is no longer active. +This mechanism has different algorithms in IKEv1 and IKEv2 in VyOS. +DPD Requests are sent as ISAKMP R-U-THERE messages and DPD Responses +are sent as ISAKMP R-U-THERE-ACK messages. In IKEv1, DPD sends messages +every configured interval. The remote peer is considered unreachable +if no response to these packets is received within the DPD timeout. +In IKEv2, DPD sends messages every configured interval. If one request +does not receive a response, strongSwan executes its retransmission algorithm with +its timers. <https://docs.strongswan.org/docs/5.9/config/retransmission.html> + +## Configuration IKE + +### IKE (Internet Key Exchange) Attributes + +VyOS IKE group has the next options: + +```{eval-rst} +.. cfgcmd:: set vpn ipsec ike-group <name> close-action <action> + + Defines the action to take if the remote peer unexpectedly + closes a CHILD_SA: + + * **none** - Set action to none (default), + * **trap** - Installs a trap policy (IPsec policy without Security + Association) for the CHILD_SA and traffic matching these policies + will trigger acquire events that cause the daemon to establish the + required IKE/IPsec SAs. + * **start** - Tries to immediately re-create the CHILD_SA. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec ike-group <name> ikev2-reauth + + Whether rekeying of an IKE_SA should also reauthenticate + the peer. In IKEv1, reauthentication is always done. + Setting this parameter enables remote host re-authentication + during an IKE rekey. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec ike-group <name> key-exchange + + Which protocol should be used to initialize the connection + If not set both protocols are handled and connections will + use IKEv2 when initiating, but accept any protocol version + when responding: + + * **ikev1** - Use IKEv1 for Key Exchange. + * **ikev2** - Use IKEv2 for Key Exchange. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec ike-group <name> lifetime + + IKE lifetime in seconds <0-86400> (default 28800). +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec ike-group <name> mode + + IKEv1 Phase 1 Mode Selection: + + * **main** - Use Main mode for Key Exchanges in the IKEv1 Protocol + (Recommended Default). + * **aggressive** - Use Aggressive mode for Key Exchanges in the IKEv1 + protocol aggressive mode is much more insecure compared to Main mode. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec ike-group <name> proposal <number> dh-group <dh-group number> + + Diffie-Hellman algorithm group. Default value is **2**. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec ike-group <name> proposal <number> encryption <encryption> + + Encryption algorithm. Default value is **aes128**. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec ike-group <name> proposal <number> hash <hash> + + Hash algorithm. Default value is **sha1**. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec ike-group <name> proposal <number> prf <prf> + + Pseudo-random function. + +``` + +### DPD (Dead Peer Detection) Configuration + +```{eval-rst} +.. cfgcmd:: set vpn ipsec ike-group <name> dead-peer-detection action <action> + + Action to perform for this CHILD_SA on DPD timeout. + + * **trap** - Installs a trap policy (IPsec policy without Security + Association), which will catch matching traffic and tries to + re-negotiate the tunnel on-demand. + * **clear** - Closes the CHILD_SA and does not take further action + (default). + * **restart** - Immediately tries to re-negotiate the CHILD_SA + under a fresh IKE_SA. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec ike-group <name> dead-peer-detection interval <interval> + + Keep-alive interval in seconds <2-86400> (default 30). +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec ike-group <name> dead-peer-detection timeout <timeout> + + Keep-alive timeout in seconds <2-86400> (default 120) **IKEv1 only** +``` + +### ESP (Encapsulating Security Payload) Attributes + +In VyOS, ESP attributes are specified through ESP groups. +Multiple proposals can be specified in a single group. + +VyOS ESP group has the next options: + +```{eval-rst} +.. cfgcmd:: set vpn ipsec esp-group <name> compression + + Enables the IPComp(IP Payload Compression) protocol which allows + compressing the content of IP packets. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec esp-group <name> disable-rekey + + Do not locally initiate a re-key of the SA, remote peer must + re-key before expiration. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec esp-group <name> life-bytes <bytes> + + ESP life in bytes <1024-26843545600000>. Number of bytes + transmitted over an IPsec SA before it expires. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec esp-group <name> life-packets <packets> + + ESP life in packets <1000-26843545600000>. + Number of packets transmitted over an IPsec SA before it expires. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec esp-group <name> lifetime <timeout> + + ESP lifetime in seconds <30-86400> (default 3600). + How long a particular instance of a connection (a set of + encryption/authentication keys for user packets) should last, + from successful negotiation to expiry. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec esp-group <name> mode <mode> + + The type of the connection: + + * **tunnel** - Tunnel mode (default). + * **transport** - Transport mode. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec esp-group <name> pfs < dh-group> + + Whether Perfect Forward Secrecy of keys is desired on the + connection's keying channel and defines a Diffie-Hellman group for + PFS: + + * **enable** - Inherit Diffie-Hellman group from IKE group (default). + * **disable** - Disable PFS. + * **<dh-group>** - Defines a Diffie-Hellman group for PFS. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec esp-group <name> proposal <number> encryption <encryption> + + Encryption algorithm. Default value is **aes128**. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec esp-group <name> proposal <number> hash <hash> + + Hash algorithm. Default value is **sha1**. +``` + +### Global IPsec Settings + +```{eval-rst} +.. cfgcmd:: set vpn ipsec interface <name> + + Interface name to restrict outbound IPsec policies. There is a possibility + to specify multiple interfaces. If an interfaces are not specified, IPsec + policies apply to all interfaces. + +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec log level <number> + + Level of logging. Default value is **0**. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec log subsystem <name> + + Subsystem of the daemon. +``` + +### Options + +```{eval-rst} +.. cfgcmd:: set vpn ipsec options disable-route-autoinstall + + Do not automatically install routes to remote + networks. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec options flexvpn + + Allows FlexVPN vendor ID payload (IKEv2 only). Send the Cisco + FlexVPN vendor ID payload (IKEv2 only), which is required in order to make + Cisco brand devices allow negotiating a local traffic selector (from + strongSwan's point of view) that is not the assigned virtual IP address if + such an address is requested by strongSwan. Sending the Cisco FlexVPN + vendor ID prevents the peer from narrowing the initiator's local traffic + selector and allows it to e.g. negotiate a TS of 0.0.0.0/0 == 0.0.0.0/0 + instead. This has been tested with a "tunnel mode ipsec ipv4" Cisco + template but should also work for GRE encapsulation. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec options interface <name> + + Interface Name to use. The name of the interface on which + virtual IP addresses should be installed. If not specified the addresses + will be installed on the outbound interface. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec options virtual-ip + + Allows the installation of virtual-ip addresses. +``` diff --git a/docs/configuration/vpn/ipsec/md-remoteaccess_ipsec.md b/docs/configuration/vpn/ipsec/md-remoteaccess_ipsec.md new file mode 100644 index 00000000..bd25a072 --- /dev/null +++ b/docs/configuration/vpn/ipsec/md-remoteaccess_ipsec.md @@ -0,0 +1,179 @@ +(remoteaccess-ipsec)= + +# IPSec IKEv2 Remote Access VPN + +Internet Key Exchange version 2 (IKEv2) is a tunneling protocol, based on IPsec, +that establishes a secure VPN communication between VPN devices, and defines +negotiation and authentication processes for IPsec security associations (SAs). +It is often known as IKEv2/IPSec or IPSec IKEv2 remote-access — or road-warriors +as others call it. + +Key exchange and payload encryption is done using IKE and ESP proposals as known +from IKEv1 but the connections are faster to establish, more reliable, and also +support roaming from IP to IP (called MOBIKE which makes sure your connection +does not drop when changing networks from e.g. WIFI to LTE and back). +Authentication can be achieved with X.509 certificates. + +## Setting up certificates: + +First of all, we need to create a CA root certificate and server certificate +on the server side. + +```none +vyos@vpn.vyos.net# run generate pki ca install ca_root +Enter private key type: [rsa, dsa, ec] (Default: rsa) +Enter private key bits: (Default: 2048) +Enter country code: (Default: GB) +Enter state: (Default: Some-State) +Enter locality: (Default: Some-City) +Enter organization name: (Default: VyOS) +Enter common name: (Default: vyos.io) +Enter how many days certificate will be valid: (Default: 1825) +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] N +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +[edit] + + +vyos@vpn.vyos.net# comp +[pki ca] ++ ca_root { ++ certificate "MIIDnTCCAoWgAwI…." ++ private { ++ key "MIIEvAIBADANBgkqhkiG9….” + +vyos@vpn.vyos.net# run generate pki certificate sign ca_root install server_cert +Do you already have a certificate request? [y/N] N +Enter private key type: [rsa, dsa, ec] (Default: rsa) +Enter private key bits: (Default: 2048) +Enter country code: (Default: GB) +Enter state: (Default: Some-State) +Enter locality: (Default: Some-City) +Enter organization name: (Default: VyOS) +Enter common name: (Default: vyos.io) vpn.vyos.net +Do you want to configure Subject Alternative Names? [y/N] N +Enter how many days certificate will be valid: (Default: 365) +Enter certificate type: (client, server) (Default: server) +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] N +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. + +vyos@vpn.vyos.net# comp +[pki certificate] ++ server_cert { ++ certificate "MIIDuzCCAqOgAwIBAgIUaSrCPWx………" ++ private { ++ key "MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBK….." ++ } ++ } +``` + +Once the command is completed, it will add the certificate to the configuration +session, to the pki subtree. You can then review the proposed changes and +commit them. + +## Setting up IPSec: + +After the PKI certs are all set up we can start configuring our IPSec/IKE +proposals used for key-exchange end data encryption. The used encryption ciphers +and integrity algorithms vary from operating system to operating system. The +ones used in this example are validated to work on Windows 10. + +```none +set vpn ipsec esp-group ESP-RW lifetime '3600' +set vpn ipsec esp-group ESP-RW pfs 'disable' +set vpn ipsec esp-group ESP-RW proposal 10 encryption 'aes128gcm128' +set vpn ipsec esp-group ESP-RW proposal 10 hash 'sha256' + +set vpn ipsec ike-group IKE-RW key-exchange 'ikev2' +set vpn ipsec ike-group IKE-RW lifetime '7200' +set vpn ipsec ike-group IKE-RW proposal 10 dh-group '14' +set vpn ipsec ike-group IKE-RW proposal 10 encryption 'aes128gcm128' +set vpn ipsec ike-group IKE-RW proposal 10 hash 'sha256' +``` + +Every connection/remote-access pool we configure also needs a pool where we +can draw our client IP addresses from. We provide one IPv4 and IPv6 pool. +Authorized clients will receive an IPv4 address from the configured IPv4 prefix +and an IPv6 address from the IPv6 prefix. We can also send some DNS nameservers +down to our clients used on their connection. + +```none +set vpn ipsec remote-access pool ra-rw-ipv4 name-server '192.0.2.1' +set vpn ipsec remote-access pool ra-rw-ipv4 prefix '192.0.2.128/25' + +set vpn ipsec remote-access pool ra-rw-ipv6 name-server '2001:db8:1000::1' +set vpn ipsec remote-access pool ra-rw-ipv6 prefix '2001:db8:2000::/64' +``` + +## Setting up tunnel: + +```none +set vpn ipsec remote-access connection rw authentication local-id '192.0.2.1' +set vpn ipsec remote-access connection rw authentication server-mode 'x509' +set vpn ipsec remote-access connection rw authentication x509 ca-certificate 'ca_root' +set vpn ipsec remote-access connection rw authentication x509 certificate 'server_cert' +set vpn ipsec remote-access connection rw esp-group 'ESP-RW' +set vpn ipsec remote-access connection rw ike-group 'IKE-RW' +set vpn ipsec remote-access connection rw local-address '192.0.2.1' +set vpn ipsec remote-access connection rw pool 'ra-rw-ipv4' +set vpn ipsec remote-access connection rw pool 'ra-rw-ipv6' +``` + +VyOS also supports two different modes of authentication, local and RADIUS. +To create a new local user named "vyos" with a password of "vyos" use the +following commands. + +```none +set vpn ipsec remote-access connection rw authentication client-mode 'eap-mschapv2' +set vpn ipsec remote-access connection rw authentication local-users username vyos password 'vyos' +``` + +Some client operating systems like to see the servers certificate. The following +option causes the server to voluntarily send its certificate, even if it wasn't +requested. + +```none +set vpn ipsec remote-access connection rw authentication always-send-cert +``` + +## Client Configuration + +Most operating systems include native client support for IPsec IKEv2 VPN +connections, and others typically have an app or add-on package which adds the +capability. +This section covers IPsec IKEv2 client configuration for Windows 10. + +VyOS provides a command to generate a connection profile used by Windows clients +that will connect to the "rw" connection on our VyOS server. + +:::{note} +Windows expects the server name to be also used in the server's +certificate common name, so it's best to use this DNS name for your VPN +connection. +::: + +```none +vyos@vpn.vyos.net:~$ generate ipsec profile windows-remote-access rw remote vpn.vyos.net + + +==== <snip> ==== +Add-VpnConnection -Name "VyOS IKEv2 VPN" -ServerAddress "vpn.vyos.net" -TunnelType "Ikev2" + +Set-VpnConnectionIPsecConfiguration -ConnectionName "VyOS IKEv2 VPN" -AuthenticationTransformConstants GCMAES128 -CipherTransformConstants +GCMAES128 -EncryptionMethod GCMAES128 -IntegrityCheckMethod SHA256128 -PfsGroup None -DHGroup "Group14" -PassThru -Force +==== </snip> ==== +``` + +Add the commands from Snippet in the Windows side via PowerShell. +Also import the root CA cert to the Windows “Trusted Root Certification +Authorities” and establish the connection. + +## Verification: + +```none +vyos@vpn.vyos.net:~$ show vpn ipsec remote-access summary + Connection ID Username Protocol State Uptime Tunnel IP Remote Host Remote ID IKE Proposal IPSec Proposal +--------------- ---------- ---------- ------- -------- ----------- ------------- ----------- ------------------------------------------ ------------------ + 5 vyos IKEv2 UP 37s 192.0.2.129 10.0.0.2 10.0.0.2 AES_GCM_16-128/PRF_HMAC_SHA2_256/MODP_2048 ESP:AES_GCM_16-128 +``` diff --git a/docs/configuration/vpn/ipsec/md-site2site_ipsec.md b/docs/configuration/vpn/ipsec/md-site2site_ipsec.md new file mode 100644 index 00000000..b813380f --- /dev/null +++ b/docs/configuration/vpn/ipsec/md-site2site_ipsec.md @@ -0,0 +1,811 @@ +(size2site-ipsec)= + +# IPsec Site-to-Site VPN + +## IPsec Site-to-Site VPN Types + +VyOS supports two types of IPsec VPN: Policy-based IPsec VPN and Route-based +IPsec VPN. + +### Policy-based VPN + +Policy-based VPN is based on static configured policies. Each policy creates +individual IPSec SA. Traffic matches these SAs encrypted and directed to the +remote peer. + +### Route-Based VPN + +Route-based VPN is based on secure traffic passing over Virtual Tunnel +Interfaces (VTIs). This type of IPsec VPNs allows using routing protocols. + +## Configuration Site-to-Site VPN + +### Requirements and Prerequisites for Site-to-Site VPN + +**Negotiated parameters that need to match** + +Phase 1 +: - IKE version + - Authentication + - Encryption + - Hashing + - PRF + - Lifetime + + :::{note} + Strongswan recommends to use the same lifetime value on both peers + ::: + +Phase 2 +: - Encryption + - Hashing + - PFS + - Mode (tunnel or transport) + - Lifetime + + :::{note} + Strongswan recommends to use the same lifetime value on both peers + ::: + + - Remote and Local networks in SA must be compatible on both peers + +### Configuration Steps for Site-to-Site VPN + +The next example shows the configuration one of the router participating in +IPsec VPN. + +Tunnel information: +: - Phase 1: + : - encryption: AES256 + - hash: SHA256 + - PRF: SHA256 + - DH: 14 + - lifetime: 28800 + - Phase 2: + : - IPsec mode: tunnel + - encryption: AES256 + - hash: SHA256 + - PFS: inherited from DH Phase 1 + - lifetime: 3600 + - If Policy based VPN is used + : - Remote network is 192.168.50.0/24. Local network is 192.168.10.0/24 + - If Route based VPN is used + : - IP of the VTI interface is 10.0.0.1/30 + +:::{note} +We do not recommend using policy-based vpn and route-based vpn configurations to the same peer. +::: + +**1. Configure ike-group (IKE Phase 1)** + +```none +set vpn ipsec ike-group IKE close-action 'start' +set vpn ipsec ike-group IKE key-exchange 'ikev1' +set vpn ipsec ike-group IKE lifetime '28800' +set vpn ipsec ike-group IKE proposal 10 dh-group '14' +set vpn ipsec ike-group IKE proposal 10 encryption 'aes256' +set vpn ipsec ike-group IKE proposal 10 hash 'sha256' +set vpn ipsec ike-group IKE proposal 10 prf 'prfsha256' +``` + +**2. Configure ESP-group (IKE Phase 2)** + +```none +set vpn ipsec esp-group ESP lifetime '3600' +set vpn ipsec esp-group ESP mode 'tunnel' +set vpn ipsec esp-group ESP pfs 'enable' +set vpn ipsec esp-group ESP proposal 10 encryption 'aes256' +set vpn ipsec esp-group ESP proposal 10 hash 'sha256' +``` + +**3. Specify interface facing to the protected destination.** + +```none +set vpn ipsec interface eth0 +``` + +**4. Configure PSK keys and authentication ids for this key if authentication type is PSK** + +```none +set vpn ipsec authentication psk PSK-KEY id '192.168.0.2' +set vpn ipsec authentication psk PSK-KEY id '192.168.5.2' +set vpn ipsec authentication psk PSK-KEY secret 'vyos' +``` + +To set base64 secret encode plaintext password to base64 and set secret-type + +```none +echo -n "vyos" | base64 +dnlvcw== +``` + +```none +set vpn ipsec authentication psk PSK-KEY secret 'dnlvcw==' +set vpn ipsec authentication psk PSK-KEY secret-type base64 +``` + +**5. Configure peer and apply IKE-group and esp-group to peer.** + +```none +set vpn ipsec site-to-site peer PEER1 authentication local-id '192.168.0.2' +set vpn ipsec site-to-site peer PEER1 authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer PEER1 authentication remote-id '192.168.5.2' +set vpn ipsec site-to-site peer PEER1 connection-type 'initiate' +set vpn ipsec site-to-site peer PEER1 default-esp-group 'ESP' +set vpn ipsec site-to-site peer PEER1 ike-group 'IKE' +set vpn ipsec site-to-site peer PEER1 local-address '192.168.0.2' +set vpn ipsec site-to-site peer PEER1 remote-address '192.168.5.2' + +Peer selects the key from step 4 according to local-id/remote-id pair. +``` + +**6. Depends to vpn type (route-based vpn or policy-based vpn).** + +> **6.1 For Policy-based VPN configure SAs using tunnel command specifying remote and local networks.** +> +> > ```none +> > set vpn ipsec site-to-site peer PEER1 tunnel 1 local prefix '192.168.10.0/24' +> > set vpn ipsec site-to-site peer PEER1 tunnel 1 remote prefix '192.168.50.0/24' +> > ``` +> +> **6.2 For Route-based VPN create VTI interface, set IP address to this interface and bind this interface to the vpn peer.** +> +> > ```none +> > set interfaces vti vti1 address 10.0.0.1/30 +> > set vpn ipsec site-to-site peer PEER1 vti bind vti1 +> > set vpn ipsec options disable-route-autoinstall +> > ``` +> > +> > Create routing between local networks via VTI interface using dynamic or +> > static routing. +> > +> > ```none +> > set protocol static route 192.168.50.0/24 next-hop 10.0.0.2 +> > ``` + +### Initiator and Responder Connection Types + +In Site-to-Site IPsec VPN it is recommended that one peer should be an +initiator and the other - the responder. The initiator actively establishes +the VPN tunnel. The responder passively waits for the remote peer to +establish the VPN tunnel. Depends on selected role it is recommended +select proper values for close-action and DPD action. + +The result of wrong value selection can be unstable work of the VPN. +: - Duplicate CHILD SA creation. + - None of the VPN sides initiates the tunnel establishment. + +Below flow-chart could be a quick reference for the close-action +combination depending on how the peer is configured. + +:::{figure} /_static/images/IPSec_close_action_settings.png +::: + +Similar combinations are applicable for the dead-peer-detection. + +### Detailed Configuration Commands + +#### PSK Key Authentication + +```{eval-rst} +.. cfgcmd:: set vpn ipsec authentication psk <name> dhcp-interface + + ID for authentication generated from DHCP address + dynamically. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec authentication psk id <id> + + static ID's for authentication. In general local and remote + address ``<x.x.x.x>``, ``<h:h:h:h:h:h:h:h>`` or ``%any``. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec authentication psk secret <secret> + + A predefined shared secret used in configured mode + ``pre-shared-secret``. Base64-encoded secrets are allowed if + `secret-type base64` is configured. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec authentication psk secret-type <type> + + Specifies the secret type: + + * **plaintext** - Plain text type (default value). + * **base64** - Base64 type. +``` + +#### Peer Configuration + +##### Peer Authentication Commands + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication mode <mode> + + Mode for authentication between VyOS and remote peer: + + * **pre-shared-secret** - Use predefined shared secret phrase. + * **rsa** - Use simple shared RSA key. + * **x509** - Use certificates infrastructure for authentication. + +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication local-id <id> + + ID for the local VyOS router. If defined, during the authentication + it will be send to remote peer. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication remote-id <id> + + 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. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication rsa local-key <key> + + Name of PKI key-pair with local private key. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication rsa remote-key <key> + + Name of PKI key-pair with remote public key. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication rsa passphrase <passphrase> + + Local private key passphrase. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication use-x509-id <id> + + Use local ID from x509 certificate. Cannot be used when + ``id`` is defined. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication x509 ca-certificate <name> + + Name of CA certificate in PKI configuration. Using for authenticating + remote peer in x509 mode. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication x509 certificate <name> + + Name of certificate in PKI configuration, which will be used + for authenticating local router on remote peer. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec authentication x509 passphrase <passphrase> + + Private key passphrase, if needed. +``` + +##### Global Peer Configuration Commands + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> connection-type <type> + + Operational mode defines how to handle this connection process. + + * **initiate** - does 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** - does 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. + * **none** - loads the connection only, which then can be manually + initiated or used as a responder configuration. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> default-esp-group <name> + + Name of ESP group to use by default for traffic encryption. + Might be overwritten by individual settings for tunnel or VTI + interface binding. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> description <description> + + Description for this peer. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> dhcp-interface <interface> + + Specify the interface which IP address, received from DHCP for IPSec + connection with this peer, will be used as ``local-address``. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> force-udp-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. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> ike-group <name> + + Name of IKE group to use for key exchanges. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> local-address <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. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> remote-address <address> + + Remote IP address or hostname for IPsec connection. IPv4 or IPv6 + address is used when a peer has a public static IP address. Hostname + is a DNS name which 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. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> replay-window <size> + + IPsec replay window to configure for CHILD_SAs + (default: 32), a value of 0 disables IPsec replay protection. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> virtual-address <address> + + Defines a virtual IP address which is requested by the initiator and + one or several IPv4 and/or IPv6 addresses are assigned from multiple + pools by the responder. The wildcard addresses 0.0.0.0 and :: + request an arbitrary address, specific addresses may be defined. +``` + +##### CHILD SAs Configuration Commands + +###### Policy-Based CHILD SAs Configuration Commands + +Every configured tunnel under peer configuration is a new CHILD SA. + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> disable + + Disable this tunnel. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> esp-group <name> + + Specify ESP group for this CHILD SA. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> priority <number> + + Priority for policy-based IPsec VPN tunnels (lowest value more + preferable). +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> protocol <name> + + Define the protocol for match traffic, which should be encrypted and + send to this peer. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> local prefix <network> + + IP network at the local side. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> local port <number> + + Local port number. Have effect only when used together with + ``prefix``. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> remote prefix <network> + + IP network at the remote side. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> remote port <number> + + Remote port number. Have effect only when used together with + ``prefix``. +``` + +###### Route-Based CHILD SAs Configuration Commands + +To configure route-based VPN it is enough to create vti interface and +bind it to the peer. 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. + +:::{warning} +When using site-to-site IPsec with VTI interfaces, +be sure to disable route autoinstall. +::: + +```none +set vpn ipsec options disable-route-autoinstall +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> vti bind <interface> + + VTI interface to bind to this peer. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> vti esp-group <name> + + ESP group for encrypt traffic, passed this VTI interface. +``` + +Traffic-selectors parameters for traffic that should pass via vti +interface. + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> vti traffic-selector local prefix <network> + + Local prefix for interesting traffic. +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec site-to-site peer <name> vti traffic-selector remote prefix <network> + + Remote prefix for interesting traffic. +``` + +### IPsec Op-mode Commands + +```{eval-rst} +.. opcmd:: show vpn ike sa + + Shows active IKE SAs information. +``` + +```{eval-rst} +.. opcmd:: show vpn ike secrets + + Shows configured authentication keys. +``` + +```{eval-rst} +.. opcmd:: show vpn ike status + + Shows Strongswan daemon status. +``` + +```{eval-rst} +.. opcmd:: show vpn ipsec connections + + Shows summary status of all configured IKE and IPsec SAs. +``` + +```{eval-rst} +.. opcmd:: show vpn ipsec sa [detail] + + Shows active IPsec SAs information. +``` + +```{eval-rst} +.. opcmd:: show vpn ipsec status + + Shows status of IPsec process. +``` + +```{eval-rst} +.. opcmd:: show vpn ipsec policy + + Shows the in-kernel crypto policies. +``` + +```{eval-rst} +.. opcmd:: show vpn ipsec state + + Shows the in-kernel crypto state. +``` + +```{eval-rst} +.. opcmd:: show log ipsec + + Shows IPsec logs. +``` + +```{eval-rst} +.. opcmd:: reset vpn ipsec site-to-site all + + Clear all ipsec connection and reinitiate them if VyOS is configured + as initiator. +``` + +```{eval-rst} +.. opcmd:: reset vpn ipsec site-to-site peer <name> + + Clear all peer IKE SAs with IPsec SAs and reinitiate them if VyOS is + configured as initiator. +``` + +```{eval-rst} +.. opcmd:: reset vpn ipsec site-to-site peer <name> tunnel <number> + + Clear scpecific IPsec SA and reinitiate it if VyOS is configured as + initiator. +``` + +```{eval-rst} +.. opcmd:: reset vpn ipsec site-to-site peer <name> vti <number> + + Clear IPsec SA which is map to vti interface of this peer and + reinitiate it if VyOS is configured as initiator. +``` + +```{eval-rst} +.. opcmd:: restart ipsec + + Restart Strongswan daemon. +``` + +## Examples: + +### Policy-Based VPN Example + +**PEER1:** + +- WAN interface on `eth0` +- `eth0` interface IP: `10.0.1.2/30` +- `dum0` interface IP: `192.168.0.1/24` (for testing purposes) +- Initiator + +**PEER2:** + +- WAN interface on `eth0` +- `eth0` interface IP: `10.0.2.2/30` +- `dum0` interface IP: `192.168.1.0/24` (for testing purposes) +- Responder + +```none +# PEER1 +set interfaces dummy dum0 address '192.168.0.1/32' +set interfaces ethernet eth0 address '10.0.1.2/30' +set protocols static route 0.0.0.0/0 next-hop 10.0.1.1 +set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' +set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' +set vpn ipsec authentication psk AUTH-PSK secret 'test' +set vpn ipsec esp-group ESP-GRPOUP lifetime '3600' +set vpn ipsec esp-group ESP-GRPOUP proposal 10 encryption 'aes256' +set vpn ipsec esp-group ESP-GRPOUP proposal 10 hash 'sha1' +set vpn ipsec ike-group IKE-GROUP close-action 'start' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'restart' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '30' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection timeout '120' +set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev1' +set vpn ipsec ike-group IKE-GROUP lifetime '28800' +set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' +set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256' +set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' +set vpn ipsec interface 'eth0' +set vpn ipsec site-to-site peer PEER2 authentication local-id '10.0.1.2' +set vpn ipsec site-to-site peer PEER2 authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer PEER2 authentication remote-id '10.0.2.2' +set vpn ipsec site-to-site peer PEER2 connection-type 'initiate' +set vpn ipsec site-to-site peer PEER2 default-esp-group 'ESP-GRPOUP' +set vpn ipsec site-to-site peer PEER2 ike-group 'IKE-GROUP' +set vpn ipsec site-to-site peer PEER2 local-address '10.0.1.2' +set vpn ipsec site-to-site peer PEER2 remote-address '10.0.2.2' +set vpn ipsec site-to-site peer PEER2 tunnel 0 local prefix '192.168.0.0/24' +set vpn ipsec site-to-site peer PEER2 tunnel 0 remote prefix '192.168.1.0/24' + + +# PEER2 +set interfaces dummy dum0 address '192.168.1.1/32' +set interfaces ethernet eth0 address '10.0.2.2/30' +set protocols static route 0.0.0.0/0 next-hop 10.0.2.1 +set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' +set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' +set vpn ipsec authentication psk AUTH-PSK secret 'test' +set vpn ipsec esp-group ESP-GRPOUP lifetime '3600' +set vpn ipsec esp-group ESP-GRPOUP proposal 10 encryption 'aes256' +set vpn ipsec esp-group ESP-GRPOUP proposal 10 hash 'sha1' +set vpn ipsec ike-group IKE-GROUP close-action 'none' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'clear' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '30' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection timeout '120' +set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev1' +set vpn ipsec ike-group IKE-GROUP lifetime '28800' +set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' +set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256' +set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' +set vpn ipsec interface 'eth0' +set vpn ipsec site-to-site peer PEER1 authentication local-id '10.0.2.2' +set vpn ipsec site-to-site peer PEER1 authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer PEER1 authentication remote-id '10.0.1.2' +set vpn ipsec site-to-site peer PEER1 connection-type 'respond' +set vpn ipsec site-to-site peer PEER1 default-esp-group 'ESP-GRPOUP' +set vpn ipsec site-to-site peer PEER1 ike-group 'IKE-GROUP' +set vpn ipsec site-to-site peer PEER1 local-address '10.0.2.2' +set vpn ipsec site-to-site peer PEER1 remote-address '10.0.1.2' +set vpn ipsec site-to-site peer PEER1 tunnel 0 local prefix '192.168.1.0/24' +set vpn ipsec site-to-site peer PEER1 tunnel 0 remote prefix '192.168.0.0/24' +``` + +Show status of policy-based IPsec VPN setup: + +```none +vyos@PEER2:~$ show vpn ike sa +Peer ID / IP Local ID / IP +------------ ------------- +10.0.1.2 10.0.1.2 10.0.2.2 10.0.2.2 + + State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time + ----- ------ ------- ---- --------- ----- ------ ------ + up IKEv1 AES_CBC_256 HMAC_SHA1_96 MODP_2048 no 1254 25633 + + +vyos@srv-gw0:~$ show vpn ipsec sa +Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal +-------------- ------- -------- -------------- ---------------- ---------------- ----------- ---------------------------------- +PEER1-tunnel-0 up 20m42s 0B/0B 0/0 10.0.1.2 10.0.1.2 AES_CBC_256/HMAC_SHA1_96/MODP_2048 + +vyos@PEER2:~$ show vpn ipsec connections +Connection State Type Remote address Local TS Remote TS Local id Remote id Proposal +-------------- ------- ------ ---------------- -------------- -------------- ---------- ----------- ---------------------------------- +PEER1 up IKEv1 10.0.1.2 - - 10.0.2.2 10.0.1.2 AES_CBC/256/HMAC_SHA1_96/MODP_2048 +PEER1-tunnel-0 up IPsec 10.0.1.2 192.168.1.0/24 192.168.0.0/24 10.0.2.2 10.0.1.2 AES_CBC/256/HMAC_SHA1_96/MODP_2048 +``` + +If there is SNAT rules on eth0, need to add exclude rule + +```none +# PEER1 side +set nat source rule 10 destination address '192.168.1.0/24' +set nat source rule 10 'exclude' +set nat source rule 10 outbound-interface name 'eth0' +set nat source rule 10 source address '192.168.0.0/24' + +# PEER2 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 name 'eth0' +set nat source rule 10 source address '192.168.1.0/24' +``` + +### Route-Based VPN Example + +**PEER1:** + +- WAN interface on `eth0` +- `eth0` interface IP: `10.0.1.2/30` +- 'vti0' interface IP: `10.100.100.1/30` +- `dum0` interface IP: `192.168.0.1/24` (for testing purposes) +- Role: Initiator + +**PEER2:** + +- WAN interface on `eth0` +- `eth0` interface IP: `10.0.2.2/30` +- 'vti0' interface IP: `10.100.100.2/30` +- `dum0` interface IP: `192.168.1.0/24` (for testing purposes) +- Role: Responder + +```none +# PEER1 +set interfaces dummy dum0 address '192.168.0.1/32' +set interfaces ethernet eth0 address '10.0.1.2/30' +set interfaces vti vti0 address '10.100.100.1/30' +set protocols static route 0.0.0.0/0 next-hop 10.0.1.1 +set protocols static route 192.168.1.0/24 next-hop 10.100.100.2 +set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' +set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' +set vpn ipsec authentication psk AUTH-PSK secret 'test' +set vpn ipsec esp-group ESP-GRPOUP lifetime '3600' +set vpn ipsec esp-group ESP-GRPOUP proposal 10 encryption 'aes256' +set vpn ipsec esp-group ESP-GRPOUP proposal 10 hash 'sha1' +set vpn ipsec ike-group IKE-GROUP close-action 'start' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'restart' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '30' +set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev2' +set vpn ipsec ike-group IKE-GROUP lifetime '28800' +set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' +set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256' +set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' +set vpn ipsec interface 'eth0' +set vpn ipsec options disable-route-autoinstall +set vpn ipsec site-to-site peer PEER2 authentication local-id '10.0.1.2' +set vpn ipsec site-to-site peer PEER2 authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer PEER2 authentication remote-id '10.0.2.2' +set vpn ipsec site-to-site peer PEER2 connection-type 'initiate' +set vpn ipsec site-to-site peer PEER2 default-esp-group 'ESP-GRPOUP' +set vpn ipsec site-to-site peer PEER2 ike-group 'IKE-GROUP' +set vpn ipsec site-to-site peer PEER2 local-address '10.0.1.2' +set vpn ipsec site-to-site peer PEER2 remote-address '10.0.2.2' +set vpn ipsec site-to-site peer PEER2 vti bind 'vti0' + + +# PEER2 +set interfaces dummy dum0 address '192.168.1.1/32' +set interfaces ethernet eth0 address '10.0.2.2/30' +set interfaces vti vti0 address '10.100.100.2/30' +set protocols static route 0.0.0.0/0 next-hop 10.0.2.1 +set protocols static route 192.168.0.0/24 next-hop 10.100.100.1 +set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' +set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' +set vpn ipsec authentication psk AUTH-PSK secret 'test' +set vpn ipsec esp-group ESP-GRPOUP lifetime '3600' +set vpn ipsec esp-group ESP-GRPOUP proposal 10 encryption 'aes256' +set vpn ipsec esp-group ESP-GRPOUP proposal 10 hash 'sha1' +set vpn ipsec ike-group IKE-GROUP close-action 'none' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'clear' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '30' +set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev2' +set vpn ipsec ike-group IKE-GROUP lifetime '28800' +set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' +set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256' +set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' +set vpn ipsec interface 'eth0' +set vpn ipsec options disable-route-autoinstall +set vpn ipsec site-to-site peer PEER1 authentication local-id '10.0.2.2' +set vpn ipsec site-to-site peer PEER1 authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer PEER1 authentication remote-id '10.0.1.2' +set vpn ipsec site-to-site peer PEER1 connection-type 'respond' +set vpn ipsec site-to-site peer PEER1 default-esp-group 'ESP-GRPOUP' +set vpn ipsec site-to-site peer PEER1 ike-group 'IKE-GROUP' +set vpn ipsec site-to-site peer PEER1 local-address '10.0.2.2' +set vpn ipsec site-to-site peer PEER1 remote-address '10.0.1.2' +set vpn ipsec site-to-site peer PEER1 vti bind 'vti0' +``` + +Show status of route-based IPsec VPN setup: + +```none +vyos@PEER2:~$ show vpn ike sa +Peer ID / IP Local ID / IP +------------ ------------- +10.0.1.2 10.0.1.2 10.0.2.2 10.0.2.2 + + State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time + ----- ------ ------- ---- --------- ----- ------ ------ + up IKEv2 AES_CBC_256 HMAC_SHA1_96 MODP_2048 no 404 27650 + +vyos@PEER2:~$ show vpn ipsec sa +Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal +------------ ------- -------- -------------- ---------------- ---------------- ----------- ---------------------------------- +PEER1-vti up 3m28s 0B/0B 0/0 10.0.1.2 10.0.1.2 AES_CBC_256/HMAC_SHA1_96/MODP_2048 + +vyos@PEER2:~$ show vpn ipsec connections +Connection State Type Remote address Local TS Remote TS Local id Remote id Proposal +------------ ------- ------ ---------------- ---------- ----------- ---------- ----------- ---------------------------------- +PEER1 up IKEv2 10.0.1.2 - - 10.0.2.2 10.0.1.2 AES_CBC/256/HMAC_SHA1_96/MODP_2048 +PEER1-vti up IPsec 10.0.1.2 0.0.0.0/0 0.0.0.0/0 10.0.2.2 10.0.1.2 AES_CBC/256/HMAC_SHA1_96/MODP_2048 + ::/0 ::/0 +``` diff --git a/docs/configuration/vpn/ipsec/md-troubleshooting_ipsec.md b/docs/configuration/vpn/ipsec/md-troubleshooting_ipsec.md new file mode 100644 index 00000000..064b4709 --- /dev/null +++ b/docs/configuration/vpn/ipsec/md-troubleshooting_ipsec.md @@ -0,0 +1,305 @@ +(troubleshooting-ipsec)= + +# Troubleshooting Site-to-Site VPN IPsec + +## Introduction + +This document describes the methodology to monitor and troubleshoot +Site-to-Site VPN IPsec. + +Steps for troubleshooting problems with Site-to-Site VPN IPsec: +: 1. Ping the remote site through the tunnel using the source and + destination IPs included in the policy. + 2. Check connectivity between the routers using the ping command + (if ICMP traffic is allowed). + 3. Check the IKE SAs' statuses. + 4. Check the IPsec SAs' statuses. + 5. Check logs to view debug messages. + +## Checking IKE SA Status + +The next command shows IKE SAs' statuses. + +```none +vyos@vyos:~$ show vpn ike sa + +Peer ID / IP Local ID / IP +------------ ------------- +192.168.1.2 192.168.1.2 192.168.0.1 192.168.0.1 + + State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time + ----- ------ ------- ---- --------- ----- ------ ------ + up IKEv2 AES_CBC_128 HMAC_SHA1_96 MODP_2048 no 162 27023 +``` + +This command shows the next information: +: - IKE SA status. + - Selected IKE version. + - Selected Encryption, Hash and Diffie-Hellman Group. + - NAT-T. + - ID and IP of both peers. + - A-Time: established time, L-Time: time for next rekeying. + +## IPsec SA (CHILD SA) Status + +The next commands show IPsec SAs' statuses. + +```none +vyos@vyos:~$ show vpn ipsec sa +Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal +------------- ------- -------- -------------- ---------------- ---------------- ----------- ---------------------------------- +PEER-tunnel-1 up 16m30s 168B/168B 2/2 192.168.1.2 192.168.1.2 AES_CBC_128/HMAC_SHA1_96/MODP_2048 +``` + +```none +vyos@vyos:~$ show vpn ipsec sa detail +PEER: #1, ESTABLISHED, IKEv2, 101275ac719d5a1b_i* 68ea4ec3bed3bf0c_r + local '192.168.0.1' @ 192.168.0.1[4500] + remote '192.168.1.2' @ 192.168.1.2[4500] + AES_CBC-128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 + established 4054s ago, rekeying in 23131s + PEER-tunnel-1: #2, reqid 1, INSTALLED, TUNNEL, ESP:AES_CBC-128/HMAC_SHA1_96/MODP_2048 + installed 1065s ago, rekeying in 1998s, expires in 2535s + in c5821882, 168 bytes, 2 packets, 81s ago + out c433406a, 168 bytes, 2 packets, 81s ago + local 10.0.0.0/24 + remote 10.0.1.0/24 +``` + +These commands show the next information: +: - IPsec SA status. + - Uptime and time for the next rekeing. + - Amount of transferred data. + - Remote and local ID and IP. + - Selected Encryption, Hash and Diffie-Hellman Group. + - Mode (tunnel or transport). + - Remote and local prefixes which are use for policy. + +There is a possibility to view the summarized information of SAs' status + +```none +vyos@vyos:~$ show vpn ipsec connections +Connection State Type Remote address Local TS Remote TS Local id Remote id Proposal +------------- ------- ------ ---------------- ----------- ----------- ----------- ----------- ---------------------------------- +PEER up IKEv2 192.168.1.2 - - 192.168.0.1 192.168.1.2 AES_CBC/128/HMAC_SHA1_96/MODP_2048 +PEER-tunnel-1 up IPsec 192.168.1.2 10.0.0.0/24 10.0.1.0/24 192.168.0.1 192.168.1.2 AES_CBC/128/HMAC_SHA1_96/MODP_2048 +``` + +## Viewing Logs for Debugging + +If IKE SAs or IPsec SAs are down, need to debug IPsec connectivity +using logs `show log ipsec` + +The next example of the successful IPsec connection initialization. + +```none +vyos@vyos:~$ show log ipsec +Jun 20 14:29:47 charon[2428]: 02[NET] <PEER|1> received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes) +Jun 20 14:29:47 charon[2428]: 02[ENC] <PEER|1> parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ] +Jun 20 14:29:47 charon-systemd[2428]: received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes) +Jun 20 14:29:47 charon[2428]: 02[CFG] <PEER|1> selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 +Jun 20 14:29:47 charon-systemd[2428]: parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ] +Jun 20 14:29:47 charon-systemd[2428]: selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 +Jun 20 14:29:47 charon[2428]: 02[IKE] <PEER|1> authentication of '192.168.0.1' (myself) with pre-shared key +Jun 20 14:29:47 charon-systemd[2428]: authentication of '192.168.0.1' (myself) with pre-shared key +Jun 20 14:29:47 charon[2428]: 02[IKE] <PEER|1> establishing CHILD_SA PEER-tunnel-1{1} +Jun 20 14:29:47 charon-systemd[2428]: establishing CHILD_SA PEER-tunnel-1{1} +Jun 20 14:29:47 charon[2428]: 02[ENC] <PEER|1> generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ] +Jun 20 14:29:47 charon-systemd[2428]: generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ] +Jun 20 14:29:47 charon[2428]: 02[NET] <PEER|1> sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes) +Jun 20 14:29:47 charon-systemd[2428]: sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes) +Jun 20 14:29:47 charon[2428]: 13[NET] <PEER|1> received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (220 bytes) +Jun 20 14:29:47 charon[2428]: 13[ENC] <PEER|1> parsed IKE_AUTH response 1 [ IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) ] +Jun 20 14:29:47 charon-systemd[2428]: received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (220 bytes) +Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> authentication of '192.168.1.2' with pre-shared key successful +Jun 20 14:29:47 charon-systemd[2428]: parsed IKE_AUTH response 1 [ IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) ] +Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> peer supports MOBIKE +Jun 20 14:29:47 charon-systemd[2428]: authentication of '192.168.1.2' with pre-shared key successful +Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2] +Jun 20 14:29:47 charon-systemd[2428]: peer supports MOBIKE +Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> scheduling rekeying in 27703s +Jun 20 14:29:47 charon-systemd[2428]: IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2] +Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> maximum IKE_SA lifetime 30583s +Jun 20 14:29:47 charon-systemd[2428]: scheduling rekeying in 27703s +Jun 20 14:29:47 charon[2428]: 13[CFG] <PEER|1> selected proposal: ESP:AES_CBC_128/HMAC_SHA1_96/NO_EXT_SEQ +Jun 20 14:29:47 charon-systemd[2428]: maximum IKE_SA lifetime 30583s +Jun 20 14:29:47 charon-systemd[2428]: selected proposal: ESP:AES_CBC_128/HMAC_SHA1_96/NO_EXT_SEQ +Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> CHILD_SA PEER-tunnel-1{1} established with SPIs cb94fb3f_i ca99c8a9_o and TS 10.0.0.0/24 === 10.0.1.0/24 +Jun 20 14:29:47 charon-systemd[2428]: CHILD_SA PEER-tunnel-1{1} established with SPIs cb94fb3f_i ca99c8a9_o and TS 10.0.0.0/24 === 10.0.1.0/24 +``` + +## Troubleshooting Examples + +### IKE PROPOSAL are Different + +In this situation, IKE SAs can be down or not active. + +```none +vyos@vyos:~$ show vpn ike sa +``` + +The problem is in IKE phase (Phase 1). The next step is checking debug logs. + +Responder Side: + +```none +Jun 23 07:36:33 charon[2440]: 01[CFG] <1> received proposals: IKE:AES_CBC_256/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 +Jun 23 07:36:33 charon-systemd[2440]: received proposals: IKE:AES_CBC_256/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 +Jun 23 07:36:33 charon[2440]: 01[CFG] <1> configured proposals: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 +Jun 23 07:36:33 charon-systemd[2440]: configured proposals: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 +Jun 23 07:36:33 charon[2440]: 01[IKE] <1> received proposals unacceptable +Jun 23 07:36:33 charon-systemd[2440]: received proposals unacceptable +Jun 23 07:36:33 charon[2440]: 01[ENC] <1> generating IKE_SA_INIT response 0 [ N(NO_PROP) ] +``` + +Initiator side: + +```none +Jun 23 07:36:32 charon-systemd[2444]: parsed IKE_SA_INIT response 0 [ N(NO_PROP) ] +Jun 23 07:36:32 charon[2444]: 14[IKE] <PEER|1> received NO_PROPOSAL_CHOSEN notify error +Jun 23 07:36:32 charon-systemd[2444]: received NO_PROPOSAL_CHOSEN notify error +``` + +The notification **NO_PROPOSAL_CHOSEN** means that the proposal mismatch. +On the Responder side there is concrete information where is mismatch. +Encryption **AES_CBC_128** is configured in IKE policy on the responder +but **AES_CBC_256** is configured on the initiator side. + +### PSK Secret Mismatch + +In this situation, IKE SAs can be down or not active. + +```none +vyos@vyos:~$ show vpn ike sa +``` + +The problem is in IKE phase (Phase 1). The next step is checking debug logs. + +Responder: + +```none +Jun 23 08:07:26 charon-systemd[2440]: tried 1 shared key for '192.168.1.2' - '192.168.0.1', but MAC mismatched +Jun 23 08:07:26 charon[2440]: 13[ENC] <PEER|3> generating IKE_AUTH response 1 [ N(AUTH_FAILED) ] +``` + +Initiator side: + +```none +Jun 23 08:07:24 charon[2436]: 12[ENC] <PEER|1> parsed IKE_AUTH response 1 [ N(AUTH_FAILED) ] +Jun 23 08:07:24 charon-systemd[2436]: parsed IKE_AUTH response 1 [ N(AUTH_FAILED) ] +Jun 23 08:07:24 charon[2436]: 12[IKE] <PEER|1> received AUTHENTICATION_FAILED notify error +Jun 23 08:07:24 charon-systemd[2436]: received AUTHENTICATION_FAILED notify error +``` + +The notification **AUTHENTICATION_FAILED** means that the authentication +is failed. There is a reason to check PSK on both side. + +### ESP Proposal Mismatch + +The output of **show** commands shows us that IKE SA is established but +IPSec SA is not. + +```none +vyos@vyos:~$ show vpn ike sa +Peer ID / IP Local ID / IP +------------ ------------- +192.168.1.2 192.168.1.2 192.168.0.1 192.168.0.1 + + State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time + ----- ------ ------- ---- --------- ----- ------ ------ + up IKEv2 AES_CBC_128 HMAC_SHA1_96 MODP_2048 no 158 26817 +``` + +```none +vyos@vyos:~$ show vpn ipsec sa +Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal +------------ ------- -------- -------------- ---------------- ---------------- ----------- ---------- +``` + +The next step is checking debug logs. + +Initiator side: + +```none +Jun 23 08:16:10 charon[3789]: 13[NET] <PEER|1> received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes) +Jun 23 08:16:10 charon[3789]: 13[ENC] <PEER|1> parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ] +Jun 23 08:16:10 charon-systemd[3789]: received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes) +Jun 23 08:16:10 charon[3789]: 13[CFG] <PEER|1> selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 +Jun 23 08:16:10 charon-systemd[3789]: parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ] +Jun 23 08:16:10 charon-systemd[3789]: selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 +Jun 23 08:16:10 charon[3789]: 13[IKE] <PEER|1> authentication of '192.168.0.1' (myself) with pre-shared key +Jun 23 08:16:10 charon-systemd[3789]: authentication of '192.168.0.1' (myself) with pre-shared key +Jun 23 08:16:10 charon[3789]: 13[IKE] <PEER|1> establishing CHILD_SA PEER-tunnel-1{1} +Jun 23 08:16:10 charon-systemd[3789]: establishing CHILD_SA PEER-tunnel-1{1} +Jun 23 08:16:10 charon[3789]: 13[ENC] <PEER|1> generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ] +Jun 23 08:16:10 charon-systemd[3789]: generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ] +Jun 23 08:16:10 charon[3789]: 13[NET] <PEER|1> sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes) +Jun 23 08:16:10 charon-systemd[3789]: sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes) +Jun 23 08:16:10 charon[3789]: 09[NET] <PEER|1> received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (140 bytes) +Jun 23 08:16:10 charon-systemd[3789]: received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (140 bytes) +Jun 23 08:16:10 charon[3789]: 09[ENC] <PEER|1> parsed IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(NO_PROP) ] +Jun 23 08:16:10 charon-systemd[3789]: parsed IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(NO_PROP) ] +Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> authentication of '192.168.1.2' with pre-shared key successful +Jun 23 08:16:10 charon-systemd[3789]: authentication of '192.168.1.2' with pre-shared key successful +Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> peer supports MOBIKE +Jun 23 08:16:10 charon-systemd[3789]: peer supports MOBIKE +Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2] +Jun 23 08:16:10 charon-systemd[3789]: IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2] +Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> scheduling rekeying in 26975s +Jun 23 08:16:10 charon-systemd[3789]: scheduling rekeying in 26975s +Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> maximum IKE_SA lifetime 29855s +Jun 23 08:16:10 charon-systemd[3789]: maximum IKE_SA lifetime 29855s +Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> received NO_PROPOSAL_CHOSEN notify, no CHILD_SA built +Jun 23 08:16:10 charon-systemd[3789]: received NO_PROPOSAL_CHOSEN notify, no CHILD_SA built +Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> failed to establish CHILD_SA, keeping IKE_SA +Jun 23 08:16:10 charon-systemd[3789]: failed to establish CHILD_SA, keeping IKE_SA +``` + +There are messages: **NO_PROPOSAL_CHOSEN** and +**failed to establish CHILD_SA** which refers that the problem is in +the IPsec(ESP) proposal mismatch. + +The reason of this problem is showed on the responder side. + +```none +Jun 23 08:16:12 charon[2440]: 01[CFG] <PEER|5> received proposals: ESP:AES_CBC_256/HMAC_SHA1_96/NO_EXT_SEQ +Jun 23 08:16:12 charon-systemd[2440]: received proposals: ESP:AES_CBC_256/HMAC_SHA1_96/NO_EXT_SEQ +Jun 23 08:16:12 charon[2440]: 01[CFG] <PEER|5> configured proposals: ESP:AES_CBC_128/HMAC_SHA1_96/MODP_2048/NO_EXT_SEQ +Jun 23 08:16:12 charon-systemd[2440]: configured proposals: ESP:AES_CBC_128/HMAC_SHA1_96/MODP_2048/NO_EXT_SEQ +Jun 23 08:16:12 charon[2440]: 01[IKE] <PEER|5> no acceptable proposal found +Jun 23 08:16:12 charon-systemd[2440]: no acceptable proposal found +Jun 23 08:16:12 charon[2440]: 01[IKE] <PEER|5> failed to establish CHILD_SA, keeping IKE_SA +``` + +Encryption **AES_CBC_128** is configured in IKE policy on the responder but **AES_CBC_256** +is configured on the initiator side. + +### Prefixes in Policies Mismatch + +As in previous situation, IKE SA is in up state but IPsec SA is not up. +According to logs we can see **TS_UNACCEPTABLE** notification. It means +that prefixes (traffic selectors) mismatch on both sides + +Initiator: + +```none +Jun 23 14:13:17 charon[4996]: 11[IKE] <PEER|1> received TS_UNACCEPTABLE notify, no CHILD_SA built +Jun 23 14:13:17 charon-systemd[4996]: maximum IKE_SA lifetime 29437s +Jun 23 14:13:17 charon[4996]: 11[IKE] <PEER|1> failed to establish CHILD_SA, keeping IKE_SA +Jun 23 14:13:17 charon-systemd[4996]: received TS_UNACCEPTABLE notify, no CHILD_SA built +Jun 23 14:13:17 charon-systemd[4996]: failed to establish CHILD_SA, keeping IKE_SA +``` + +The reason of this problem is showed on the responder side. + +```none +Jun 23 14:13:19 charon[2440]: 01[IKE] <PEER|7> traffic selectors 10.0.2.0/24 === 10.0.0.0/24 unacceptable +Jun 23 14:13:19 charon-systemd[2440]: traffic selectors 10.0.2.0/24 === 10.0.0.0/24 unacceptable +Jun 23 14:13:19 charon[2440]: 01[IKE] <PEER|7> failed to establish CHILD_SA, keeping IKE_SA +Jun 23 14:13:19 charon-systemd[2440]: failed to establish CHILD_SA, keeping IKE_SA +Jun 23 14:13:19 charon[2440]: 01[ENC] <PEER|7> generating IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(TS_UNACCEPT) ] +Jun 23 14:13:19 charon-systemd[2440]: generating IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(TS_UNACCEPT) ] +``` + +Traffic selectors **10.0.2.0/24 === 10.0.0.0/24** are unacceptable on the +responder side. diff --git a/docs/configuration/vpn/md-dmvpn.md b/docs/configuration/vpn/md-dmvpn.md new file mode 100644 index 00000000..4d1525ad --- /dev/null +++ b/docs/configuration/vpn/md-dmvpn.md @@ -0,0 +1,351 @@ +(vpn-dmvpn)= + +# DMVPN + +{abbr}`DMVPN (Dynamic Multipoint Virtual Private Network)` is a dynamic +{abbr}`VPN (Virtual Private Network)` technology originally developed by Cisco. +While their implementation was somewhat proprietary, the underlying +technologies are actually standards based. The three technologies are: + +- {abbr}`NHRP (Next Hop Resolution Protocol)` {rfc}`2332` +- {abbr}`mGRE (Multipoint Generic Routing Encapsulation)` {rfc}`1702` +- {abbr}`IPSec (IP Security)` - too many RFCs to list, but start with + {rfc}`4301` + +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. +::: + +:::{figure} /_static/images/vpn_dmvpn_topology01.png +:alt: Baseline DMVPN topology +:scale: 40 % + +Baseline DMVPN topology +::: + +## Configuration + +- Please refer to the {ref}`tunnel-interface` documentation for the individual + tunnel related options. +- Please refer to the {ref}`ipsec_general` documentation for individual IPSec + related options. + +```{eval-rst} +.. cfgcmd:: set protocols nhrp tunnel <tunnel> cisco-authentication <secret> + + Enables Cisco style authentication on NHRP packets. This embeds the secret + plaintext password to the outgoing NHRP packets. Incoming NHRP packets on + this interface are discarded unless the secret password is present. Maximum + length of the secret is 8 characters. +``` + +```{eval-rst} +.. cfgcmd:: set protocols nhrp tunnel <tunnel> dynamic-map <address> + nbma-domain-name <fqdn> + + Specifies that the {abbr}`NBMA (Non-broadcast multiple-access network)` + addresses of the next hop servers are defined in the domain name + nbma-domain-name. For each A record opennhrp creates a dynamic NHS entry. + + Each dynamic NHS will get a peer entry with the configured network address + and the discovered NBMA address. + + The first registration request is sent to the protocol broadcast address, and + the server's real protocol address is dynamically detected from the first + registration reply. +``` + +```{eval-rst} +.. cfgcmd:: set protocols nhrp tunnel <tunnel> holding-time <timeout> + + Specifies the holding time for NHRP Registration Requests and Resolution + Replies sent from this interface or shortcut-target. The holdtime is specified + in seconds and defaults to two hours. +``` + +```{eval-rst} +.. cfgcmd:: set protocols nhrp tunnel <tunnel> map cisco + + If the statically mapped peer is running Cisco IOS, specify the cisco keyword. + It is used to fix statically the Registration Request ID so that a matching + Purge Request can be sent if NBMA address has changed. This is to work around + broken IOS which requires Purge Request ID to match the original Registration + Request ID. +``` + +```{eval-rst} +.. cfgcmd:: set protocols nhrp tunnel <tunnel> map nbma-address <address> + + Creates static peer mapping of protocol-address to {abbr}`NBMA (Non-broadcast + multiple-access network)` address. + + If the IP prefix mask is present, it directs opennhrp to use this peer as a + next hop server when sending Resolution Requests matching this subnet. + + This is also known as the HUBs IP address or FQDN. +``` + +```{eval-rst} +.. cfgcmd:: set protocols nhrp tunnel <tunnel> map register + + The optional parameter register specifies that Registration Request should be + sent to this peer on startup. + + This option is required when running a DMVPN spoke. +``` + +```{eval-rst} +.. cfgcmd:: set protocols nhrp tunnel <tunnel> multicast <dynamic | nhs> + + Determines how opennhrp daemon should soft switch the multicast traffic. + Currently, multicast traffic is captured by opennhrp daemon using a packet + socket, and resent back to proper destinations. This means that multicast + packet sending is CPU intensive. + + Specfying nhs makes all multicast packets to be repeated to each statically + configured next hop. + + Synamic instructs to forward to all peers which we have a direct connection + with. Alternatively, you can specify the directive multiple times for each + protocol-address the multicast traffic should be sent to. + + .. warning:: It is very easy to misconfigure multicast repeating if you have + multiple NHSes. +``` + +```{eval-rst} +.. cfgcmd:: set protocols nhrp tunnel <tunnel> non-caching + + Disables caching of peer information from forwarded NHRP Resolution Reply + packets. This can be used to reduce memory consumption on big NBMA subnets. + + .. note:: Currently does not do much as caching is not implemented. +``` + +```{eval-rst} +.. cfgcmd:: set protocols nhrp tunnel <tunnel> redirect + + Enable sending of Cisco style NHRP Traffic Indication packets. If this is + enabled and opennhrp detects a forwarded packet, it will send a message to + the original sender of the packet instructing it to create a direct connection + with the destination. This is basically a protocol independent equivalent of + ICMP redirect. +``` + +```{eval-rst} +.. cfgcmd:: set protocols nhrp tunnel <tunnel> shortcut + + Enable creation of shortcut routes. + + A received NHRP Traffic Indication will trigger the resolution and + establishment of a shortcut route. +``` + +```{eval-rst} +.. cfgcmd:: set protocols nhrp tunnel <tunnel> shortcut-destination + + This instructs opennhrp to reply with authorative answers on NHRP Resolution + Requests destinied to addresses in this interface (instead of forwarding the + packets). This effectively allows the creation of shortcut routes to subnets + located on the interface. + + When specified, this should be the only keyword for the interface. +``` + +```{eval-rst} +.. cfgcmd:: set protocols nhrp tunnel <tunnel> shortcut-target <address> + + Defines an off-NBMA network prefix for which the GRE interface will act as a + gateway. This an alternative to defining local interfaces with + shortcut-destination flag. +``` + +```{eval-rst} +.. cfgcmd:: set protocols nhrp tunnel <tunnel> shortcut-target <address> + holding-time <timeout> + + Specifies the holding time for NHRP Registration Requests and Resolution + Replies sent from this interface or shortcut-target. The holdtime is specified + in seconds and defaults to two hours. +``` + +## Example + +This blueprint uses VyOS as the DMVPN Hub and Cisco (7206VXR) and VyOS as +multiple spoke sites. The lab was built using {abbr}`EVE-NG (Emulated Virtual +Environment NG)`. + +:::{figure} /_static/images/blueprint-dmvpn.png +:alt: DMVPN network + +DMVPN example network +::: + +Each node (Hub and Spoke) uses an IP address from the network 172.16.253.128/29. + +The below referenced IP address `192.0.2.1` is used as example address +representing a global unicast address under which the HUB can be contacted by +each and every individual spoke. + +(dmvpn-example-configuration)= + +### Configuration + +#### Hub + +```none +set interfaces ethernet eth0 address 192.0.2.1/24 + +set interfaces tunnel tun100 address '172.16.253.134/29' +set interfaces tunnel tun100 encapsulation 'gre' +set interfaces tunnel tun100 local-ip '192.0.2.1' +set interfaces tunnel tun100 enable-multicast +set interfaces tunnel tun100 parameters ip key '1' + +set protocols nhrp tunnel tun100 cisco-authentication 'secret' +set protocols nhrp tunnel tun100 holding-time '300' +set protocols nhrp tunnel tun100 multicast 'dynamic' +set protocols nhrp tunnel tun100 redirect +set protocols nhrp tunnel tun100 shortcut + +set vpn ipsec esp-group ESP-HUB lifetime '1800' +set vpn ipsec esp-group ESP-HUB mode 'transport' +set vpn ipsec esp-group ESP-HUB pfs 'dh-group2' +set vpn ipsec esp-group ESP-HUB proposal 1 encryption 'aes256' +set vpn ipsec esp-group ESP-HUB proposal 1 hash 'sha1' +set vpn ipsec esp-group ESP-HUB proposal 2 encryption '3des' +set vpn ipsec esp-group ESP-HUB proposal 2 hash 'md5' +set vpn ipsec ike-group IKE-HUB key-exchange 'ikev1' +set vpn ipsec ike-group IKE-HUB lifetime '3600' +set vpn ipsec ike-group IKE-HUB proposal 1 dh-group '2' +set vpn ipsec ike-group IKE-HUB proposal 1 encryption 'aes256' +set vpn ipsec ike-group IKE-HUB proposal 1 hash 'sha1' +set vpn ipsec ike-group IKE-HUB proposal 2 dh-group '2' +set vpn ipsec ike-group IKE-HUB proposal 2 encryption 'aes128' +set vpn ipsec ike-group IKE-HUB proposal 2 hash 'sha1' + +set vpn ipsec interface 'eth0' + +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 'tun100' +set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' +set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' +``` + +:::{note} +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 official 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 + +The individual spoke configurations only differ in the local IP address on the +`tun10` interface. See the above diagram for the individual IP addresses. + +##### spoke01-spoke04 + +```none +crypto keyring DMVPN + pre-shared-key address 192.0.2.1 key secret +! +crypto isakmp policy 10 + encr aes 256 + authentication pre-share + group 2 +crypto isakmp invalid-spi-recovery +crypto isakmp keepalive 30 30 periodic +crypto isakmp profile DMVPN + keyring DMVPN + match identity address 192.0.2.1 255.255.255.255 +! +crypto ipsec transform-set DMVPN-AES256 esp-aes 256 esp-sha-hmac + mode transport +! +crypto ipsec profile DMVPN + set security-association idle-time 720 + set transform-set DMVPN-AES256 + set isakmp-profile DMVPN +! +interface Tunnel10 + ! individual spoke tunnel IP must change + ip address 172.16.253.129 255.255.255.248 + no ip redirects + ip nhrp authentication secret + ip nhrp map 172.16.253.134 192.0.2.1 + ip nhrp map multicast 192.0.2.1 + ip nhrp network-id 1 + ip nhrp holdtime 600 + ip nhrp nhs 172.16.253.134 + ip nhrp registration timeout 75 + tunnel source FastEthernet0/0 + tunnel mode gre multipoint + tunnel protection ipsec profile DMVPN + tunnel key 1 +! +interface FastEthernet0/0 + ip address dhcp + duplex half +``` + +##### spoke05 + +VyOS can also run in DMVPN spoke mode. + +```none +set interfaces ethernet eth0 address 'dhcp' + +set interfaces tunnel tun100 address '172.16.253.133/29' +set interfaces tunnel tun100 local-ip 0.0.0.0 +set interfaces tunnel tun100 encapsulation 'gre' +set interfaces tunnel tun100 enable-multicast +set interfaces tunnel tun100 parameters ip key '1' + +set protocols nhrp tunnel tun100 cisco-authentication 'secret' +set protocols nhrp tunnel tun100 holding-time '300' +set protocols nhrp tunnel tun100 map 172.16.253.134/29 nbma-address '192.0.2.1' +set protocols nhrp tunnel tun100 map 172.16.253.134/29 register +set protocols nhrp tunnel tun100 multicast 'nhs' +set protocols nhrp tunnel tun100 redirect +set protocols nhrp tunnel tun100 shortcut + +set vpn ipsec esp-group ESP-HUB lifetime '1800' +set vpn ipsec esp-group ESP-HUB mode 'transport' +set vpn ipsec esp-group ESP-HUB pfs 'dh-group2' +set vpn ipsec esp-group ESP-HUB proposal 1 encryption 'aes256' +set vpn ipsec esp-group ESP-HUB proposal 1 hash 'sha1' +set vpn ipsec esp-group ESP-HUB proposal 2 encryption '3des' +set vpn ipsec esp-group ESP-HUB proposal 2 hash 'md5' +set vpn ipsec ike-group IKE-HUB close-action 'none' +set vpn ipsec ike-group IKE-HUB key-exchange 'ikev1' +set vpn ipsec ike-group IKE-HUB lifetime '3600' +set vpn ipsec ike-group IKE-HUB proposal 1 dh-group '2' +set vpn ipsec ike-group IKE-HUB proposal 1 encryption 'aes256' +set vpn ipsec ike-group IKE-HUB proposal 1 hash 'sha1' +set vpn ipsec ike-group IKE-HUB proposal 2 dh-group '2' +set vpn ipsec ike-group IKE-HUB proposal 2 encryption 'aes128' +set vpn ipsec ike-group IKE-HUB proposal 2 hash 'sha1' + +set vpn ipsec interface 'eth0' + +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 'tun100' +set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' +set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' +``` diff --git a/docs/configuration/vpn/md-index.md b/docs/configuration/vpn/md-index.md new file mode 100644 index 00000000..92d9bfef --- /dev/null +++ b/docs/configuration/vpn/md-index.md @@ -0,0 +1,25 @@ +# VPN + +```{eval-rst} +.. toctree:: + :maxdepth: 1 + :includehidden: + + ipsec/index + l2tp + openconnect + pptp + rsa-keys + sstp + +``` + +pages to sort + +```{eval-rst} +.. toctree:: + :maxdepth: 1 + :includehidden: + + dmvpn +``` diff --git a/docs/configuration/vpn/md-l2tp.md b/docs/configuration/vpn/md-l2tp.md new file mode 100644 index 00000000..edd3146b --- /dev/null +++ b/docs/configuration/vpn/md-l2tp.md @@ -0,0 +1,685 @@ +(l2tp)= + +# L2TP + +VyOS utilizes [accel-ppp] to provide L2TP server functionality. It can be used +with local authentication or a connected RADIUS server. + +## Configuring L2TP Server + +```none +set vpn l2tp remote-access authentication mode local +set vpn l2tp remote-access authentication local-users username test password 'test' +set vpn l2tp remote-access client-ip-pool L2TP-POOL range 192.168.255.2-192.168.255.254 +set vpn l2tp remote-access default-pool 'L2TP-POOL' +set vpn l2tp remote-access outside-address 192.0.2.2 +set vpn l2tp remote-access gateway-address 192.168.255.1 +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access authentication mode <local | radius> + + Set authentication backend. The configured authentication backend is used + for all queries. + + * **radius**: All authentication queries are handled by a configured RADIUS + server. + * **local**: All authentication queries are handled locally. +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access authentication local-users username <user> password + <pass> + + Create `<user>` for local authentication on this system. The users password + will be set to `<pass>`. +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access client-ip-pool <POOL-NAME> range <x.x.x.x-x.x.x.x | x.x.x.x/x> + + Use this command to define the first IP address of a pool of + addresses to be given to l2tp clients. If notation ``x.x.x.x-x.x.x.x``, + it must be within a /24 subnet. If notation ``x.x.x.x/x`` is + used there is possibility to set host/netmask. +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access default-pool <POOL-NAME> + + Use this command to define default address pool name. +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access gateway-address <gateway> + + Specifies single `<gateway>` IP address to be used as local address of PPP + interfaces. +``` + +## Configuring IPsec + +```none +set vpn ipsec interface eth0 +set vpn l2tp remote-access ipsec-settings authentication mode pre-shared-secret +set vpn l2tp remote-access ipsec-settings authentication pre-shared-secret secret +``` + +```{eval-rst} +.. cfgcmd:: set vpn ipsec interface <INTERFACE> + + Use this command to define IPsec interface. +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access ipsec-settings authentication mode <pre-shared-secret | x509> + + Set mode for IPsec authentication between VyOS and L2TP clients. +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access ipsec-settings authentication pre-shared-secret <secret> + + Set predefined shared secret phrase. + +``` + +If a local firewall policy is in place on your external interface you will need +to allow the ports below: + +- UDP port 500 (IKE) +- IP protocol number 50 (ESP) +- UDP port 1701 for IPsec + +As well as the below to allow NAT-traversal (when NAT is detected by the +VPN client, ESP is encapsulated in UDP for NAT-traversal): + +- UDP port 4500 (NAT-T) + +Example: + +```none +set firewall ipv4 name OUTSIDE-LOCAL rule 40 action 'accept' +set firewall ipv4 name OUTSIDE-LOCAL rule 40 protocol 'esp' +set firewall ipv4 name OUTSIDE-LOCAL rule 41 action 'accept' +set firewall ipv4 name OUTSIDE-LOCAL rule 41 destination port '500' +set firewall ipv4 name OUTSIDE-LOCAL rule 41 protocol 'udp' +set firewall ipv4 name OUTSIDE-LOCAL rule 42 action 'accept' +set firewall ipv4 name OUTSIDE-LOCAL rule 42 destination port '4500' +set firewall ipv4 name OUTSIDE-LOCAL rule 42 protocol 'udp' +set firewall ipv4 name OUTSIDE-LOCAL rule 43 action 'accept' +set firewall ipv4 name OUTSIDE-LOCAL rule 43 destination port '1701' +set firewall ipv4 name OUTSIDE-LOCAL rule 43 ipsec 'match-ipsec' +set firewall ipv4 name OUTSIDE-LOCAL rule 43 protocol 'udp' +``` + +To allow VPN-clients access via your external address, a NAT rule is required: + +```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 +``` + +## Configuring RADIUS authentication + +To enable RADIUS based authentication, the authentication mode needs to be +changed within the configuration. Previous settings like the local users, still +exists within the configuration, however they are not used if the mode has been +changed from local to radius. Once changed back to local, it will use all local +accounts again. + +```none +set vpn l2tp remote-access authentication mode radius +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access authentication radius server <server> key <secret> + + Configure RADIUS `<server>` and its required shared `<secret>` for + communicating with the RADIUS server. +``` + +Since the RADIUS server would be a single point of failure, multiple RADIUS +servers can be setup and will be used subsequentially. +For example: + +```none +set vpn l2tp remote-access authentication radius server 10.0.0.1 key 'foo' +set vpn l2tp remote-access authentication radius server 10.0.0.2 key 'foo' +``` + +:::{note} +Some [RADIUS] severs use an access control list which allows or denies +queries, make sure to add your VyOS router to the allowed client list. +::: + +### RADIUS source address + +If you are using OSPF as your IGP, use the interface connected closest to the +RADIUS server. You can bind all outgoing RADIUS requests to a single source IP +e.g. the loopback interface. + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access authentication radius source-address <address> + + Source IPv4 address used in all RADIUS server queires. +``` + +:::{note} +The `source-address` must be configured to that of an interface. +Best practice would be a loopback or dummy interface. +::: + +### RADIUS advanced options + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access authentication radius server <server> port <port> + + Configure RADIUS `<server>` and its required port for authentication requests. +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access authentication radius server <server> fail-time <time> + + Mark RADIUS server as offline for this given `<time>` in seconds. +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access authentication radius server <server> disable + + Temporary disable this RADIUS server. +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access authentication radius acct-timeout <timeout> + + Timeout to wait reply for Interim-Update packets. (default 3 seconds) +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access authentication radius dynamic-author server <address> + + Specifies IP address for Dynamic Authorization Extension server (DM/CoA) +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access authentication radius dynamic-author port <port> + + Port for Dynamic Authorization Extension server (DM/CoA) +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access authentication radius dynamic-author key <secret> + + Secret for Dynamic Authorization Extension server (DM/CoA) +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access authentication radius max-try <number> + + Maximum number of tries to send Access-Request/Accounting-Request queries +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access authentication radius timeout <timeout> + + Timeout to wait response from server (seconds) +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access authentication radius nas-identifier <identifier> + + Value to send to RADIUS server in NAS-Identifier attribute and to be matched + in DM/CoA requests. +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access authentication radius nas-ip-address <address> + + Value to send to RADIUS server in NAS-IP-Address attribute and to be matched + in DM/CoA requests. Also DM/CoA server will bind to that address. +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access authentication radius source-address <address> + + Source IPv4 address used in all RADIUS server queires. +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access authentication radius rate-limit attribute <attribute> + + Specifies which RADIUS server attribute contains the rate limit information. + The default attribute is `Filter-Id`. +``` + +:::{note} +If you set a custom RADIUS attribute you must define it on both +dictionaries on the RADIUS server and client. +::: + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access authentication radius rate-limit enable + + Enables bandwidth shaping via RADIUS. +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access authentication radius rate-limit vendor + + Specifies the vendor dictionary. This dictionary needs to be present in + /usr/share/accel-ppp/radius. +``` + +Received RADIUS attributes have a higher priority than parameters defined within +the CLI configuration, refer to the explanation below. + +### Allocation clients ip addresses by RADIUS + +If the RADIUS server sends the attribute `Framed-IP-Address` then this IP +address will be allocated to the client and the option `default-pool` within +the CLI config will be ignored. + +If the RADIUS server sends the attribute `Framed-Pool`, then the IP address +will be allocated from a predefined IP pool whose name equals the attribute +value. + +If the RADIUS server sends the attribute `Stateful-IPv6-Address-Pool`, the +IPv6 address will be allocated from a predefined IPv6 pool `prefix` whose +name equals the attribute value. + +If the RADIUS server sends the attribute `Delegated-IPv6-Prefix-Pool`, an +IPv6 delegation prefix will be allocated from a predefined IPv6 pool +`delegate` whose name equals the attribute value. + +:::{note} +`Stateful-IPv6-Address-Pool` and `Delegated-IPv6-Prefix-Pool` are defined in +RFC6911. If they are not defined in your RADIUS server, add new [dictionary]. +::: + +The client's interface can be put into a VRF context via a RADIUS Access-Accept +packet, or changed via RADIUS CoA. `Accel-VRF-Name` is used for these +purposes. This is a custom [ACCEL-PPP attribute]. Define it in your RADIUS +server. + +### Renaming clients interfaces by RADIUS + +If the RADIUS server uses the attribute `NAS-Port-Id`, ppp tunnels will be +renamed. + +:::{note} +The value of the attribute `NAS-Port-Id` must be less than 16 +characters, otherwise the interface won't be renamed. +::: + +## Configuring LNS (L2TP Network Server) + +LNS are often used to connect to a LAC (L2TP Access Concentrator). + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access lns host-name <hostname> + + Sent to the client (LAC) in the Host-Name attribute +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access lns shared-secret <secret> + + Tunnel password used to authenticate the client (LAC) +``` + +To explain the usage of LNS follow our blueprint {ref}`examples-lac-lns`. + +## IPv6 + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access ppp-options ipv6 <require | prefer | allow | deny> + + Specifies IPv6 negotiation preference. + + * **require** - Require IPv6 negotiation + * **prefer** - Ask client for IPv6 negotiation, do not fail if it rejects + * **allow** - Negotiate IPv6 only if client requests + * **deny** - Do not negotiate IPv6 (default value) +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access client-ipv6-pool <IPv6-POOL-NAME> prefix <address> + mask <number-of-bits> + + Use this comand to set the IPv6 address pool from which an l2tp client will + get an IPv6 prefix of your defined length (mask) to terminate the l2tp + endpoint at their side. The mask length can be set between 48 and 128 bits + long, the default value is 64. +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access client-ipv6-pool <IPv6-POOL-NAME> delegate <address> + delegation-prefix <number-of-bits> + + Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on l2tp. + You will have to set your IPv6 pool and the length of the delegation + prefix. From the defined IPv6 pool you will be handing out networks of the + defined length (delegation-prefix). The length of the delegation prefix can + be between 32 and 64 bits long. +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access default-ipv6-pool <IPv6-POOL-NAME> + + Use this command to define default IPv6 address pool name. +``` + +```none +set vpn l2tp remote-access ppp-options ipv6 allow +set vpn l2tp remote-access client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' +set vpn l2tp remote-access client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' +set vpn l2tp remote-access default-ipv6-pool IPv6-POOL +``` + +### IPv6 Advanced Options + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access ppp-options ipv6-accept-peer-interface-id + + Accept peer interface identifier. By default this is not defined. +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access ppp-options ipv6-interface-id <random | x:x:x:x> + + Specifies if a fixed or random interface identifier is used for IPv6. The + default is fixed. + + * **random** - Random interface identifier for IPv6 + * **x:x:x:x** - Specify interface identifier for IPv6 +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access ppp-options ipv6-interface-id <random | x:x:x:x> + + Specifies the peer interface identifier for IPv6. The default is fixed. + + * **random** - Random interface identifier for IPv6 + * **x:x:x:x** - Specify interface identifier for IPv6 + * **ipv4-addr** - Calculate interface identifier from IPv4 address. + * **calling-sid** - Calculate interface identifier from calling-station-id. +``` + +## Scripting + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access extended-scripts on-change <path_to_script> + + Script to run when the session interface is changed by RADIUS CoA handling +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access extended-scripts on-down <path_to_script> + + Script to run when the session interface is about to terminate +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access extended-scripts on-pre-up <path_to_script> + + Script to run before the session interface comes up +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access extended-scripts on-up <path_to_script> + + Script to run when the session interface is completely configured and started +``` + +## Advanced Options + +### Authentication Advanced Options + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access authentication local-users username <user> disable + + Disable `<user>` account. +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access authentication local-users username <user> static-ip + <address> + + Assign a static IP address to `<user>` account. +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access authentication local-users username <user> rate-limit + download <bandwidth> + + Rate limit the download bandwidth for `<user>` to `<bandwidth>` kbit/s. +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access authentication local-users username <user> rate-limit + upload <bandwidth> + + Rate limit the upload bandwidth for `<user>` to `<bandwidth>` kbit/s +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access authentication protocols + <pap | chap | mschap | mschap-v2> + + Require the peer to authenticate itself using one of the following protocols: + pap, chap, mschap, mschap-v2. +``` + +### Client IP Pool Advanced Options + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access client-ip-pool <POOL-NAME> next-pool <NEXT-POOL-NAME> + + Use this command to define the next address pool name. +``` + +### PPP Advanced Options + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access ppp-options disable-ccp + + Disable Compression Control Protocol (CCP). + CCP is enabled by default. +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access ppp-options interface-cache <number> + + Specifies number of interfaces to cache. This prevents interfaces from being + removed once the corresponding session is destroyed. Instead, interfaces are + cached for later use in new sessions. This should reduce the kernel-level + interface creation/deletion rate. + Default value is **0**. +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access ppp-options ipv4 <require | prefer | allow | deny> + + Specifies IPv4 negotiation preference. + + * **require** - Require IPv4 negotiation + * **prefer** - Ask client for IPv4 negotiation, do not fail if it rejects + * **allow** - Negotiate IPv4 only if client requests (Default value) + * **deny** - Do not negotiate IPv4 +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access ppp-options lcp-echo-failure <number> + + Defines the maximum `<number>` of unanswered echo requests. Upon reaching the + value `<number>`, the session will be reset. Default value is **3**. +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access ppp-options lcp-echo-interval <interval> + + If this option is specified and is greater than 0, then the PPP module will + send LCP echo requests every `<interval>` seconds. + Default value is **30**. +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access ppp-options lcp-echo-timeout + + Specifies timeout in seconds to wait for any peer activity. If this option is + specified it turns on adaptive lcp echo functionality and "lcp-echo-failure" + is not used. Default value is **0**. +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access ppp-options min-mtu <number> + + Defines the minimum acceptable MTU. If a client tries to negotiate an MTU + lower than this it will be NAKed, and disconnected if it rejects a greater + MTU. + Default value is **100**. +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access ppp-options mppe <require | prefer | deny> + + Specifies {abbr}`MPPE (Microsoft Point-to-Point Encryption)` negotiation + preference. + + * **require** - ask client for mppe, if it rejects drop connection + * **prefer** - ask client for mppe, if it rejects don't fail. (Default value) + * **deny** - deny mppe + + Default behavior - don't ask the client for mppe, but allow it if the client + wants. + Please note that RADIUS may override this option with the + MS-MPPE-Encryption-Policy attribute. +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access ppp-options mru <number> + + Defines preferred MRU. By default is not defined. +``` + +### Global Advanced options + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access description <description> + + Set description. +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access limits burst <value> + + Burst count +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access limits connection-limit <value> + + Maximum accepted connection rate (e.g. 1/min, 60/sec) +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access limits timeout <value> + + Timeout in seconds +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access mtu + + Maximum Transmission Unit (MTU) (default: **1436**) +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access max-concurrent-sessions + + Maximum number of concurrent session start attempts +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access name-server <address> + + Connected clients should use `<address>` as their DNS server. This command + accepts both IPv4 and IPv6 addresses. Up to two nameservers can be configured + for IPv4, up to three for IPv6. +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access shaper fwmark <1-2147483647> + + Match firewall mark value +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access snmp master-agent + + Enable SNMP +``` + +```{eval-rst} +.. cfgcmd:: set vpn l2tp remote-access wins-server <address> + + Windows Internet Name Service (WINS) servers propagated to client +``` + +## Monitoring + +```none +vyos@vyos:~$ show l2tp-server sessions + ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes +--------+----------+---------------+-----+--------+-------------+------------+--------+----------+----------+---------- + l2tp0 | test | 192.168.255.3 | | | 192.168.0.36 | | active | 02:01:47 | 7.7 KiB | 1.2 KiB +``` + +```none +vyos@vyos:~$ show l2tp-server statistics + uptime: 0.02:49:49 +cpu: 0% +mem(rss/virt): 5920/100892 kB +core: + mempool_allocated: 133202 + mempool_available: 131770 + thread_count: 1 + thread_active: 1 + context_count: 5 + context_sleeping: 0 + context_pending: 0 + md_handler_count: 3 + md_handler_pending: 0 + timer_count: 0 + timer_pending: 0 +sessions: + starting: 0 + active: 0 + finishing: 0 +l2tp: + tunnels: + starting: 0 + active: 0 + finishing: 0 + sessions (control channels): + starting: 0 + active: 0 + finishing: 0 + sessions (data channels): + starting: 0 + active: 0 + finishing: 0 +``` + +[accel-ppp]: https://accel-ppp.org/ +[accel-ppp attribute]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel +[cloudflare]: https://blog.cloudflare.com/announcing-1111 +[dictionary]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911 +[freeradius]: https://freeradius.org +[google public dns]: https://developers.google.com/speed/public-dns +[network policy server]: https://en.wikipedia.org/wiki/Network_Policy_Server +[opennic]: https://www.opennic.org/ +[quad9]: https://quad9.net +[radius]: https://en.wikipedia.org/wiki/RADIUS diff --git a/docs/configuration/vpn/md-openconnect.md b/docs/configuration/vpn/md-openconnect.md new file mode 100644 index 00000000..d7352a39 --- /dev/null +++ b/docs/configuration/vpn/md-openconnect.md @@ -0,0 +1,291 @@ +(vpn-openconnect)= + +# OpenConnect + +OpenConnect-compatible server feature has been available since Equuleus (1.3). +Openconnect VPN supports SSL connection and offers full network access. SSL VPN +network extension connects the end-user system to the corporate network with +access controls based only on network layer information, such as destination IP +address and port number. So, it provides safe communication for all types of +device traffic across public networks and private networks, also encrypts the +traffic with SSL protocol. + +The remote user will use the openconnect client to connect to the router and +will receive an IP address from a VPN pool, allowing full access to the +network. + +## Configuration + +### SSL Certificates + +We need to generate the certificate which authenticates users who attempt to +access the network resource through the SSL VPN tunnels. The following commands +will create a self signed certificates and will be stored in configuration: + +```none +run generate pki ca install <CA name> +run generate pki certificate sign <CA name> install <Server name> +``` + +We can also create the certificates using Certbot which is an easy-to-use +client that fetches a certificate from Let's Encrypt an open certificate +authority launched by the EFF, Mozilla, and others and deploys it to a web +server. + +```none +sudo certbot certonly --standalone --preferred-challenges http -d <domain name> +``` + +### Server Configuration + +```none +set vpn openconnect authentication local-users username <user> password <pass> +set vpn openconnect authentication mode <local password|radius> +set vpn openconnect network-settings client-ip-settings subnet <subnet> +set vpn openconnect network-settings name-server <address> +set vpn openconnect network-settings name-server <address> +set vpn openconnect ssl ca-certificate <pki-ca-name> +set vpn openconnect ssl certificate <pki-cert-name> +set vpn openconnect ssl passphrase <pki-password> +``` + +### 2FA OTP support + +Instead of password only authentication, 2FA password +authentication + OTP key can be used. Alternatively, OTP authentication only, +without a password, can be used. +To do this, an OTP configuration must be added to the configuration above: + +```none +set vpn openconnect authentication mode local <password-otp|otp> +set vpn openconnect authentication local-users username <user> otp <key> +set vpn openconnect authentication local-users username <user> interval <interval (optional)> +set vpn openconnect authentication local-users username <user> otp-length <otp-length (optional)> +set vpn openconnect authentication local-users username <user> token-type <token-type (optional)> +``` + +For generating an OTP key in VyOS, you can use the CLI command +(operational mode): + +```none +generate openconnect username <user> otp-key hotp-time +``` + +## Verification + +```none +vyos@vyos:~$ sh openconnect-server sessions +interface username ip remote IP RX TX state uptime +----------- ---------- ------------- ----------- ------- --------- --------- -------- +sslvpn0 tst 172.20.20.198 192.168.6.1 0 bytes 152 bytes connected 3s +``` + +:::{note} +It is compatible with Cisco (R) AnyConnect (R) clients. +::: + +## Example + +### SSL Certificates generation + +Follow the instructions to generate CA cert (in configuration mode): + +```none +vyos@vyos# run generate pki ca install ca-ocserv +Enter private key type: [rsa, dsa, ec] (Default: rsa) +Enter private key bits: (Default: 2048) +Enter country code: (Default: GB) US +Enter state: (Default: Some-State) Delaware +Enter locality: (Default: Some-City) Mycity +Enter organization name: (Default: VyOS) MyORG +Enter common name: (Default: vyos.io) oc-ca +Enter how many days certificate will be valid: (Default: 1825) 3650 +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] N +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +[edit] +``` + +Follow the instructions to generate server cert (in configuration mode): + +```none +vyos@vyos# run generate pki certificate sign ca-ocserv install srv-ocserv +Do you already have a certificate request? [y/N] N +Enter private key type: [rsa, dsa, ec] (Default: rsa) +Enter private key bits: (Default: 2048) +Enter country code: (Default: GB) US +Enter state: (Default: Some-State) Delaware +Enter locality: (Default: Some-City) Mycity +Enter organization name: (Default: VyOS) MyORG +Enter common name: (Default: vyos.io) oc-srv +Do you want to configure Subject Alternative Names? [y/N] N +Enter how many days certificate will be valid: (Default: 365) 1830 +Enter certificate type: (client, server) (Default: server) +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] N +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +[edit] +``` + +Each of the install command should be applied to the configuration and commited +before using under the openconnect configuration: + +```none +vyos@vyos# commit +[edit] +vyos@vyos# save +Saving configuration to '/config/config.boot'... +Done +[edit] +``` + +### Openconnect Configuration + +Simple setup with one user added and password authentication: + +```none +set vpn openconnect authentication local-users username tst password 'OC_bad_Secret' +set vpn openconnect authentication mode local password +set vpn openconnect network-settings client-ip-settings subnet '172.20.20.0/24' +set vpn openconnect network-settings name-server '10.1.1.1' +set vpn openconnect network-settings name-server '10.1.1.2' +set vpn openconnect ssl ca-certificate 'ca-ocserv' +set vpn openconnect ssl certificate 'srv-ocserv' +``` + +### Adding a 2FA with an OTP-key + +First the OTP keys must be generated and sent to the user and to the +configuration: + +```none +vyos@vyos:~$ generate openconnect username tst otp-key hotp-time +# You can share it with the user, he just needs to scan the QR in his OTP app +# username: tst +# OTP KEY: 5PA4SGYTQSGOBO3H3EQSSNCUNZAYAPH2 +# OTP URL: otpauth://totp/tst@vyos?secret=5PA4SGYTQSGOBO3H3EQSSNCUNZAYAPH2&digits=6&period=30 +█████████████████████████████████████████ +█████████████████████████████████████████ +████ ▄▄▄▄▄ █▀ ██▄▀ ▄█▄▀▀▄▄▄▄██ ▄▄▄▄▄ ████ +████ █ █ █▀ █▄▄▀▀▀▄█ ▄▄▀▄ █ █ █ ████ +████ █▄▄▄█ █▀█▀▄▄▀ ▄▀ █▀ ▀▄██ █▄▄▄█ ████ +████▄▄▄▄▄▄▄█▄█▄▀ ▀▄█ ▀ ▀ ▀ █▄█▄▄▄▄▄▄▄████ +████ ▄▄▄▀▄▄ ▄███▀▄▀█▄██▀ ▀▄ ▀▄█ ▀ ▀████ +████ ▀▀ ▀ ▄█▄ ▀ ▀▄ ▄█▀ ▄█ ▄▀▀▄██ █████ +████▄ █▄▀▀▄█▀ ▀█▄█▄▄▄▄ ▄▀█▀▀█ ▀ ▄ ▀█▀████ +█████ ▀█▀▄▄ █ ▀▄▄ ▄█▄ ▀█▀▀ █▀ ▄█████ +████▀██▀█▄▄ ▀▀▀▀█▄▀ ▀█▄▄▀▀▀ ▀ ▀█▄██▀▀████ +████▄ ▄ ▄▀▄██▀█ ▄ ▀▄██ ▄▄ ▀▀▄█▄██ ▄█████ +████▀▀ ▄▀ ▄ ▀█▀█▀█ █▀█▄▄▀█▀█▄██▄▄█ ▀████ +████ █ ▀█▄▄█▄ ▀ ▄▄▀▀ ▀ █▄█▀████ █▀ ▀████ +████▄██▄██▄█▀ ▄▀ ▄▄▀▄ ▄▀█ ▄ ▄▄▄ ▀█▄ ████ +████ ▄▄▄▄▄ █▄ ▀█▄█ ▄ ▀ ▄ ▄ █▄█ ▄▀▄█████ +████ █ █ █ ▀▄██▄▄▀█▄▀▄██▄▀ ▄ ▀██▀████ +████ █▄▄▄█ █ ██▀▄▄ ▀▄▄▀█▀ ▀█ ▄▀█ ▀██████ +████▄▄▄▄▄▄▄█▄███▄███▄█▄▄▄▄█▄▄█▄██▄█▄█████ +█████████████████████████████████████████ +█████████████████████████████████████████ +# To add this OTP key to configuration, run the following commands: +set vpn openconnect authentication local-users username tst otp key 'ebc1c91b13848ce0bb67d9212934546e41803cfa' +``` + +Next it is necessary to configure 2FA for OpenConnect: + +```none +set vpn openconnect authentication mode local password-otp +set vpn openconnect authentication local-users username tst otp key 'ebc1c91b13848ce0bb67d9212934546e41803cfa' +``` + +Now when connecting the user will first be asked for the password +and then the OTP key. + +:::{warning} +When using Time-based one-time password (TOTP) (OTP HOTP-time), +be sure that the time on the server and the +OTP token generator are synchronized by NTP +::: + +To display the configured OTP user settings, use the command: + +```none +show openconnect-server user <username> otp <full|key-b32|key-hex|qrcode|uri> +``` + +### Identity Based Configuration + +OpenConnect supports a subset of it's configuration options to be applied on a +per user/group basis, for configuration purposes we refer to this functionality +as "Identity based config". The following [OpenConnect Server Manual](https://ocserv.gitlab.io/www/manual.html#:~:text=Configuration%20files%20that%20will%20be%20applied%20per%20user%20connection%20or%0A%23%20per%20group) +outlines the set of configuration options that are allowed. This can be +leveraged to apply different sets of configs to different users or groups of +users. + +```none +sudo mkdir -p /config/auth/ocserv/config-per-user +sudo touch /config/auth/ocserv/default-user.conf + +set vpn set vpn openconnect authentication identity-based-config mode user +set vpn openconnect authentication identity-based-config directory /config/auth/ocserv/config-per-user +set vpn openconnect authentication identity-based-config default-config /config/auth/ocserv/default-user.conf +``` + +:::{warning} +The above directory and default-config must be a child directory +of /config/auth, since files outside this directory are not persisted after an +image upgrade. +::: + +Once you commit the above changes you can create a config file in the +/config/auth/ocserv/config-per-user directory that matches a username of a +user you have created e.g. "tst". Now when logging in with the "tst" user the +config options you set in this file will be loaded. + +Be sure to set a sane default config in the default config file, this will be +loaded in the case that a user is authenticated and no file is found in the +configured directory matching the users username/group. + +```none +sudo nano /config/auth/ocserv/config-per-user/tst +``` + +The same configuration options apply when Identity based config is configured +in group mode except that group mode can only be used with RADIUS +authentication. + +:::{warning} +OpenConnect server matches the filename in a case sensitive +manner, make sure the username/group name you configure matches the +filename exactly. +::: + +### Configuring RADIUS accounting + +OpenConnect can be configured to send accounting information to a +RADIUS server to capture user session data such as time of +connect/disconnect, data transferred, and so on. + +Configure an accounting server and enable accounting with: + +```none +set vpn openconnect accounting mode radius +set vpn openconnect accounting radius server 172.20.20.10 +set vpn openconnect accounting radius server 172.20.20.10 port 1813 +set vpn openconnect accounting radius server 172.20.20.10 key your_radius_secret +``` + +:::{warning} +The RADIUS accounting feature must be used with the OpenConnect +authentication mode RADIUS. It cannot be used with local authentication. +You must configure the OpenConnect authentication mode to "radius". +::: + +An example of the data captured by a FREERADIUS server with sql accounting: + +```none +mysql> SELECT username, nasipaddress, acctstarttime, acctstoptime, acctinputoctets, acctoutputoctets, callingstationid, framedipaddress, connectinfo_start FROM radacct; ++----------+---------------+---------------------+---------------------+-----------------+------------------+-------------------+-----------------+-----------------------------------+ +| username | nasipaddress | acctstarttime | acctstoptime | acctinputoctets | acctoutputoctets | callingstationid | framedipaddress | connectinfo_start | ++----------+---------------+---------------------+---------------------+-----------------+------------------+-------------------+-----------------+-----------------------------------+ +| test | 198.51.100.15 | 2023-01-13 00:59:15 | 2023-01-13 00:59:21 | 10606 | 152 | 192.168.6.1 | 172.20.20.198 | Open AnyConnect VPN Agent v8.05-1 | ++----------+---------------+---------------------+---------------------+-----------------+------------------+-------------------+-----------------+-----------------------------------+ +``` diff --git a/docs/configuration/vpn/md-pptp.md b/docs/configuration/vpn/md-pptp.md new file mode 100644 index 00000000..030d4bbf --- /dev/null +++ b/docs/configuration/vpn/md-pptp.md @@ -0,0 +1,656 @@ +(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. + +## Configuring PPTP Server + +```none +set vpn pptp remote-access authentication mode local +set vpn pptp remote-access authentication local-users username test password 'test' +set vpn pptp remote-access client-ip-pool PPTP-POOL range 192.168.255.2-192.168.255.254 +set vpn pptp remote-access default-pool 'PPTP-POOL' +set vpn pptp remote-access outside-address 192.0.2.2 +set vpn pptp remote-access gateway-address 192.168.255.1 +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access authentication mode <local | radius> + + Set authentication backend. The configured authentication backend is used + for all queries. + + * **radius**: All authentication queries are handled by a configured RADIUS + server. + * **local**: All authentication queries are handled locally. + * **noauth**: Authentication disabled. +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access authentication local-users username <user> password + <pass> + + Create `<user>` for local authentication on this system. The users password + will be set to `<pass>`. +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access client-ip-pool <POOL-NAME> range <x.x.x.x-x.x.x.x | x.x.x.x/x> + + Use this command to define the first IP address of a pool of + addresses to be given to PPTP clients. If notation ``x.x.x.x-x.x.x.x``, + it must be within a /24 subnet. If notation ``x.x.x.x/x`` is + used there is possibility to set host/netmask. +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access default-pool <POOL-NAME> + + Use this command to define default address pool name. +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access gateway-address <gateway> + + Specifies single `<gateway>` IP address to be used as local address of PPP + interfaces. +``` + +## Configuring RADIUS authentication + +To enable RADIUS based authentication, the authentication mode needs to be +changed within the configuration. Previous settings like the local users, still +exists within the configuration, however they are not used if the mode has been +changed from local to radius. Once changed back to local, it will use all local +accounts again. + +```none +set vpn pptp remote-access authentication mode radius +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access authentication radius server <server> key <secret> + + Configure RADIUS `<server>` and its required shared `<secret>` for + communicating with the RADIUS server. +``` + +Since the RADIUS server would be a single point of failure, multiple RADIUS +servers can be setup and will be used subsequentially. +For example: + +```none +set vpn pptp remote-access authentication radius server 10.0.0.1 key 'foo' +set vpn pptp remote-access authentication radius server 10.0.0.2 key 'foo' +``` + +:::{note} +Some RADIUS severs use an access control list which allows or denies +queries, make sure to add your VyOS router to the allowed client list. +::: + +### RADIUS source address + +If you are using OSPF as IGP, always the closest interface connected to the +RADIUS server is used. You can bind all outgoing RADIUS requests +to a single source IP e.g. the loopback interface. + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access authentication radius source-address <address> + + Source IPv4 address used in all RADIUS server queires. +``` + +:::{note} +The `source-address` must be configured on one of VyOS interface. +Best practice would be a loopback or dummy interface. +::: + +### RADIUS advanced options + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access authentication radius server <server> port <port> + + Configure RADIUS `<server>` and its required port for authentication requests. +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access authentication radius server <server> fail-time <time> + + Mark RADIUS server as offline for this given `<time>` in seconds. +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access authentication radius server <server> disable + + Temporary disable this RADIUS server. +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access authentication radius acct-timeout <timeout> + + Timeout to wait reply for Interim-Update packets. (default 3 seconds) +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access authentication radius dynamic-author server <address> + + Specifies IP address for Dynamic Authorization Extension server (DM/CoA) +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access authentication radius dynamic-author port <port> + + Port for Dynamic Authorization Extension server (DM/CoA) +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access authentication radius dynamic-author key <secret> + + Secret for Dynamic Authorization Extension server (DM/CoA) +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access authentication radius max-try <number> + + Maximum number of tries to send Access-Request/Accounting-Request queries +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access authentication radius timeout <timeout> + + Timeout to wait response from server (seconds) +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access authentication radius nas-identifier <identifier> + + Value to send to RADIUS server in NAS-Identifier attribute and to be matched + in DM/CoA requests. +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access authentication radius nas-ip-address <address> + + Value to send to RADIUS server in NAS-IP-Address attribute and to be matched + in DM/CoA requests. Also DM/CoA server will bind to that address. +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access authentication radius source-address <address> + + Source IPv4 address used in all RADIUS server queires. +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access authentication radius rate-limit attribute <attribute> + + Specifies which RADIUS server attribute contains the rate limit information. + The default attribute is `Filter-Id`. +``` + +:::{note} +If you set a custom RADIUS attribute you must define it on both +dictionaries at RADIUS server and client. +::: + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access authentication radius rate-limit enable + + Enables bandwidth shaping via RADIUS. +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access authentication radius rate-limit vendor + + Specifies the vendor dictionary, dictionary needs to be in + /usr/share/accel-ppp/radius. +``` + +Received RADIUS attributes have a higher priority than parameters defined within +the CLI configuration, refer to the explanation below. + +### Allocation clients ip addresses by RADIUS + +If the RADIUS server sends the attribute `Framed-IP-Address` then this IP +address will be allocated to the client and the option `default-pool` within the CLI +config is being ignored. + +If the RADIUS server sends the attribute `Framed-Pool`, IP address will be allocated +from a predefined IP pool whose name equals the attribute value. + +If the RADIUS server sends the attribute `Stateful-IPv6-Address-Pool`, IPv6 address +will be allocated from a predefined IPv6 pool `prefix` whose name equals the attribute value. + +If the RADIUS server sends the attribute `Delegated-IPv6-Prefix-Pool`, IPv6 +delegation pefix will be allocated from a predefined IPv6 pool `delegate` +whose name equals the attribute value. + +:::{note} +`Stateful-IPv6-Address-Pool` and `Delegated-IPv6-Prefix-Pool` are defined in +RFC6911. If they are not defined in your RADIUS server, add new [dictionary]. +::: + +User interface can be put to VRF context via RADIUS Access-Accept packet, or change +it via RADIUS CoA. `Accel-VRF-Name` is used from these purposes. It is custom [ACCEL-PPP attribute]. +Define it in your RADIUS server. + +### Renaming clients interfaces by RADIUS + +If the RADIUS server uses the attribute `NAS-Port-Id`, ppp tunnels will be +renamed. + +:::{note} +The value of the attribute `NAS-Port-Id` must be less than 16 +characters, otherwise the interface won't be renamed. +::: + +## IPv6 + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access ppp-options ipv6 <require | prefer | allow | deny> + + Specifies IPv6 negotiation preference. + + * **require** - Require IPv6 negotiation + * **prefer** - Ask client for IPv6 negotiation, do not fail if it rejects + * **allow** - Negotiate IPv6 only if client requests + * **deny** - Do not negotiate IPv6 (default value) +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access client-ipv6-pool <IPv6-POOL-NAME> prefix <address> + mask <number-of-bits> + + Use this comand to set the IPv6 address pool from which an PPTP client + will get an IPv6 prefix of your defined length (mask) to terminate the + PPTP endpoint at their side. The mask length can be set from 48 to 128 + bit long, the default value is 64. +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access client-ipv6-pool <IPv6-POOL-NAME> delegate <address> + delegation-prefix <number-of-bits> + + Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on + PPTP. You will have to set your IPv6 pool and the length of the + delegation prefix. From the defined IPv6 pool you will be handing out + networks of the defined length (delegation-prefix). The length of the + delegation prefix can be set from 32 to 64 bit long. +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access default-ipv6-pool <IPv6-POOL-NAME> + + Use this command to define default IPv6 address pool name. +``` + +```none +set vpn pptp remote-access ppp-options ipv6 allow +set vpn pptp remote-access client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' +set vpn pptp remote-access client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' +set vpn pptp remote-access default-ipv6-pool IPv6-POOL +``` + +### IPv6 Advanced Options + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access ppp-options ipv6-accept-peer-interface-id + + Accept peer interface identifier. By default is not defined. +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access ppp-options ipv6-interface-id <random | x:x:x:x> + + Specifies fixed or random interface identifier for IPv6. + By default is fixed. + + * **random** - Random interface identifier for IPv6 + * **x:x:x:x** - Specify interface identifier for IPv6 +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access ppp-options ipv6-interface-id <random | x:x:x:x> + + Specifies peer interface identifier for IPv6. By default is fixed. + + * **random** - Random interface identifier for IPv6 + * **x:x:x:x** - Specify interface identifier for IPv6 + * **ipv4-addr** - Calculate interface identifier from IPv4 address. + * **calling-sid** - Calculate interface identifier from calling-station-id. +``` + +## Scripting + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access extended-scripts on-change <path_to_script> + + Script to run when session interface changed by RADIUS CoA handling +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access extended-scripts on-down <path_to_script> + + Script to run when session interface going to terminate +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access extended-scripts on-pre-up <path_to_script> + + Script to run before session interface comes up +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access extended-scripts on-up <path_to_script> + + Script to run when session interface is completely configured and started +``` + +## Advanced Options + +### Authentication Advanced Options + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access authentication local-users username <user> disable + + Disable `<user>` account. +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access authentication local-users username <user> static-ip + <address> + + Assign static IP address to `<user>` account. +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access authentication local-users username <user> rate-limit + download <bandwidth> + + Download bandwidth limit in kbit/s for `<user>`. +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access authentication local-users username <user> rate-limit + upload <bandwidth> + + Upload bandwidth limit in kbit/s for `<user>`. +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access authentication protocols + <pap | chap | mschap | mschap-v2> + + Require the peer to authenticate itself using one of the following protocols: + pap, chap, mschap, mschap-v2. +``` + +### Client IP Pool Advanced Options + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access client-ip-pool <POOL-NAME> next-pool <NEXT-POOL-NAME> + + Use this command to define the next address pool name. +``` + +### PPP Advanced Options + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access ppp-options disable-ccp + + Disable Compression Control Protocol (CCP). + CCP is enabled by default. +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access ppp-options interface-cache <number> + + Specifies number of interfaces to keep in cache. It means that don’t + destroy interface after corresponding session is destroyed, instead + place it to cache and use it later for new sessions repeatedly. + This should reduce kernel-level interface creation/deletion rate lack. + Default value is **0**. +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access ppp-options ipv4 <require | prefer | allow | deny> + + Specifies IPv4 negotiation preference. + + * **require** - Require IPv4 negotiation + * **prefer** - Ask client for IPv4 negotiation, do not fail if it rejects + * **allow** - Negotiate IPv4 only if client requests (Default value) + * **deny** - Do not negotiate IPv4 +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access ppp-options lcp-echo-failure <number> + + Defines the maximum `<number>` of unanswered echo requests. Upon reaching the + value `<number>`, the session will be reset. Default value is **3**. +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access ppp-options lcp-echo-interval <interval> + + If this option is specified and is greater than 0, then the PPP module will + send LCP pings of the echo request every `<interval>` seconds. + Default value is **30**. +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access ppp-options lcp-echo-timeout + + Specifies timeout in seconds to wait for any peer activity. If this option + specified it turns on adaptive lcp echo functionality and "lcp-echo-failure" + is not used. Default value is **0**. +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access ppp-options min-mtu <number> + + Defines minimum acceptable MTU. If client will try to negotiate less then + specified MTU then it will be NAKed or disconnected if rejects greater MTU. + Default value is **100**. +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access ppp-options mppe <require | prefer | deny> + + Specifies {abbr}`MPPE (Microsoft Point-to-Point Encryption)` negotiation + preference. + + * **require** - ask client for mppe, if it rejects drop connection + * **prefer** - ask client for mppe, if it rejects don't fail. (Default value) + * **deny** - deny mppe + + Default behavior - don't ask client for mppe, but allow it if client wants. + Please note that RADIUS may override this option by MS-MPPE-Encryption-Policy + attribute. +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access ppp-options mru <number> + + Defines preferred MRU. By default is not defined. +``` + +### Global Advanced options + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access description <description> + + Set description. +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access limits burst <value> + + Burst count +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access limits connection-limit <value> + + Acceptable rate of connections (e.g. 1/min, 60/sec) +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access limits timeout <value> + + Timeout in seconds +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access mtu + + Maximum Transmission Unit (MTU) (default: **1436**) +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access max-concurrent-sessions + + Maximum number of concurrent session start attempts +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access name-server <address> + + Connected client should use `<address>` as their DNS server. This + command accepts both IPv4 and IPv6 addresses. Up to two nameservers + can be configured for IPv4, up to three for IPv6. +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access shaper fwmark <1-2147483647> + + Match firewall mark value +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access snmp master-agent + + Enable SNMP +``` + +```{eval-rst} +.. cfgcmd:: set vpn pptp remote-access wins-server <address> + + Windows Internet Name Service (WINS) servers propagated to client +``` + +## Monitoring + +```{eval-rst} +.. opcmd:: show pptp-server sessions + + Use this command to locally check the active sessions in the PPTP + server. +``` + +```none +vyos@vyos:~$ show pptp-server sessions + ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes +--------+----------+----------+-----+--------+----------------+------------+--------+----------+----------+---------- + pptp0 | test | 10.0.0.2 | | | 192.168.10.100 | | active | 00:01:26 | 6.9 KiB | 220 B +``` + +```none +vyos@vyos:~$ show pptp-server statistics + uptime: 0.00:04:52 +cpu: 0% +mem(rss/virt): 5504/100176 kB +core: + mempool_allocated: 152007 + mempool_available: 149007 + thread_count: 1 + thread_active: 1 + context_count: 6 + context_sleeping: 0 + context_pending: 0 + md_handler_count: 6 + md_handler_pending: 0 + timer_count: 2 + timer_pending: 0 +sessions: + starting: 0 + active: 1 + finishing: 0 +pptp: + starting: 0 + active: 1 +``` + +## Troubleshooting + +```none +vyos@vyos:~$sudo journalctl -u accel-ppp@pptp -b 0 + +Feb 29 14:58:57 vyos accel-pptp[4629]: pptp: new connection from 192.168.10.100 +Feb 29 14:58:57 vyos accel-pptp[4629]: :: recv [PPTP Start-Ctrl-Conn-Request <Version 1> <Framing 1> <Bearer 1> <Max-Chan 0>] +Feb 29 14:58:57 vyos accel-pptp[4629]: :: send [PPTP Start-Ctrl-Conn-Reply <Version 1> <Result 1> <Error 0> <Framing 3> <Bearer 3> <Max-Chan 1>] +Feb 29 14:58:57 vyos accel-pptp[4629]: :: recv [PPTP Outgoing-Call-Request <Call-ID 2961> <Call-Serial 2> <Min-BPS 300> <Max-BPS 100000000> <Bearer 3> <Framing 3> <Window-Size 64> <Delay 0>] +Feb 29 14:58:57 vyos accel-pptp[4629]: :: send [PPTP Outgoing-Call-Reply <Call-ID 2> <Peer-Call-ID 2961> <Result 1> <Error 0> <Cause 0> <Speed 100000000> <Window-Size 64> <Delay 0> <Channel 0>] +Feb 29 14:58:57 vyos accel-pptp[4629]: :: lcp_layer_init +Feb 29 14:58:57 vyos accel-pptp[4629]: :: auth_layer_init +Feb 29 14:58:57 vyos accel-pptp[4629]: :: ccp_layer_init +Feb 29 14:58:57 vyos accel-pptp[4629]: :: ipcp_layer_init +Feb 29 14:58:57 vyos accel-pptp[4629]: :: ipv6cp_layer_init +Feb 29 14:58:57 vyos accel-pptp[4629]: :: ppp establishing +Feb 29 14:58:57 vyos accel-pptp[4629]: :: lcp_layer_start +Feb 29 14:58:57 vyos accel-pptp[4629]: :: send [LCP ConfReq id=75 <auth PAP> <mru 1436> <magic 483920bd>] +Feb 29 14:58:57 vyos accel-pptp[4629]: :: recv [PPTP Set-Link-Info] +Feb 29 14:58:57 vyos accel-pptp[4629]: :: recv [LCP ConfReq id=0 <mru 1400> <magic 0142785a> <pcomp> <accomp> < d 3 6 >] +Feb 29 14:58:57 vyos accel-pptp[4629]: :: send [LCP ConfRej id=0 <pcomp> <accomp> < d 3 6 >] +Feb 29 14:58:57 vyos accel-pptp[4629]: :: recv [LCP ConfReq id=1 <mru 1400> <magic 0142785a>] +Feb 29 14:58:57 vyos accel-pptp[4629]: :: send [LCP ConfAck id=1] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: fsm timeout 9 +Feb 29 14:59:00 vyos accel-pptp[4629]: :: send [LCP ConfReq id=75 <auth PAP> <mru 1436> <magic 483920bd>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP ConfNak id=75 <auth MSCHAP-v2>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: send [LCP ConfReq id=76 <auth CHAP-md5> <mru 1436> <magic 483920bd>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP ConfNak id=76 <auth MSCHAP-v2>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: send [LCP ConfReq id=77 <auth MSCHAP-v1> <mru 1436> <magic 483920bd>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP ConfNak id=77 <auth MSCHAP-v2>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: send [LCP ConfReq id=78 <auth MSCHAP-v2> <mru 1436> <magic 483920bd>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP ConfAck id=78 <auth MSCHAP-v2> <mru 1436> <magic 483920bd>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: lcp_layer_started +Feb 29 14:59:00 vyos accel-pptp[4629]: :: auth_layer_start +Feb 29 14:59:00 vyos accel-pptp[4629]: :: send [MSCHAP-v2 Challenge id=1 <8aa758781676e6a8e85c11963ee010>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP Ident id=2 <MSRASV5.20>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP Ident id=3 <MSRAS-0-MSEDGEWIN10>] +Feb 29 14:59:00 vyos accel-pptp[4629]: [43B blob data] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [PPTP Set-Link-Info] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [MSCHAP-v2 Response id=1 <90c21af1091f745e8bf22388b058>, <e695ae5aae274c88a3fa1ee3dc9057aece4d53c87b9fea>, F=0, name="test"] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: connect: ppp0 <--> pptp(192.168.10.100) +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ppp connected +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [MSCHAP-v2 Success id=1 "S=347F417CF04BEBBC7F75CFA7F43474C36FB218F9 M=Authentication succeeded"] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: test: authentication succeeded +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: auth_layer_started +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ccp_layer_start +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [CCP ConfReq id=b9 <mppe +H -M +S -L -D -C>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ipcp_layer_start +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ipv6cp_layer_start +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: IPV6CP: discarding packet +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [LCP ProtoRej id=122 <8057>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: recv [IPCP ConfReq id=6 <addr 0.0.0.0> <dns1 0.0.0.0> <wins1 0.0.0.0> <dns2 0.0.0.0> <wins2 0.0.0.0>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [IPCP ConfReq id=3b <addr 10.0.0.1>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [IPCP ConfRej id=6 <dns1 0.0.0.0> <wins1 0.0.0.0> <dns2 0.0.0.0> <wins2 0.0.0.0>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: recv [LCP ProtoRej id=7 <80fd>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ccp_layer_finished +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: recv [IPCP ConfAck id=3b <addr 10.0.0.1>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: recv [IPCP ConfReq id=8 <addr 0.0.0.0>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [IPCP ConfNak id=8 <addr 10.0.0.2>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: recv [IPCP ConfReq id=9 <addr 10.0.0.2>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [IPCP ConfAck id=9] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ipcp_layer_started +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: rename interface to 'pptp0' +Feb 29 14:59:00 vyos accel-pptp[4629]: pptp0:test: pptp: ppp started +``` + +[accel-ppp]: https://accel-ppp.org/ +[accel-ppp attribute]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel +[dictionary]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911 diff --git a/docs/configuration/vpn/md-rsa-keys.md b/docs/configuration/vpn/md-rsa-keys.md new file mode 100644 index 00000000..d8d7bca8 --- /dev/null +++ b/docs/configuration/vpn/md-rsa-keys.md @@ -0,0 +1,105 @@ +# RSA-Keys + +RSA can be used for services such as key exchanges and for encryption purposes. +To make IPSec work with dynamic address on one/both sides, we will have to use +RSA keys for authentication. They are very fast and easy to setup. + +First, on both routers run the operational command "generate pki key-pair +install \<key-pair nam>>". You may choose different length than 2048 of course. + +```none +vyos@left# run generate pki key-pair install ipsec-LEFT +Enter private key type: [rsa, dsa, ec] (Default: rsa) +Enter private key bits: (Default: 2048) +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] N +Configure mode commands to install key pair: +Do you want to install the public key? [Y/n] Yrgerg +set pki key-pair ipsec-LEFT public key 'MIIBIjANBgkqh...' +Do you want to install the private key? [Y/n] Y +set pki key-pair ipsec-LEFT private key 'MIIEvgIBADAN...' +[edit] +``` + +Configuration commands will display. +Note the command with the public key +(set pki key-pair ipsec-LEFT public key 'MIIBIjANBgkqh...'). +Then do the same on the opposite router: + +```none +vyos@left# run generate pki key-pair install ipsec-RIGHT +``` + +Note the command with the public key +(set pki key-pair ipsec-RIGHT public key 'FAAOCAQ8AMII...'). + +The noted public keys should be entered on the opposite routers. + +On the LEFT: + +```none +set pki key-pair ipsec-RIGHT public key 'FAAOCAQ8AMII...' +``` + +On the RIGHT: + +```none +set pki key-pair ipsec-LEFT public key 'MIIBIjANBgkqh...' +``` + +Now you are ready to setup IPsec. The key points: + +1. Since both routers do not know their effective public addresses, we set the local-address of the peer to "any". +2. On the initiator, we set the peer address to its public address, but on the responder we only set the id. +3. On the initiator, we need to set the remote-id option so that it can identify IKE traffic from the responder correctly. +4. On the responder, we need to set the local id so that initiator can know who's talking to it for the point #3 to work. + +On the LEFT (static address): + +```none +set vpn ipsec 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 id LEFT +set vpn ipsec site-to-site peer @RIGHT authentication mode rsa +set vpn ipsec site-to-site peer @RIGHT authentication rsa local-key ipsec-LEFT +set vpn ipsec site-to-site peer @RIGHT authentication rsa remote-key ipsec-RIGHT +set vpn ipsec site-to-site peer @RIGHT authentication remote-id 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): + +```none +set vpn ipsec 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 local-key ipsec-RIGHT +set vpn ipsec site-to-site peer 192.0.2.10 authentication rsa remote-key ipsec-LEFT +set vpn ipsec site-to-site peer 192.0.2.10 authentication 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/md-sstp.md b/docs/configuration/vpn/md-sstp.md new file mode 100644 index 00000000..3574a904 --- /dev/null +++ b/docs/configuration/vpn/md-sstp.md @@ -0,0 +1,765 @@ +(sstp)= + +# SSTP Server + +{abbr}`SSTP (Secure Socket Tunneling Protocol)` is a form of {abbr}`VPN +(Virtual Private Network)` tunnel that provides a mechanism to transport PPP +traffic through an SSL/TLS channel. SSL/TLS provides transport-level security +with key negotiation, encryption and traffic integrity checking. The use of +SSL/TLS over TCP port 443 allows SSTP to pass through virtually all firewalls +and proxy servers except for authenticated web proxies. + +SSTP is available for Linux, BSD, and Windows. + +VyOS utilizes [accel-ppp] to provide SSTP server functionality. We support both +local and RADIUS authentication. + +As SSTP provides PPP via a SSL/TLS channel the use of either publicly signed +certificates or private PKI is required. + +## Configuring SSTP Server + +### Certificates + +Using our documentation chapter - {ref}`pki` generate and install CA and Server certificate + +```none +vyos@vyos:~$ generate pki ca install CA +``` + +```none +vyos@vyos:~$ generate pki certificate sign CA install Server +``` + +### Configuration + +```none +set vpn sstp authentication local-users username test password 'test' +set vpn sstp authentication mode 'local' +set vpn sstp client-ip-pool SSTP-POOL range '10.0.0.2-10.0.0.100' +set vpn sstp default-pool 'SSTP-POOL' +set vpn sstp gateway-address '10.0.0.1' +set vpn sstp ssl ca-certificate 'CA1' +set vpn sstp ssl certificate 'Server' +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp authentication mode <local | radius> + + Set authentication backend. The configured authentication backend is used + for all queries. + + * **radius**: All authentication queries are handled by a configured RADIUS + server. + * **local**: All authentication queries are handled locally. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp authentication local-users username <user> password + <pass> + + Create `<user>` for local authentication on this system. The users password + will be set to `<pass>`. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp client-ip-pool <POOL-NAME> range <x.x.x.x-x.x.x.x | x.x.x.x/x> + + Use this command to define the first IP address of a pool of + addresses to be given to SSTP clients. If notation ``x.x.x.x-x.x.x.x``, + it must be within a /24 subnet. If notation ``x.x.x.x/x`` is + used there is possibility to set host/netmask. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp default-pool <POOL-NAME> + + Use this command to define default address pool name. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp gateway-address <gateway> + + Specifies single `<gateway>` IP address to be used as local address of PPP + interfaces. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp ssl ca-certificate <file> + + Name of installed certificate authority certificate. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp ssl certificate <file> + + Name of installed server certificate. +``` + +## Configuring RADIUS authentication + +To enable RADIUS based authentication, the authentication mode needs to be +changed within the configuration. Previous settings like the local users still +exist within the configuration, however they are not used if the mode has been +changed from local to radius. Once changed back to local, it will use all local +accounts again. + +```none +set vpn sstp authentication mode radius +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp authentication radius server <server> key <secret> + + Configure RADIUS `<server>` and its required shared `<secret>` for + communicating with the RADIUS server. +``` + +Since the RADIUS server would be a single point of failure, multiple RADIUS +servers can be setup and will be used subsequentially. +For example: + +```none +set vpn sstp authentication radius server 10.0.0.1 key 'foo' +set vpn sstp authentication radius server 10.0.0.2 key 'foo' +``` + +:::{note} +Some RADIUS severs use an access control list which allows or denies +queries, make sure to add your VyOS router to the allowed client list. +::: + +### RADIUS source address + +If you are using OSPF as your IGP, use the interface connected closest to the +RADIUS server. You can bind all outgoing RADIUS requests to a single source IP +e.g. the loopback interface. + +```{eval-rst} +.. cfgcmd:: set vpn sstp authentication radius source-address <address> + + Source IPv4 address used in all RADIUS server queires. +``` + +:::{note} +The `source-address` must be configured to that of an interface. +Best practice would be a loopback or dummy interface. +::: + +### RADIUS advanced options + +```{eval-rst} +.. cfgcmd:: set vpn sstp authentication radius server <server> port <port> + + Configure RADIUS `<server>` and its required port for authentication requests. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp authentication radius server <server> fail-time <time> + + Mark RADIUS server as offline for this given `<time>` in seconds. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp authentication radius server <server> disable + + Temporary disable this RADIUS server. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp authentication radius acct-timeout <timeout> + + Timeout to wait reply for Interim-Update packets. (default 3 seconds) +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp authentication radius dynamic-author server <address> + + Specifies IP address for Dynamic Authorization Extension server (DM/CoA) +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp authentication radius dynamic-author port <port> + + Port for Dynamic Authorization Extension server (DM/CoA) +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp authentication radius dynamic-author key <secret> + + Secret for Dynamic Authorization Extension server (DM/CoA) +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp authentication radius max-try <number> + + Maximum number of tries to send Access-Request/Accounting-Request queries +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp authentication radius timeout <timeout> + + Timeout to wait response from server (seconds) +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp authentication radius nas-identifier <identifier> + + Value to send to RADIUS server in NAS-Identifier attribute and to be matched + in DM/CoA requests. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp authentication radius nas-ip-address <address> + + Value to send to RADIUS server in NAS-IP-Address attribute and to be matched + in DM/CoA requests. Also DM/CoA server will bind to that address. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp authentication radius source-address <address> + + Source IPv4 address used in all RADIUS server queires. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp authentication radius rate-limit attribute <attribute> + + Specifies which RADIUS server attribute contains the rate limit information. + The default attribute is `Filter-Id`. +``` + +:::{note} +If you set a custom RADIUS attribute you must define it on both +dictionaries on the RADIUS server and client. +::: + +```{eval-rst} +.. cfgcmd:: set vpn sstp authentication radius rate-limit enable + + Enables bandwidth shaping via RADIUS. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp authentication radius rate-limit vendor + + Specifies the vendor dictionary, This dictionary needs to be present in + /usr/share/accel-ppp/radius. +``` + +Received RADIUS attributes have a higher priority than parameters defined within +the CLI configuration, refer to the explanation below. + +### Allocation clients ip addresses by RADIUS + +If the RADIUS server sends the attribute `Framed-IP-Address` then this IP +address will be allocated to the client and the option `default-pool` within +the CLI config will being ignored. + +If the RADIUS server sends the attribute `Framed-Pool`, then the IP address +will be allocated from a predefined IP pool whose name equals the attribute +value. + +If the RADIUS server sends the attribute `Stateful-IPv6-Address-Pool`, the +IPv6 address will be allocated from a predefined IPv6 pool `prefix` whose +name equals the attribute value. + +If the RADIUS server sends the attribute `Delegated-IPv6-Prefix-Pool`, an +IPv6 delegation prefix will be allocated from a predefined IPv6 pool `delegate` +whose name equals the attribute value. + +:::{note} +`Stateful-IPv6-Address-Pool` and `Delegated-IPv6-Prefix-Pool` are defined in +RFC6911. If they are not defined in your RADIUS server, add new [dictionary]. +::: + +The client's interface can be put into a VRF context via a RADIUS Access-Accept +packet, or changed via RADIUS CoA. `Accel-VRF-Name` is used for these +purposes. This is a custom [ACCEL-PPP attribute]. Define it in your RADIUS +server. + +### Renaming clients interfaces by RADIUS + +If the RADIUS server uses the attribute `NAS-Port-Id`, ppp tunnels will be +renamed. + +:::{note} +The value of the attribute `NAS-Port-Id` must be less than 16 +characters, otherwise the interface won't be renamed. +::: + +## IPv6 + +```{eval-rst} +.. cfgcmd:: set vpn sstp ppp-options ipv6 <require | prefer | allow | deny> + + Specifies IPv6 negotiation preference. + + * **require** - Require IPv6 negotiation + * **prefer** - Ask client for IPv6 negotiation, do not fail if it rejects + * **allow** - Negotiate IPv6 only if client requests + * **deny** - Do not negotiate IPv6 (default value) +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp client-ipv6-pool <IPv6-POOL-NAME> prefix <address> + mask <number-of-bits> + + Use this comand to set the IPv6 address pool from which an SSTP client will + get an IPv6 prefix of your defined length (mask) to terminate the SSTP + endpoint at their side. The mask length can be set between 48 and 128 bits + long, the default value is 64. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp client-ipv6-pool <IPv6-POOL-NAME> delegate <address> + delegation-prefix <number-of-bits> + + Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on SSTP. You + will have to set your IPv6 pool and the length of the delegation prefix. From + the defined IPv6 pool you will be handing out networks of the defined length + (delegation-prefix). The length of the delegation prefix can be set between + 32 and 64 bits long. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp default-ipv6-pool <IPv6-POOL-NAME> + + Use this command to define default IPv6 address pool name. +``` + +```none +set vpn sstp ppp-options ipv6 allow +set vpn sstp client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' +set vpn sstp client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' +set vpn sstp default-ipv6-pool IPv6-POOL +``` + +### IPv6 Advanced Options + +```{eval-rst} +.. cfgcmd:: set vpn sstp ppp-options ipv6-accept-peer-interface-id + + Accept peer interface identifier. By default this is not defined. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp ppp-options ipv6-interface-id <random | x:x:x:x> + + Specifies if a fixed or random interface identifier is used for IPv6. The + default is fixed. + + * **random** - Random interface identifier for IPv6 + * **x:x:x:x** - Specify interface identifier for IPv6 +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp ppp-options ipv6-interface-id <random | x:x:x:x> + + Specifies the peer interface identifier for IPv6. The default is fixed. + + * **random** - Random interface identifier for IPv6 + * **x:x:x:x** - Specify interface identifier for IPv6 + * **ipv4-addr** - Calculate interface identifier from IPv4 address. + * **calling-sid** - Calculate interface identifier from calling-station-id. +``` + +## Scripting + +```{eval-rst} +.. cfgcmd:: set vpn sstp extended-scripts on-change <path_to_script> + + Script to run when the session interface is changed by RADIUS CoA handling +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp extended-scripts on-down <path_to_script> + + Script to run when the session interface about to terminate +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp extended-scripts on-pre-up <path_to_script> + + Script to run before the session interface comes up +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp extended-scripts on-up <path_to_script> + + Script to run when the session interface is completely configured and started +``` + +## Advanced Options + +### Authentication Advanced Options + +```{eval-rst} +.. cfgcmd:: set vpn sstp authentication local-users username <user> disable + + Disable `<user>` account. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp authentication local-users username <user> static-ip + <address> + + Assign a static IP address to `<user>` account. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp authentication local-users username <user> rate-limit + download <bandwidth> + + Rate limit the download bandwidth for `<user>` to `<bandwidth>` kbit/s. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp authentication local-users username <user> rate-limit + upload <bandwidth> + + Rate limit the upload bandwidth for `<user>` to `<bandwidth>` kbit/s. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp authentication protocols + <pap | chap | mschap | mschap-v2> + + Require the peer to authenticate itself using one of the following protocols: + pap, chap, mschap, mschap-v2. +``` + +### Client IP Pool Advanced Options + +```{eval-rst} +.. cfgcmd:: set vpn sstp client-ip-pool <POOL-NAME> next-pool <NEXT-POOL-NAME> + + Use this command to define the next address pool name. +``` + +### PPP Advanced Options + +```{eval-rst} +.. cfgcmd:: set vpn sstp ppp-options disable-ccp + + Disable Compression Control Protocol (CCP). + CCP is enabled by default. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp ppp-options interface-cache <number> + + Specifies number of interfaces to cache. This prevents interfaces from being + removed once the corresponding session is destroyed. Instead, interfaces are + cached for later use in new sessions. This should reduce the kernel-level + interface creation/deletion rate. + Default value is **0**. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp ppp-options ipv4 <require | prefer | allow | deny> + + Specifies IPv4 negotiation preference. + + * **require** - Require IPv4 negotiation + * **prefer** - Ask client for IPv4 negotiation, do not fail if it rejects + * **allow** - Negotiate IPv4 only if client requests (Default value) + * **deny** - Do not negotiate IPv4 +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp ppp-options lcp-echo-failure <number> + + Defines the maximum `<number>` of unanswered echo requests. Upon reaching the + value `<number>`, the session will be reset. Default value is **3**. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp ppp-options lcp-echo-interval <interval> + + If this option is specified and is greater than 0, then the PPP module will + send LCP echo requests every `<interval>` seconds. + Default value is **30**. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp ppp-options lcp-echo-timeout + + Specifies timeout in seconds to wait for any peer activity. If this option is + specified it turns on adaptive lcp echo functionality and "lcp-echo-failure" + is not used. Default value is **0**. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp ppp-options min-mtu <number> + + Defines the minimum acceptable MTU. If a client tries to negotiate an MTU + lower than this it will be NAKed, and disconnected if it rejects a greater + MTU. + Default value is **100**. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp ppp-options mppe <require | prefer | deny> + + Specifies {abbr}`MPPE (Microsoft Point-to-Point Encryption)` negotiation + preference. + + * **require** - ask client for mppe, if it rejects drop connection + * **prefer** - ask client for mppe, if it rejects don't fail. (Default value) + * **deny** - deny mppe + + Default behavior - don't ask the client for mppe, but allow it if the client + wants. + Please note that RADIUS may override this option by MS-MPPE-Encryption-Policy + attribute. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp ppp-options mru <number> + + Defines preferred MRU. By default is not defined. +``` + +### Global Advanced options + +```{eval-rst} +.. cfgcmd:: set vpn sstp description <description> + + Set description. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp limits burst <value> + + Burst count +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp limits connection-limit <value> + + Maximum accepted connection rate (e.g. 1/min, 60/sec) +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp limits timeout <value> + + Timeout in seconds +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp mtu + + Maximum Transmission Unit (MTU) (default: **1500**) +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp max-concurrent-sessions + + Maximum number of concurrent session start attempts +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp name-server <address> + + Connected clients should use `<address>` as their DNS server. This command + accepts both IPv4 and IPv6 addresses. Up to two nameservers can be configured + for IPv4, up to three for IPv6. +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp shaper fwmark <1-2147483647> + + Match firewall mark value +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp snmp master-agent + + Enable SNMP +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp wins-server <address> + + Windows Internet Name Service (WINS) servers propagated to client +``` + +```{eval-rst} +.. cfgcmd:: set vpn sstp host-name <hostname> + + If this option is given, only SSTP connections to the specified host + and with the same TLS SNI will be allowed. +``` + +## Configuring SSTP client + +Once you have setup your SSTP server there comes the time to do some basic +testing. The Linux client used for testing is called [sstpc]. [sstpc] requires a +PPP configuration/peer file. + +If you use a self-signed certificate, do not forget to install CA on the client side. + +The following PPP configuration tests MSCHAP-v2: + +```none +$ cat /etc/ppp/peers/vyos +usepeerdns +#require-mppe +#require-pap +require-mschap-v2 +noauth +lock +refuse-pap +refuse-eap +refuse-chap +refuse-mschap +#refuse-mschap-v2 +nobsdcomp +nodeflate +debug +``` + +You can now "dial" the peer with the follwoing command: `sstpc --log-level 4 +--log-stderr --user vyos --password vyos vpn.example.com -- call vyos`. + +A connection attempt will be shown as: + +```none +$ sstpc --log-level 4 --log-stderr --user vyos --password vyos vpn.example.com -- call vyos + +Mar 22 13:29:12 sstpc[12344]: Resolved vpn.example.com to 192.0.2.1 +Mar 22 13:29:12 sstpc[12344]: Connected to vpn.example.com +Mar 22 13:29:12 sstpc[12344]: Sending Connect-Request Message +Mar 22 13:29:12 sstpc[12344]: SEND SSTP CRTL PKT(14) +Mar 22 13:29:12 sstpc[12344]: TYPE(1): CONNECT REQUEST, ATTR(1): +Mar 22 13:29:12 sstpc[12344]: ENCAP PROTO(1): 6 +Mar 22 13:29:12 sstpc[12344]: RECV SSTP CRTL PKT(48) +Mar 22 13:29:12 sstpc[12344]: TYPE(2): CONNECT ACK, ATTR(1): +Mar 22 13:29:12 sstpc[12344]: CRYPTO BIND REQ(4): 40 +Mar 22 13:29:12 sstpc[12344]: Started PPP Link Negotiation +Mar 22 13:29:15 sstpc[12344]: Sending Connected Message +Mar 22 13:29:15 sstpc[12344]: SEND SSTP CRTL PKT(112) +Mar 22 13:29:15 sstpc[12344]: TYPE(4): CONNECTED, ATTR(1): +Mar 22 13:29:15 sstpc[12344]: CRYPTO BIND(3): 104 +Mar 22 13:29:15 sstpc[12344]: Connection Established + +$ ip addr show ppp0 +164: ppp0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1452 qdisc fq_codel state UNKNOWN group default qlen 3 + link/ppp promiscuity 0 + inet 100.64.2.2 peer 100.64.1.1/32 scope global ppp0 + valid_lft forever preferred_lft forever +``` + +## Monitoring + +```{eval-rst} +.. opcmd:: show sstp-server sessions + + Use this command to locally check the active sessions in the SSTP + server. +``` + +```none +vyos@vyos:~$ show sstp-server sessions + ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes +--------+----------+----------+-----+--------+----------------+------------+--------+----------+----------+---------- + sstp0 | test | 10.0.0.2 | | | 192.168.10.100 | | active | 00:15:46 | 16.3 KiB | 210 B +``` + +```none +vyos@vyos:~$ show sstp-server statistics + uptime: 0.01:21:54 +cpu: 0% +mem(rss/virt): 6688/100464 kB +core: + mempool_allocated: 149420 + mempool_available: 146092 + thread_count: 1 + thread_active: 1 + context_count: 6 + context_sleeping: 0 + context_pending: 0 + md_handler_count: 7 + md_handler_pending: 0 + timer_count: 2 + timer_pending: 0 +sessions: + starting: 0 + active: 1 + finishing: 0 +sstp: + starting: 0 + active: 1 +``` + +## Troubleshooting + +```none +vyos@vyos:~$sudo journalctl -u accel-ppp@sstp -b 0 + +Feb 28 17:03:04 vyos accel-sstp[2492]: sstp: new connection from 192.168.10.100:49852 +Feb 28 17:03:04 vyos accel-sstp[2492]: sstp: starting +Feb 28 17:03:04 vyos accel-sstp[2492]: sstp: started +Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [HTTP <SSTP_DUPLEX_POST /sra_{BA195980-CD49-458b-9E23-C84EE0ADCD75}/ HTTP/1.1>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [HTTP <SSTPCORRELATIONID: {48B82435-099A-4158-A987-052E7570CFAA}>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [HTTP <Content-Length: 18446744073709551615>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [HTTP <Host: vyos.io>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [HTTP <HTTP/1.1 200 OK>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [HTTP <Date: Wed, 28 Feb 2024 17:03:04 GMT>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [HTTP <Content-Length: 18446744073709551615>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [SSTP SSTP_MSG_CALL_CONNECT_REQUEST] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [SSTP SSTP_MSG_CALL_CONNECT_ACK] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: lcp_layer_init +Feb 28 17:03:04 vyos accel-sstp[2492]: :: auth_layer_init +Feb 28 17:03:04 vyos accel-sstp[2492]: :: ccp_layer_init +Feb 28 17:03:04 vyos accel-sstp[2492]: :: ipcp_layer_init +Feb 28 17:03:04 vyos accel-sstp[2492]: :: ipv6cp_layer_init +Feb 28 17:03:04 vyos accel-sstp[2492]: :: ppp establishing +Feb 28 17:03:04 vyos accel-sstp[2492]: :: lcp_layer_start +Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [LCP ConfReq id=56 <auth PAP> <mru 1452> <magic 1cd9ad05>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [LCP ConfReq id=0 <mru 4091> <magic 345f64ca> <pcomp> <accomp> < d 3 6 >] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [LCP ConfRej id=0 <pcomp> <accomp> < d 3 6 >] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [LCP ConfReq id=1 <mru 4091> <magic 345f64ca>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [LCP ConfNak id=1 <mru 1452>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [LCP ConfReq id=2 <mru 1452> <magic 345f64ca>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [LCP ConfAck id=2] +Feb 28 17:03:07 vyos accel-sstp[2492]: :: fsm timeout 9 +Feb 28 17:03:07 vyos accel-sstp[2492]: :: send [LCP ConfReq id=56 <auth PAP> <mru 1452> <magic 1cd9ad05>] +Feb 28 17:03:07 vyos accel-sstp[2492]: :: recv [LCP ConfAck id=56 <auth PAP> <mru 1452> <magic 1cd9ad05>] +Feb 28 17:03:07 vyos accel-sstp[2492]: :: lcp_layer_started +Feb 28 17:03:07 vyos accel-sstp[2492]: :: auth_layer_start +Feb 28 17:03:07 vyos accel-sstp[2492]: :: recv [LCP Ident id=3 <MSRASV5.20>] +Feb 28 17:03:07 vyos accel-sstp[2492]: :: recv [LCP Ident id=4 <MSRAS-0-MSEDGEWIN10>] +Feb 28 17:03:07 vyos accel-sstp[2492]: [50B blob data] +Feb 28 17:03:07 vyos accel-sstp[2492]: :: recv [PAP AuthReq id=3] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: connect: ppp0 <--> sstp(192.168.10.100:49852) +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: ppp connected +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [PAP AuthAck id=3 "Authentication succeeded"] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: test: authentication succeeded +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: auth_layer_started +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: ccp_layer_start +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: ipcp_layer_start +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: ipv6cp_layer_start +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: recv [SSTP SSTP_MSG_CALL_CONNECTED] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: IPV6CP: discarding packet +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [LCP ProtoRej id=88 <8057>] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: recv [IPCP ConfReq id=7 <addr 0.0.0.0> <dns1 0.0.0.0> <wins1 0.0.0.0> <dns2 0.0.0.0> <wins2 0.0.0.0>] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [IPCP ConfReq id=25 <addr 10.0.0.1>] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [IPCP ConfRej id=7 <dns1 0.0.0.0> <wins1 0.0.0.0> <dns2 0.0.0.0> <wins2 0.0.0.0>] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: recv [IPCP ConfAck id=25 <addr 10.0.0.1>] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: recv [IPCP ConfReq id=8 <addr 0.0.0.0>] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [IPCP ConfNak id=8 <addr 10.0.0.5>] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: recv [IPCP ConfReq id=9 <addr 10.0.0.5>] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [IPCP ConfAck id=9] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: ipcp_layer_started +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: rename interface to 'sstp0' +Feb 28 17:03:07 vyos accel-sstp[2492]: sstp0:test: sstp: ppp: started +``` + +```{include} /_include/common-references.txt +``` + +[accel-ppp attribute]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel +[dictionary]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911 +[sstpc]: https://github.com/reliablehosting/sstp-client diff --git a/docs/configuration/vrf/md-index.md b/docs/configuration/vrf/md-index.md new file mode 100644 index 00000000..b0c86bda --- /dev/null +++ b/docs/configuration/vrf/md-index.md @@ -0,0 +1,601 @@ +--- +lastproofread: '2021-07-07' +--- + +(vrf)= + +# VRF + +{abbr}`VRF (Virtual Routing and Forwarding)` devices combined with ip rules +provides the ability to create virtual routing and forwarding domains (aka +VRFs, VRF-lite to be specific) in the Linux network stack. One use case is the +multi-tenancy problem where each tenant has their own unique routing tables and +in the very least need different default gateways. + +## Configuration + +A VRF device is created with an associated route table. Network interfaces are +then enslaved to a VRF device. + +```{eval-rst} +.. cfgcmd:: set vrf name <name> table <id> + + Create a new VRF instance with `<name>` and `<id>`. The name is used when placing + individual interfaces into the VRF. + + .. note:: A routing table ID can not be modified once it is assigned. It can + only be changed by deleting and re-adding the VRF instance. +``` + +```{eval-rst} +.. cfgcmd:: set vrf bind-to-all + + By default the scope of the port bindings for unbound sockets is limited to + the default VRF. That is, it will not be matched by packets arriving on + interfaces enslaved to a VRF and processes may bind to the same port if + they bind to a VRF. + + TCP & UDP services running in the default VRF context (ie., not bound to any + VRF device) can work across all VRF domains by enabling this option. +``` + +### Zebra/Kernel route filtering + +Zebra supports prefix-lists and Route Mapss to match routes received from +other FRR components. The permit/deny facilities provided by these commands +can be used to filter which routes zebra will install in the kernel. + +```{eval-rst} +.. cfgcmd:: set vrf <name> ip protocol <protocol> route-map <route-map> + + Apply a route-map filter to routes for the specified protocol. + + The following protocols can be used: any, babel, bgp, connected, eigrp, + isis, kernel, ospf, rip, static, table + + .. note:: If you choose any as the option that will cause all protocols that + are sending routes to zebra. +``` + +```{eval-rst} +.. cfgcmd:: set vrf <name> ipv6 protocol <protocol> route-map <route-map> + + Apply a route-map filter to routes for the specified protocol. + + The following protocols can be used: any, babel, bgp, connected, isis, + kernel, ospfv3, ripng, static, table + + .. note:: If you choose any as the option that will cause all protocols that + are sending routes to zebra. +``` + +### Nexthop Tracking + +Nexthop tracking resolve nexthops via the default route by default. This is enabled +by default for a traditional profile of FRR which we use. It and can be disabled if +you do not wan't to e.g. allow BGP to peer across the default route. + +```{eval-rst} +.. cfgcmd:: set vrf name <name> ip nht no-resolve-via-default + + Do not allow IPv4 nexthop tracking to resolve via the default route. This + parameter is configured per-VRF, so the command is also available in the VRF + subnode. +``` + +```{eval-rst} +.. cfgcmd:: set vrf name <name> ipv6 nht no-resolve-via-default + + Do not allow IPv4 nexthop tracking to resolve via the default route. This + parameter is configured per-VRF, so the command is also available in the VRF + subnode. +``` + +### Interfaces + +When VRFs are used it is not only mandatory to create a VRF but also the VRF +itself needs to be assigned to an interface. + +```{eval-rst} +.. cfgcmd:: set interfaces <dummy | ethernet | bonding | bridge | pppoe> + <interface> vrf <name> + + Assign interface identified by `<interface>` to VRF named `<name>`. +``` + +### Routing + +:::{note} +VyOS 1.4 (sagitta) introduced dynamic routing support for VRFs. +::: + +Currently dynamic routing is supported for the following protocols: + +- {ref}`routing-bgp` +- {ref}`routing-isis` +- {ref}`routing-ospf` +- {ref}`routing-ospfv3` +- {ref}`routing-static` + +The CLI configuration is same as mentioned in above articles. The only +difference is, that each routing protocol used, must be prefixed with the `vrf +name <name>` command. + +#### Example + +The following commands would be required to set options for a given dynamic +routing protocol inside a given vrf: + +- {ref}`routing-bgp`: `set vrf name <name> protocols bgp ...` +- {ref}`routing-isis`: `set vrf name <name> protocols isis ...` +- {ref}`routing-ospf`: `set vrf name <name> protocols ospf ...` +- {ref}`routing-ospfv3`: `set vrf name <name> protocols ospfv3 ...` +- {ref}`routing-static`: `set vrf name <name> protocols static ...` + +## Operation + +It is not sufficient to only configure a VRF but VRFs must be maintained, too. +For VRF maintenance the following operational commands are in place. + +```{eval-rst} +.. opcmd:: show vrf + + Lists VRFs that have been created + + .. code-block:: none + + vyos@vyos:~$ show vrf + VRF name state mac address flags interfaces + -------- ----- ----------- ----- ---------- + blue up 00:53:12:d8:74:24 noarp,master,up,lower_up dum200,eth0.302 + red up 00:53:de:02:df:aa noarp,master,up,lower_up dum100,eth0.300,bond0.100,peth0 + + .. note:: Command should probably be extended to list also the real + interfaces assigned to this one VRF to get a better overview. +``` + +```{eval-rst} +.. opcmd:: show vrf <name> + + .. code-block:: none + + vyos@vyos:~$ show vrf name blue + VRF name state mac address flags interfaces + -------- ----- ----------- ----- ---------- + blue up 00:53:12:d8:74:24 noarp,master,up,lower_up dum200,eth0.302 +``` + +```{eval-rst} +.. opcmd:: show ip route vrf <name> + + Display IPv4 routing table for VRF identified by `<name>`. + + .. code-block:: none + + vyos@vyos:~$ show ip route vrf blue + Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued route, r - rejected route + + VRF blue: + K 0.0.0.0/0 [255/8192] unreachable (ICMP unreachable), 00:00:50 + S>* 172.16.0.0/16 [1/0] via 192.0.2.1, dum1, 00:00:02 + C>* 192.0.2.0/24 is directly connected, dum1, 00:00:06 + +``` + +```{eval-rst} +.. opcmd:: show ipv6 route vrf <name> + + Display IPv6 routing table for VRF identified by `<name>`. + + .. code-block:: none + + vyos@vyos:~$ show ipv6 route vrf red + Codes: K - kernel route, C - connected, S - static, R - RIPng, + O - OSPFv3, I - IS-IS, B - BGP, N - NHRP, T - Table, + v - VNC, V - VNC-Direct, A - Babel, D - SHARP, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued route, r - rejected route + + VRF red: + K ::/0 [255/8192] unreachable (ICMP unreachable), 00:43:20 + C>* 2001:db8::/64 is directly connected, dum1, 00:02:19 + C>* fe80::/64 is directly connected, dum1, 00:43:19 + K>* ff00::/8 [0/256] is directly connected, dum1, 00:43:19 + +``` + +```{eval-rst} +.. opcmd:: ping <host> vrf <name> + + The ping command is used to test whether a network host is reachable or not. + + Ping uses ICMP protocol's mandatory ECHO_REQUEST datagram to elicit an + ICMP ECHO_RESPONSE from a host or gateway. ECHO_REQUEST datagrams (pings) + will have an IP and ICMP header, followed by "struct timeval" and an + arbitrary number of pad bytes used to fill out the packet. + + When doing fault isolation with ping, you should first run it on the local + host, to verify that the local network interface is up and running. Then, + continue with hosts and gateways further down the road towards your + destination. Round-trip time and packet loss statistics are computed. + + Duplicate packets are not included in the packet loss calculation, although + the round-trip time of these packets is used in calculating the minimum/ + average/maximum round-trip time numbers. + + .. note:: Ping command can be interrupted at any given time using ``<Ctrl>+c``. + A brief statistic is shown afterwards. + + .. code-block:: none + + vyos@vyos:~$ ping 192.0.2.1 vrf red + PING 192.0.2.1 (192.0.2.1) 56(84) bytes of data. + 64 bytes from 192.0.2.1: icmp_seq=1 ttl=64 time=0.070 ms + 64 bytes from 192.0.2.1: icmp_seq=2 ttl=64 time=0.078 ms + ^C + --- 192.0.2.1 ping statistics --- + 2 packets transmitted, 2 received, 0% packet loss, time 4ms + rtt min/avg/max/mdev = 0.070/0.074/0.078/0.004 ms +``` + +```{eval-rst} +.. opcmd:: traceroute vrf <name> [ipv4 | ipv6] <host> + + Displays the route packets taken to a network host utilizing VRF instance + identified by `<name>`. When using the IPv4 or IPv6 option, displays the + route packets taken to the given hosts IP address family. This option is + useful when the host is specified as a hostname rather than an IP address. +``` + +```{eval-rst} +.. opcmd:: force vrf <name> + + Join a given VRF. This will open a new subshell within the specified VRF. + + The prompt is adjusted to reflect this change in both config and op-mode. + + .. code-block:: none + + vyos@vyos:~$ force vrf blue + vyos@vyos(vrf:blue):~$ +``` + +(vrf-example)= + +## Example + +### VRF route leaking + +The following example topology was built using EVE-NG. + +:::{figure} /_static/images/vrf-example-topology-01.png +:alt: VRF topology example + +VRF route leaking +::: + +- PC1 is in the `default` VRF and acting as e.g. a "fileserver" +- PC2 is in VRF `blue` which is the development department +- PC3 and PC4 are connected to a bridge device on router `R1` which is in VRF + `red`. Say this is the HR department. +- R1 is managed through an out-of-band network that resides in VRF `mgmt` + +(vrf-example-configuration)= + +#### Configuration + +> ```none +> set interfaces bridge br10 address '10.30.0.254/24' +> set interfaces bridge br10 member interface eth3 +> set interfaces bridge br10 member interface eth4 +> set interfaces bridge br10 vrf 'red' +> +> set interfaces ethernet eth0 address 'dhcp' +> set interfaces ethernet eth0 vrf 'mgmt' +> set interfaces ethernet eth1 address '10.0.0.254/24' +> set interfaces ethernet eth2 address '10.20.0.254/24' +> set interfaces ethernet eth2 vrf 'blue' +> +> set protocols static route 10.20.0.0/24 interface eth2 vrf 'blue' +> set protocols static route 10.30.0.0/24 interface br10 vrf 'red' +> +> set service ssh disable-host-validation +> set service ssh vrf 'mgmt' +> +> set system name-server 'eth0' +> +> set vrf name blue protocols static route 10.0.0.0/24 interface eth1 vrf 'default' +> set vrf name blue table '3000' +> set vrf name mgmt table '1000' +> set vrf name red protocols static route 10.0.0.0/24 interface eth1 vrf 'default' +> set vrf name red table '2000' +> ``` + +### VRF and NAT + +(vrf-nat-configuration)= + +#### Configuration + +> ```none +> set interfaces ethernet eth0 address '172.16.50.12/24' +> set interfaces ethernet eth0 vrf 'red' +> +> set interfaces ethernet eth1 address '192.168.130.100/24' +> set interfaces ethernet eth1 vrf 'blue' +> +> set nat destination rule 110 description 'NAT ssh- INSIDE' +> set nat destination rule 110 destination port '2022' +> set nat destination rule 110 inbound-interface 'eth0' +> set nat destination rule 110 protocol 'tcp' +> set nat destination rule 110 translation address '192.168.130.40' +> +> set nat source rule 100 outbound-interface 'eth0' +> set nat source rule 100 protocol 'all' +> set nat source rule 100 source address '192.168.130.0/24' +> set nat source rule 100 translation address 'masquerade' +> +> set service ssh vrf 'red' +> +> set vrf bind-to-all +> set vrf name blue protocols static route 0.0.0.0/0 next-hop 172.16.50.1 vrf 'red' +> set vrf name blue protocols static route 172.16.50.0/24 interface eth0 vrf 'red' +> set vrf name blue table '1010' +> +> set vrf name red protocols static route 0.0.0.0/0 next-hop 172.16.50.1 +> set vrf name red protocols static route 192.168.130.0/24 interface eth1 vrf 'blue' +> set vrf name red table '2020' +> ``` + +(vrf-example-operation)= + +#### Operation + +After committing the configuration we can verify all leaked routes are +installed, and try to ICMP ping PC1 from PC3. + +> ```none +> PCS> ping 10.0.0.1 +> +> 84 bytes from 10.0.0.1 icmp_seq=1 ttl=63 time=1.943 ms +> 84 bytes from 10.0.0.1 icmp_seq=2 ttl=63 time=1.618 ms +> 84 bytes from 10.0.0.1 icmp_seq=3 ttl=63 time=1.745 ms +> ``` +> +> ```none +> VPCS> show ip +> +> NAME : VPCS[1] +> IP/MASK : 10.30.0.1/24 +> GATEWAY : 10.30.0.254 +> DNS : +> MAC : 00:50:79:66:68:0f +> ``` + +##### VRF default routing table + +> ```none +> vyos@R1:~$ show ip route +> Codes: K - kernel route, C - connected, S - static, R - RIP, +> O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, +> T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, +> F - PBR, f - OpenFabric, +> > - selected route, * - FIB route, q - queued, r - rejected, b - backup +> +> C>* 10.0.0.0/24 is directly connected, eth1, 00:07:44 +> S>* 10.20.0.0/24 [1/0] is directly connected, eth2 (vrf blue), weight 1, 00:07:38 +> S>* 10.30.0.0/24 [1/0] is directly connected, br10 (vrf red), weight 1, 00:07:38 +> ``` + +##### VRF red routing table + +> ```none +> vyos@R1:~$ show ip route vrf red +> Codes: K - kernel route, C - connected, S - static, R - RIP, +> O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, +> T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, +> F - PBR, f - OpenFabric, +> > - selected route, * - FIB route, q - queued, r - rejected, b - backup +> +> VRF red: +> K>* 0.0.0.0/0 [255/8192] unreachable (ICMP unreachable), 00:07:57 +> S>* 10.0.0.0/24 [1/0] is directly connected, eth1 (vrf default), weight 1, 00:07:40 +> C>* 10.30.0.0/24 is directly connected, br10, 00:07:54 +> ``` + +##### VRF blue routing table + +> ```none +> vyos@R1:~$ show ip route vrf blue +> Codes: K - kernel route, C - connected, S - static, R - RIP, +> O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, +> T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, +> F - PBR, f - OpenFabric, +> > - selected route, * - FIB route, q - queued, r - rejected, b - backup +> +> VRF blue: +> K>* 0.0.0.0/0 [255/8192] unreachable (ICMP unreachable), 00:08:00 +> S>* 10.0.0.0/24 [1/0] is directly connected, eth1 (vrf default), weight 1, 00:07:44 +> C>* 10.20.0.0/24 is directly connected, eth2, 00:07:53 +> ``` + +# L3VPN VRFs + +{abbr}`L3VPN VRFs ( Layer 3 Virtual Private Networks )` bgpd supports for +IPv4 RFC 4364 and IPv6 RFC 4659. L3VPN routes, and their associated VRF +MPLS labels, can be distributed to VPN SAFI neighbors in the default, i.e., +non VRF, BGP instance. VRF MPLS labels are reached using core MPLS labels +which are distributed using LDP or BGP labeled unicast. +bgpd also supports inter-VRF route leaking. + +(l3vpn-vrf-route-leaking)= + +## VRF Route Leaking + +BGP routes may be leaked (i.e. copied) between a unicast VRF RIB and the VPN +SAFI RIB of the default VRF for use in MPLS-based L3VPNs. Unicast routes may +also be leaked between any VRFs (including the unicast RIB of the default BGP +instance). A shortcut syntax is also available for specifying leaking from +one VRF to another VRF using the default instance’s VPN RIB as the intemediary +. A common application of the VRF-VRF feature is to connect a customer’s +private routing domain to a provider’s VPN service. Leaking is configured from +the point of view of an individual VRF: import refers to routes leaked from VPN +to a unicast VRF, whereas export refers to routes leaked from a unicast VRF to +VPN. + +:::{note} +Routes exported from a unicast VRF to the VPN RIB must be augmented +by two parameters: + +> an RD / RTLIST + +Configuration for these exported routes must, at a minimum, specify +these two parameters. +::: + +(l3vpn-vrf-example-configuration)= + +## Configuration + +Configuration of route leaking between a unicast VRF RIB and the VPN SAFI RIB +of the default VRF is accomplished via commands in the context of a VRF +address-family. + +```{eval-rst} +.. cfgcmd:: set vrf name <name> protocols bgp address-family + <ipv4-unicast|ipv6-unicast> rd vpn export <asn:nn|address:nn> + + Specifies the route distinguisher to be added to a route exported from the + current unicast VRF to VPN. +``` + +```{eval-rst} +.. cfgcmd:: set vrf name <name> protocols bgp address-family + <ipv4-unicast|ipv6-unicast> route-target vpn <import|export|both> + [RTLIST] + + Specifies the route-target list to be attached to a route (export) or the + route-target list to match against (import) when exporting/importing + between the current unicast VRF and VPN.The RTLIST is a space-separated + list of route-targets, which are BGP extended community values as + described in Extended Communities Attribute. +``` + +```{eval-rst} +.. cfgcmd:: set vrf name <name> protocols bgp address-family + <ipv4-unicast|ipv6-unicast> label vpn export <0-1048575|auto> + + Enables an MPLS label to be attached to a route exported from the current + unicast VRF to VPN. If the value specified is auto, the label value is + automatically assigned from a pool maintained. +``` + +```{eval-rst} +.. cfgcmd:: set vrf name <name> protocols bgp address-family + <ipv4-unicast|ipv6-unicast> label vpn allocation-mode per-nexthop + + Select how labels are allocated in the given VRF. By default, the per-vrf + mode is selected, and one label is used for all prefixes from the VRF. The + per-nexthop will use a unique label for all prefixes that are reachable via + the same nexthop. +``` + +```{eval-rst} +.. cfgcmd:: set vrf name <name> protocols bgp address-family + <ipv4-unicast|ipv6-unicast> route-map vpn <import|export> + [route-map <name>] + + Specifies an optional route-map to be applied to routes imported or + exported between the current unicast VRF and VPN. +``` + +```{eval-rst} +.. cfgcmd:: set vrf name <name> protocols bgp address-family + <ipv4-unicast|ipv6-unicast> <import|export> vpn + + Enables import or export of routes between the current unicast VRF and VPN. +``` + +```{eval-rst} +.. cfgcmd:: set vrf name <name> protocols bgp address-family + <ipv4-unicast|ipv6-unicast> import vrf <name> + + Shortcut syntax for specifying automatic leaking from vrf VRFNAME to the + current VRF using the VPN RIB as intermediary. The RD and RT are auto + derived and should not be specified explicitly for either the source or + destination VRF’s. +``` + +```{eval-rst} +.. cfgcmd:: set vrf name <name> protocols bgp address-family + <ipv4-unicast|ipv6-unicast> route-map vrf import + [route-map <name>] + + Specifies an optional route-map to be applied to routes imported from VRFs. +``` + +```{eval-rst} +.. cfgcmd:: set vrf name <name> protocols bgp interface <interface> mpls + forwarding + + It is possible to permit BGP install VPN prefixes without transport labels. + This configuration will install VPN prefixes originated from an e-bgp session, + and with the next-hop directly connected. +``` + +(l3vpn-vrf-example-operation)= + +## Operation + +It is not sufficient to only configure a L3VPN VRFs but L3VPN VRFs must be +maintained, too.For L3VPN VRF maintenance the following operational commands +are in place. + +```{eval-rst} +.. opcmd:: show bgp <ipv4|ipv6> vpn + + Print active IPV4 or IPV6 routes advertised via the VPN SAFI. + + .. code-block:: none + + BGP table version is 2, local router ID is 10.0.1.1, vrf id 0 + Default local pref 100, local AS 65001 + Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, + i internal, r RIB-failure, S Stale, R Removed + Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self + Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path + Route Distinguisher: 10.50.50.1:1011 + *>i10.50.50.0/24 10.0.0.7 0 100 0 i + UN=10.0.0.7 EC{65035:1011} label=80 type=bgp, subtype=0 + Route Distinguisher: 10.60.60.1:1011 + *>i10.60.60.0/24 10.0.0.10 0 100 0 i + UN=10.0.0.10 EC{65035:1011} label=80 type=bgp, subtype=0 +``` + +```{eval-rst} +.. opcmd:: show bgp <ipv4|ipv6> vpn summary + + Print a summary of neighbor connections for the specified AFI/SAFI + combination. + + .. code-block:: none + + BGP router identifier 10.0.1.1, local AS number 65001 vrf-id 0 + BGP table version 0 + RIB entries 9, using 1728 bytes of memory + Peers 4, using 85 KiB of memory + Peer groups 1, using 64 bytes of memory + + Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd PfxSnt + 10.0.0.7 4 65001 2860 2870 0 0 0 1d23h34m 2 10 + +``` + +```{include} /_include/common-references.txt +``` diff --git a/docs/contributing/md-build-vyos.md b/docs/contributing/md-build-vyos.md new file mode 100644 index 00000000..4541e828 --- /dev/null +++ b/docs/contributing/md-build-vyos.md @@ -0,0 +1,838 @@ +(build)= + +# Build VyOS + +## Prerequisites + +There are different ways you can build VyOS. + +Building using a {ref}`build_docker` container, although not the only way, +is the easiest way as all dependencies are managed for you. However, you can +also set up your own build machine and run a {ref}`build_native`. + +:::{note} +Starting with VyOS 1.2 the release model of VyOS has changed. VyOS +is now **free as in speech, but not as in beer**. This means that while +VyOS is still an open source project, the release ISOs are no longer free +and can only be obtained via subscription, or by contributing to the +community. + +The source code remains public and an ISO can be built using the process +outlined in this chapter. +::: + +(build_native)= + +### Native Build + +To build VyOS natively you require a properly configured build host with the +following Debian versions installed: + +- Debian Jessie for VyOS 1.2 (crux) +- Debian Buster for VyOS 1.3 (equuleus) +- Debian Bookworm for VyOS 1.4 (sagitta) +- Debian Bookworm or updated for VyOS 1.5 (circinus, current) - aka the + rolling release + +To start, clone the repository to your local machine: + +```none +# For VyOS 1.2 (crux) +$ git clone -b crux --single-branch https://github.com/vyos/vyos-build + +# For VyOS 1.3 (equuleus) +$ git clone -b equuleus --single-branch https://github.com/vyos/vyos-build + +# For VyOS 1.4 (sagitta) +$ git clone -b sagitta --single-branch https://github.com/vyos/vyos-build + +# For VyOS 1.5 (circinus, current) +$ git clone -b current --single-branch https://github.com/vyos/vyos-build + +$ cd vyos-build + +# For VyOS 1.2 (crux) and VyOS 1.3 (equuleus) +$ ./configure --architecture amd64 --build-by "j.randomhacker@vyos.io" +$ sudo make iso + +# For VyOS 1.4 (sagitta) and VyOS 1.5 (circinus, current) +$ sudo make clean +$ sudo ./build-vyos-image iso --architecture amd64 --build-by "j.randomhacker@vyos.io" +``` + +For the packages required, you can refer to the `docker/Dockerfile` file +in the [repository]. The `./build-vyos-image` script will also warn you if any +dependencies are missing. + +(build_docker)= + +### Docker + +This will guide you through the process of building a VyOS ISO using [Docker]. +This process has been tested on clean installs of Debian Bullseye (11) and +Bookworm (12). + +Installing [Docker] and prerequisites: + +:::{hint} +Due to the updated version of Docker, the following examples may +become invalid. + +Due to differences in version updates and build processes, content related +to VyOS 1.3 and below is no longer included below. +::: + +[On Debian] + +```none +# Add Docker's official GPG key: +$ sudo apt-get update +$ sudo apt-get install ca-certificates curl gnupg +$ sudo install -m 0755 -d /etc/apt/keyrings +$ curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg +$ sudo chmod a+r /etc/apt/keyrings/docker.gpg + +# Add the repository to Apt sources: +$ echo \ + "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \ + https://download.docker.com/linux/debian \ + $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \ + sudo tee /etc/apt/sources.list.d/docker.list > /dev/null + +$ sudo apt-get update +$ sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin +``` + +To be able to use [Docker] without `sudo`, the current non-root user must be +added to the `docker` group by calling: `sudo usermod -aG docker +yourusername`. + +:::{hint} +Doing so grants privileges equivalent to the `root` user! It is +recommended to remove the non-root user from the `docker` group after +building the VyOS ISO. See also [Docker as non-root]. +::: + +:::{note} +The build process needs to be built on a local file system, building +on SMB or NFS shares will result in the container failing to build properly! +VirtualBox Drive Share is also not an option as block device operations +are not implemented and the drive is always mounted as "nodev" +::: + +#### Build Container + +The container can be built by hand or by fetching the pre-built one from +DockerHub. Using the pre-built containers from the [VyOS DockerHub +organisation][vyos dockerhub organisation] will ensure that the container is always up-to-date. A rebuild +is triggered once the container changes (please note this will take 2-3 hours +after pushing to the vyos-build repository). + +% note: If you are using the pre-built container, it will be automatically +% downloaded from DockerHub if it is not found on your local machine when +% you build the ISO. + +##### Dockerhub + +To manually download the container from DockerHub, run: + +```none +$ docker pull vyos/vyos-build:sagitta # For VyOS 1.4 +$ docker pull vyos/vyos-build:current # For rolling release +``` + +##### Build from source + +The container can also be built directly from source: + +```none +# For VyOS 1.4 (sagitta) +$ git clone -b sagitta --single-branch https://github.com/vyos/vyos-build + +# For VyOS 1.5 (circinus, current) +$ git clone -b current --single-branch https://github.com/vyos/vyos-build + + +$ cd vyos-build +$ docker build -t vyos/vyos-build:sagitta docker # For VyOS 1.4 +$ docker build -t vyos/vyos-build:current docker # For rolling release +``` + +:::{note} +Since VyOS has switched to Debian (12) Bookworm in its `current` +branch, It is recommended to use the official Docker Hub container image +to build `equleus` and `crux`. +::: + +#### Tips and Tricks + +You can create yourself some handy Bash aliases to always launch the latest - +per release train (`current` or `sagitta`) - container. Add the following to +your `.bash_aliases` file: + +```none +alias vybld='docker pull vyos/vyos-build:current && docker run --rm -it \ + -v "$(pwd)":/vyos \ + -v "$HOME/.gitconfig":/etc/gitconfig \ + -v "$HOME/.bash_aliases":/home/vyos_bld/.bash_aliases \ + -v "$HOME/.bashrc":/home/vyos_bld/.bashrc \ + -w /vyos --privileged --sysctl net.ipv6.conf.lo.disable_ipv6=0 \ + -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) \ + vyos/vyos-build:current bash' + +alias vybld_sagitta='docker pull vyos/vyos-build:sagitta && docker run --rm -it \ + -v "$(pwd)":/vyos \ + -v "$HOME/.gitconfig":/etc/gitconfig \ + -v "$HOME/.bash_aliases":/home/vyos_bld/.bash_aliases \ + -v "$HOME/.bashrc":/home/vyos_bld/.bashrc \ + -w /vyos --privileged --sysctl net.ipv6.conf.lo.disable_ipv6=0 \ + -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) \ + vyos/vyos-build:sagitta bash' +``` + +Now you are prepared with two new aliases `vybld` and `vybld_sagitta` to +spawn your development containers in your current working directory. + +:::{note} +Some VyOS packages (namely vyos-1x) come with build-time tests which +verify some of the internal library calls that they work as expected. Those +tests are carried out through the Python Unittest module. If you want to +build the `vyos-1x` package (which is our main development package) you +need to start your Docker container using the following argument: +`--sysctl net.ipv6.conf.lo.disable_ipv6=0`, otherwise those tests will +fail. +::: + +(build_iso)= + +## Build ISO + +Now as you are aware of the prerequisites we can continue and build our own +ISO from source. For this we have to fetch the latest source code from GitHub. +Please note as this will differ for both `current` and `crux`. + +```none +# For VyOS 1.4 (sagitta) +$ git clone -b sagitta --single-branch https://github.com/vyos/vyos-build + +# For VyOS 1.5 (circinus, current) +$ git clone -b current --single-branch https://github.com/vyos/vyos-build +``` + +Now a fresh build of the VyOS ISO can begin. Change directory to the +`vyos-build` directory and run: + +```none +$ cd vyos-build + +# For VyOS 1.4 (sagitta) +$ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:sagitta bash + +# For VyOS 1.5 (circinus, current) +$ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:current bash +``` + +```none +# For MacOS (crux, equuleus, sagitta) +$ git clone https://github.com/vyos/vyos-utils-misc +$ cd build-tools/macos-build + +# For VyOS 1.2 (crux) +$ os=jessie64 branch=crux make build + +# For VyOS 1.3 (equuleus) +$ os=buster64 branch=equuleus make build + +# For VyOS 1.4 (sagitta) +$ os=buster64 branch=sagitta make build +``` + +Start the build: + +```none +# For VyOS 1.4 (sagitta) and For VyOS 1.5 (circinus, current) +vyos_bld@8153428c7e1f:/vyos$ sudo make clean +vyos_bld@8153428c7e1f:/vyos$ sudo ./build-vyos-image iso --architecture amd64 --build-by "j.randomhacker@vyos.io" +``` + +When the build is successful, the resulting iso can be found inside the +`build` directory as `live-image-[architecture].hybrid.iso`. + +Good luck! + +:::{hint} +Building VyOS on Windows WSL2 with Docker integrated into WSL2 will +work like a charm. No problems are known so far! +::: + +(build-source)= + +(customize)= + +### Customize + +This ISO can be customized with the following list of configure options. +The full and current list can be generated with `./build-vyos-image --help`: + +```none +$ vyos_bld@8153428c7e1f:/vyos$ sudo ./build-vyos-image --help + I: Checking if packages required for VyOS image build are installed + usage: build-vyos-image [-h] [--architecture ARCHITECTURE] + [--build-by BUILD_BY] [--debian-mirror DEBIAN_MIRROR] + [--debian-security-mirror DEBIAN_SECURITY_MIRROR] + [--pbuilder-debian-mirror PBUILDER_DEBIAN_MIRROR] + [--vyos-mirror VYOS_MIRROR] [--build-type BUILD_TYPE] + [--version VERSION] [--build-comment BUILD_COMMENT] [--debug] [--dry-run] + [--custom-apt-entry CUSTOM_APT_ENTRY] [--custom-apt-key CUSTOM_APT_KEY] + [--custom-package CUSTOM_PACKAGE] + [build_flavor] + + positional arguments: + build_flavor Build flavor + + optional arguments: + -h, --help show this help message and exit + --architecture ARCHITECTURE + Image target architecture (amd64 or arm64) + --build-by BUILD_BY Builder identifier (e.g. jrandomhacker@example.net) + --debian-mirror DEBIAN_MIRROR + Debian repository mirror + --debian-security-mirror DEBIAN_SECURITY_MIRROR + Debian security updates mirror + --pbuilder-debian-mirror PBUILDER_DEBIAN_MIRROR + Debian repository mirror for pbuilder env bootstrap + --vyos-mirror VYOS_MIRROR + VyOS package mirror + --build-type BUILD_TYPE + Build type, release or development + --version VERSION Version number (release builds only) + --build-comment BUILD_COMMENT + Optional build comment + --debug Enable debug output + --dry-run Check build configuration and exit + --custom-apt-entry CUSTOM_APT_ENTRY + Custom APT entry + --custom-apt-key CUSTOM_APT_KEY + Custom APT key file + --custom-package CUSTOM_PACKAGE + Custom package to install from repositories +``` + +(iso_build_issues)= + +#### ISO Build Issues + +There are (rare) situations where building an ISO image is not possible at all +due to a broken package feed in the background. APT is not very good at +reporting the root cause of the issue. Your ISO build will likely fail with a +more or less similar looking error message: + +```none +The following packages have unmet dependencies: + vyos-1x : Depends: accel-ppp but it is not installable +E: Unable to correct problems, you have held broken packages. +P: Begin unmounting filesystems... +P: Saving caches... +Reading package lists... +Building dependency tree... +Reading state information... +Del frr-pythontools 7.5-20210215-00-g8a5d3b7cd-0 [38.9 kB] +Del accel-ppp 1.12.0-95-g59f8e1b [475 kB] +Del frr 7.5-20210215-00-g8a5d3b7cd-0 [2671 kB] +Del frr-snmp 7.5-20210215-00-g8a5d3b7cd-0 [55.1 kB] +Del frr-rpki-rtrlib 7.5-20210215-00-g8a5d3b7cd-0 [37.3 kB] +make: *** [Makefile:30: iso] Error 1 +(10:13) vyos_bld ece068908a5b:/vyos [current] # +``` + +To debug the build process and gain additional information of what could be the +root cause, you need to use `chroot` to change into the build directory. This is +explained in the following step by step procedure: + +```none +vyos_bld ece068908a5b:/vyos [current] # sudo chroot build/chroot /bin/bash +``` + +We now need to mount some required, volatile filesystems + +```none +(live)root@ece068908a5b:/# mount -t proc none /proc +(live)root@ece068908a5b:/# mount -t sysfs none /sys +(live)root@ece068908a5b:/# mount -t devtmpfs none /dev +``` + +We now are free to run any command we would like to use for debugging, e.g. +re-installing the failed package after updating the repository. + +```none +(live)root@ece068908a5b:/# apt-get update; apt-get install vyos-1x +Get:1 file:/root/packages ./ InRelease +Ign:1 file:/root/packages ./ InRelease +Get:2 file:/root/packages ./ Release [1235 B] +Get:2 file:/root/packages ./ Release [1235 B] +Get:3 file:/root/packages ./ Release.gpg +Ign:3 file:/root/packages ./ Release.gpg +Hit:4 http://repo.powerdns.com/debian buster-rec-43 InRelease +Hit:5 http://repo.saltstack.com/py3/debian/10/amd64/archive/3002.2 buster InRelease +Hit:6 http://deb.debian.org/debian bullseye InRelease +Hit:7 http://deb.debian.org/debian buster InRelease +Hit:8 http://deb.debian.org/debian-security buster/updates InRelease +Hit:9 http://deb.debian.org/debian buster-updates InRelease +Hit:10 http://deb.debian.org/debian buster-backports InRelease +Hit:11 http://dev.packages.vyos.net/repositories/current current InRelease +Reading package lists... Done +N: Download is performed unsandboxed as root as file '/root/packages/./InRelease' couldn't be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied) +Reading package lists... Done +Building dependency tree +Reading state information... Done +Some packages could not be installed. This may mean that you have +requested an impossible situation or if you are using the unstable +distribution that some required packages have not yet been created +or been moved out of Incoming. +The following information may help to resolve the situation: + +The following packages have unmet dependencies: + vyos-1x : Depends: accel-ppp but it is not installable +E: Unable to correct problems, you have held broken packages. +``` + +Now it's time to fix the package mirror and rerun the last step until the +package installation succeeds again! + +(build_custom_packages)= + +### Linux Kernel + +The Linux kernel used by VyOS is heavily tied to the ISO build process. The +file `data/defaults.toml` hosts a TOML definition of the kernel version used +`kernel_version` and the `kernel_flavor` of the kernel which represents the +kernel's LOCAL_VERSION. Both together form the kernel version variable in the +system: + +```none +vyos@vyos:~$ uname -r +6.1.52-amd64-vyos +``` + +- Accel-PPP +- Intel NIC drivers +- Inter QAT + +Each of those modules holds a dependency on the kernel version and if you are +lucky enough to receive an ISO build error which sounds like: + +```none +I: Create initramfs if it does not exist. +Extra argument '6.1.52-amd64-vyos' +Usage: update-initramfs {-c|-d|-u} [-k version] [-v] [-b directory] +Options: + -k version Specify kernel version or 'all' + -c Create a new initramfs + -u Update an existing initramfs + -d Remove an existing initramfs + -b directory Set alternate boot directory + -v Be verbose +See update-initramfs(8) for further details. +E: config/hooks/live/17-gen_initramfs.chroot failed (exit non-zero). You should check for errors. +``` + +The most obvious reasons could be: + +- `vyos-build` repo is outdated, please `git pull` to update to the latest + release kernel version from us. +- You have your own custom kernel `*.deb` packages in the `packages` folder but + neglected to create all required out-of tree modules like Accel-PPP, Intel + QAT or Intel NIC drivers + +#### Building The Kernel + +The kernel build is quite easy, most of the required steps can be found in the +`vyos-build/packages/linux-kernel/Jenkinsfile` but we will walk you through +it. + +Clone the kernel source to `vyos-build/packages/linux-kernel/`: + +```none +$ cd vyos-build/packages/linux-kernel/ +$ git clone https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git +``` + +Check out the required kernel version - see `vyos-build/data/defaults.toml` +file (example uses kernel 4.19.146): + +```none +$ cd vyos-build/packages/linux-kernel/linux +$ git checkout v4.19.146 +Checking out files: 100% (61536/61536), done. +Note: checking out 'v4.19.146'. + +You are in 'detached HEAD' state. You can look around, make experimental +changes and commit them, and you can discard any commits you make in this +state without impacting any branches by performing another checkout. + +If you want to create a new branch to retain commits you create, you may +do so (now or later) by using -b with the checkout command again. Example: + + git checkout -b <new-branch-name> + +HEAD is now at 015e94d0e37b Linux 4.19.146 +``` + +Now we can use the helper script `build-kernel.sh` which does all the +necessary voodoo by applying required patches from the +`vyos-build/packages/linux-kernel/patches` folder, copying our kernel +configuration `x86_64_vyos_defconfig` to the right location, and finally +building the Debian packages. + +:::{note} +Building the kernel will take some time depending on the speed and +quantity of your CPU/cores and disk speed. Expect 20 minutes +(or even longer) on lower end hardware. +::: + +```none +(18:59) vyos_bld 412374ca36b8:/vyos/vyos-build/packages/linux-kernel [current] # ./build-kernel.sh +I: Copy Kernel config (x86_64_vyos_defconfig) to Kernel Source +I: Apply Kernel patch: /vyos/vyos-build/packages/linux-kernel/patches/kernel/0001-VyOS-Add-linkstate-IP-device-attribute.patch +patching file Documentation/networking/ip-sysctl.txt +patching file include/linux/inetdevice.h +patching file include/linux/ipv6.h +patching file include/uapi/linux/ip.h +patching file include/uapi/linux/ipv6.h +patching file net/ipv4/devinet.c +Hunk #1 succeeded at 2319 (offset 1 line). +patching file net/ipv6/addrconf.c +patching file net/ipv6/route.c +I: Apply Kernel patch: /vyos/vyos-build/packages/linux-kernel/patches/kernel/0002-VyOS-add-inotify-support-for-stackable-filesystems-o.patch +patching file fs/notify/inotify/Kconfig +patching file fs/notify/inotify/inotify_user.c +patching file fs/overlayfs/super.c +Hunk #2 succeeded at 1713 (offset 9 lines). +Hunk #3 succeeded at 1739 (offset 9 lines). +Hunk #4 succeeded at 1762 (offset 9 lines). +patching file include/linux/inotify.h +I: Apply Kernel patch: /vyos/vyos-build/packages/linux-kernel/patches/kernel/0003-RFC-builddeb-add-linux-tools-package-with-perf.patch +patching file scripts/package/builddeb +I: make x86_64_vyos_defconfig + HOSTCC scripts/basic/fixdep + HOSTCC scripts/kconfig/conf.o + YACC scripts/kconfig/zconf.tab.c + LEX scripts/kconfig/zconf.lex.c + HOSTCC scripts/kconfig/zconf.tab.o + HOSTLD scripts/kconfig/conf +# +# configuration written to .config +# +I: Generate environment file containing Kernel variable +I: Build Debian Kernel package + UPD include/config/kernel.release +/bin/sh ./scripts/package/mkdebian +dpkg-buildpackage -r"fakeroot -u" -a$(cat debian/arch) -b -nc -uc +dpkg-buildpackage: info: source package linux-4.19.146-amd64-vyos +dpkg-buildpackage: info: source version 4.19.146-1 +dpkg-buildpackage: info: source distribution buster +dpkg-buildpackage: info: source changed by vyos_bld <christian@poessinger.com> +dpkg-buildpackage: info: host architecture amd64 +dpkg-buildpackage: warning: debian/rules is not executable; fixing that + dpkg-source --before-build . + debian/rules build +make KERNELRELEASE=4.19.146-amd64-vyos ARCH=x86 KBUILD_BUILD_VERSION=1 KBUILD_SRC= + SYSTBL arch/x86/include/generated/asm/syscalls_32.h + +... + +dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory +dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory +dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory +dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory +dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory +dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory +dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory +dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory +dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory +dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory +dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory +dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory +dpkg-shlibdeps: warning: package could avoid a useless dependency if /vyos/vyos-build/packages/linux-kernel/linux/debian/toolstmp/usr/bin/trace /vyos/vyos-build/packages/linux-kernel/linux/debian/toolstmp/usr/bin/perf were not linked against libcrypto.so.1.1 (they use none of the library's symbols) +dpkg-shlibdeps: warning: package could avoid a useless dependency if /vyos/vyos-build/packages/linux-kernel/linux/debian/toolstmp/usr/bin/trace /vyos/vyos-build/packages/linux-kernel/linux/debian/toolstmp/usr/bin/perf were not linked against libcrypt.so.1 (they use none of the library's symbols) +dpkg-deb: building package 'linux-tools-4.19.146-amd64-vyos' in '../linux-tools-4.19.146-amd64-vyos_4.19.146-1_amd64.deb'. + dpkg-genbuildinfo --build=binary + dpkg-genchanges --build=binary >../linux-4.19.146-amd64-vyos_4.19.146-1_amd64.changes +dpkg-genchanges: warning: package linux-image-4.19.146-amd64-vyos-dbg in control file but not in files list +dpkg-genchanges: info: binary-only upload (no source code included) + dpkg-source --after-build . +dpkg-buildpackage: info: binary-only upload (no source included) +``` + +In the end you will be presented with the kernel binary packages which you can +then use in your custom ISO build process, by placing all the `*.deb` files in +the vyos-build/packages folder where they will be used automatically when +building VyOS as documented above. + +##### Firmware + +If you upgrade your kernel or include new drivers you may need new firmware. +Build a new `vyos-linux-firmware` package with the included helper scripts. + +```none +$ cd vyos-build/packages/linux-kernel +$ git clone https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git +$ ./build-linux-firmware.sh +$ cp vyos-linux-firmware_*.deb ../ +``` + +This tries to automatically detect which blobs are needed based on which drivers +were built. If it fails to find the correct files you can add them manually to +`vyos-build/packages/linux-kernel/build-linux-firmware.sh`: + +```bash +ADD_FW_FILES="iwlwifi* ath11k/QCA6390/*/*.bin" +``` + +#### Building Out-Of-Tree Modules + +Building the kernel is one part, but now you also need to build the required +out-of-tree modules so everything is lined up and the ABIs match. To do so, +you can again take a look at `vyos-build/packages/linux-kernel/Jenkinsfile` +to see all of the required modules and their selected versions. We will show +you how to build all the current required modules. + +##### Accel-PPP + +First, clone the source code and check out the appropriate version by running: + +```none +$ cd vyos-build/packages/linux-kernel +$ git clone https://github.com/accel-ppp/accel-ppp.git +``` + +We again make use of a helper script and some patches to make the build work. +Just run the following command: + +```none +$ ./build-accel-ppp.sh +I: Build Accel-PPP Debian package +CMake Deprecation Warning at CMakeLists.txt:3 (cmake_policy): + The OLD behavior for policy CMP0003 will be removed from a future version + of CMake. + + The cmake-policies(7) manual explains that the OLD behaviors of all + policies are deprecated and that a policy should be set to OLD only under + specific short-term circumstances. Projects should be ported to the NEW + behavior and not rely on setting a policy to OLD. + +-- The C compiler identification is GNU 8.3.0 + +... + +CPack: Create package using DEB +CPack: Install projects +CPack: - Run preinstall target for: accel-ppp +CPack: - Install project: accel-ppp +CPack: Create package +CPack: - package: /vyos/vyos-build/packages/linux-kernel/accel-ppp/build/accel-ppp.deb generated. +``` + +After compiling the packages you will find yourself the newly generated `*.deb` +binaries in `vyos-build/packages/linux-kernel` from which you can copy them +to the `vyos-build/packages` folder for inclusion during the ISO build. + +##### Intel NIC + +The Intel NIC drivers do not come from a Git repository, instead we just fetch +the tarballs from our mirror and compile them. + +Simply use our wrapper script to build all of the driver modules. + +```none +./build-intel-drivers.sh + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed +100 490k 100 490k 0 0 648k 0 --:--:-- --:--:-- --:--:-- 648k +I: Compile Kernel module for Intel ixgbe driver + +... + +I: Building Debian package vyos-intel-iavf +Doing `require 'backports'` is deprecated and will not load any backport in the next major release. +Require just the needed backports instead, or 'backports/latest'. +Debian packaging tools generally labels all files in /etc as config files, as mandated by policy, so fpm defaults to this behavior for deb packages. You can disable this default behavior with --deb-no-default-config-files flag {:level=>:warn} +Created package {:path=>"vyos-intel-iavf_4.0.1-0_amd64.deb"} +I: Cleanup iavf source +``` + +After compiling the packages you will find yourself the newly generated `*.deb` +binaries in `vyos-build/packages/linux-kernel` from which you can copy them +to the `vyos-build/packages` folder for inclusion during the ISO build. + +##### Intel QAT + +The Intel QAT (Quick Assist Technology) drivers do not come from a Git +repository, instead we just fetch the tarballs from 01.org, Intel's +open-source website. + +Simply use our wrapper script to build all of the driver modules. + +```none +$ ./build-intel-qat.sh + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed +100 5065k 100 5065k 0 0 1157k 0 0:00:04 0:00:04 --:--:-- 1157k +I: Compile Kernel module for Intel qat driver +checking for a BSD-compatible install... /usr/bin/install -c +checking whether build environment is sane... yes +checking for a thread-safe mkdir -p... /bin/mkdir -p +checking for gawk... gawk +checking whether make sets $(MAKE)... yes + +... + +I: Building Debian package vyos-intel-qat +Doing `require 'backports'` is deprecated and will not load any backport in the next major release. +Require just the needed backports instead, or 'backports/latest'. +Debian packaging tools generally labels all files in /etc as config files, as mandated by policy, so fpm defaults to this behavior for deb packages. You can disable this default behavior with --deb-no-default-config-files flag {:level=>:warn} +Created package {:path=>"vyos-intel-qat_1.7.l.4.9.0-00008-0_amd64.deb"} +I: Cleanup qat source +``` + +After compiling the packages you will find yourself the newly generated `*.deb` +binaries in `vyos-build/packages/linux-kernel` from which you can copy them +to the `vyos-build/packages` folder for inclusion during the ISO build. + +### Packages + +If you are brave enough to build yourself an ISO image containing any modified +package from our GitHub organisation - this is the place to be. + +Any "modified" package may refer to an altered version of e.g. vyos-1x package +that you would like to test before filing a pull request on GitHub. + +Building an ISO with any customized package is in no way different than +building a regular (customized or not) ISO image. Simply place your modified +`*.deb` package inside the `packages` folder within `vyos-build`. The build +process will then pickup your custom package and integrate it into your ISO. + +### Troubleshooting + +Debian APT is not very verbose when it comes to errors. If your ISO build breaks +for whatever reason and you suspect it's a problem with APT dependencies or +installation you can add this small patch which increases the APT verbosity +during ISO build. + + +```diff +diff --git i/scripts/live-build-config w/scripts/live-build-config +index 1b3b454..3696e4e 100755 +--- i/scripts/live-build-config ++++ w/scripts/live-build-config +@@ -57,7 +57,8 @@ lb config noauto \ + --firmware-binary false \ + --updates true \ + --security true \ +- --apt-options "--yes -oAcquire::Check-Valid-Until=false" \ ++ --apt-options "--yes -oAcquire::Check-Valid-Until=false -oDebug::BuildDeps=true -oDebug::pkgDepCache::AutoInstall=true \ ++ -oDebug::pkgDepCache::Marker=true -oDebug::pkgProblemResolver=true -oDebug::Acquire::gpgv=true" \ + --apt-indices false + "${@}" + """ +``` + + +### Virtualization Platforms + +#### QEMU + +Run the following command after building the ISO image. + +```none +$ make qemu +``` + +#### VMware + +Run the following command after building the QEMU image. + +```none +$ make vmware +``` + +(build-packages)= + +## Packages + +VyOS itself comes with a bunch of packages that are specific to our system and +thus cannot be found in any Debian mirror. Those packages can be found at the +[VyOS GitHub project] in their source format can easily be compiled into +a custom Debian (`*.deb`) package. + +The easiest way to compile your package is with the above mentioned +{ref}`build_docker` container, it includes all required dependencies for +all VyOS related packages. + +Assume we want to build the vyos-1x package on our own and modify it to our +needs. We first need to clone the repository from GitHub. + +```none +$ git clone https://github.com/vyos/vyos-1x +``` + +### Build + +Launch Docker container and build package + +```none +# For VyOS 1.3 (equuleus, current) +$ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:current bash + +# Change to source directory +$ cd vyos-1x + +# Build DEB +$ dpkg-buildpackage -uc -us -tc -b +``` + +After a minute or two you will find the generated DEB packages next to the +vyos-1x source directory: + +```none +# ls -al ../vyos-1x*.deb +-rw-r--r-- 1 vyos_bld vyos_bld 567420 Aug 3 12:01 ../vyos-1x_1.3dev0-1847-gb6dcb0a8_all.deb +-rw-r--r-- 1 vyos_bld vyos_bld 3808 Aug 3 12:01 ../vyos-1x-vmware_1.3dev0-1847-gb6dcb0a8_amd64.deb +``` + +### Install + +To take your newly created package on a test drive you can simply SCP it to a +running VyOS instance and install the new `*.deb` package over the current +running one. + +Just install using the following commands: + +```none +vyos@vyos:~$ dpkg --install /tmp/vyos-1x_1.3dev0-1847-gb6dcb0a8_all.deb +(Reading database ... 58209 files and directories currently installed.) +Preparing to unpack .../vyos-1x_1.3dev0-1847-gb6dcb0a8_all.deb ... +Unpacking vyos-1x (1.3dev0-1847-gb6dcb0a8) over (1.3dev0-1847-gb6dcb0a8) ... +Setting up vyos-1x (1.3dev0-1847-gb6dcb0a8) ... +Processing triggers for rsyslog (8.1901.0-1) ... +``` + +You can also place the generated `*.deb` into your ISO build environment to +include it in a custom iso, see {ref}`build_custom_packages` for more +information. + +:::{warning} +Any packages in the packages directory will be added to the iso +during build, replacing the upstream ones. Make sure you delete them (both +the source directories and built deb packages) if you want to build an iso +from purely upstream packages. +::: + + + +[docker]: https://www.docker.com +[docker as non-root]: https://docs.docker.com/engine/install/linux-postinstall +[on debian]: https://docs.docker.com/engine/install/debian/ +[repository]: https://github.com/vyos/vyos-build +[vyos dockerhub organisation]: https://hub.docker.com/u/vyos +[vyos github project]: https://github.com/vyos diff --git a/docs/contributing/md-debugging.md b/docs/contributing/md-debugging.md new file mode 100644 index 00000000..73b622c6 --- /dev/null +++ b/docs/contributing/md-debugging.md @@ -0,0 +1,191 @@ +(debugging)= + +# Debugging + +There are two flags available to aid in debugging configuration scripts. +Since configuration loading issues will manifest during boot, the flags are +passed as kernel boot parameters. + +## ISO image build + +When having trouble compiling your own ISO image or debugging Jenkins issues +you can follow the steps at {ref}`iso_build_issues`. + +## System Startup + +The system startup can be debugged (like loading in the configuration +file from `/config/config.boot`. This can be achieve by extending the +Kernel command-line in the bootloader. + +### Kernel + +- `vyos-debug` - Adding the parameter to the linux boot line will produce + timing results for the execution of scripts during commit. If one is seeing + an unexpected delay during manual or boot commit, this may be useful in + identifying bottlenecks. The internal flag is `VYOS_DEBUG`, and is found + in [vyatta-cfg]. Output is directed to `/var/log/vyatta/cfg-stdout.log`. +- `vyos-config-debug` - During development, coding errors can lead to a + commit failure on boot, possibly resulting in a failed initialization of the + CLI. In this circumstance, the kernel boot parameter `vyos-config-debug` + will ensure access to the system as user `vyos`, and will log a Python + stack trace to the file `/tmp/boot-config-trace`. + File `boot-config-trace` will generate only if config loaded with a failure + status. + +## Live System + +A number of flags can be set up to change the behaviour of VyOS at runtime. +These flags can be toggled using either environment variables or creating +files. + +For each feature, a file called `vyos.feature.debug` can be created to +toggle the feature on. If a parameter is required it can be placed inside +the file as its first line. + +The file can be placed in `/tmp` for one time debugging (as the file +will be removed on reboot) or placed in '/config' to stay permanently. + +For example, `/tmp/vyos.ifconfig.debug` can be created to enable +interface debugging. + +It is also possible to set up the debugging using environment variables. +In that case, the name will be (in uppercase) VYOS_FEATURE_DEBUG. + +For example running, `export VYOS_IFCONFIG_DEBUG=""` on your vbash, +will have the same effect as `touch /tmp/vyos.ifconfig.debug`. + +- `ifconfig` - Once set, all commands used, and their responses received + from the OS, will be presented on the screen for inspection. +- `command` - Once set, all commands used, and their responses received + from the OS, will be presented on the screen for inspection. +- `developer` - Should a command fail, instead of printing a message to the + user explaining how to report issues, the python interpreter will start a + PBD post-mortem session to allow the developer to debug the issue. As the + debugger will wait from input from the developer, it has the capacity to + prevent a router to boot and therefore should only be permanently set up + on production if you are ready to see the OS fail to boot. +- `log` - In some rare cases, it may be useful to see what the OS is doing, + including during boot. This option sends all commands used by VyOS to a + file. The default file is `/tmp/full-log` but it can be changed. + +:::{note} +In order to retrieve the debug output on the command-line you need to +disable `vyos-configd` in addition. This can be run either one-time by +calling `sudo systemctl stop vyos-configd` or make this reboot-safe by +calling `sudo systemctl disable vyos-configd`. +::: + +### FRR + +Recent versions use the `vyos.frr` framework. The Python class is located +inside our `vyos-1x:python/vyos/frr.py`. It comes with an embedded debugging/ +(print style) debugger as vyos.ifconfig does. + +To enable debugging just run: `$ touch /tmp/vyos.frr.debug` + +### Debugging Python Code with PDB + +Sometimes it might be useful to debug Python code interactively on the live +system rather than a IDE. This can be achieved using pdb. + +Let us assume you want to debug a Python script that is called by an op-mode +command. After you found the script by looking up the op-mode-defitions you +can edit the script in the live system using e.g. vi: +`vi /usr/libexec/vyos/op_mode/show_xyz.py` + +Insert the following statement right before the section where you want to +investigate a problem (e.g. a statement you see in a backtrace): +`import pdb; pdb.set_trace()` +Optionally you can surrounded this statement by an `if` which only triggers +under the condition you are interested in. + +Once you run `show xyz` and your condition is triggered you should be dropped +into the python debugger: + +```none +> /usr/libexec/vyos/op_mode/show_nat_translations.py(109)process() +-> rule_type = rule.get('type', '') +(Pdb) +``` + +You can type `help` to get an overview of the available commands, and +`help command` to get more information on each command. + +Useful commands are: + +- examine variables using `pp(var)` +- continue execution using `cont` +- get a backtrace using `bt` + +### Config Migration Scripts + +When writing a new configuration migrator it may happen that you see an error +when you try to invoke it manually on a development system. This error will +look like: + +```none +vyos@vyos:~$ /opt/vyatta/etc/config-migrate/migrate/ssh/0-to-1 /tmp/config.boot +Traceback (most recent call last): + File "/opt/vyatta/etc/config-migrate/migrate/ssh/0-to-1", line 31, in <module> + config = ConfigTree(config_file) + File "/usr/lib/python3/dist-packages/vyos/configtree.py", line 134, in __init__ + raise ValueError("Failed to parse config: {0}".format(msg)) +ValueError: Failed to parse config: Syntax error on line 240, character 1: Invalid syntax. +``` + +The reason is that the configuration migration backend is rewritten and uses +a new form of "magic string" which is applied on demand when real config +migration is run on boot. When running individual migrators for testing, +you need to convert the "magic string" on your own by: + +```none +vyos@vyos:~$ /usr/libexec/vyos/run-config-migration.py --virtual --set-vintage vyos /tmp/config.boot +``` + +### Configuration Error on System Boot + +Being brave and running the latest rolling releases will sometimes trigger +bugs due to corner cases we missed in our design. Those bugs should be filed +via [Phabricator] but you can help us to narrow down the issue. Login to your +VyOS system and change into configuration mode by typing `configure`. Now +re-load your boot configuration by simply typing `load` followed by return. + +You should now see a Python backtrace which will help us to handle the issue, +please attach it to the [Phabricator] task. + +### Boot Timing + +During the migration and extensive rewrite of functionality from Perl into +Python a significant increase in the overall system boottime was noticed. The +system boot time can be analysed and a graph can be generated in the end which +shows in detail who called whom during the system startup phase. + +This is done by utilizing the `systemd-bootchart` package which is now +installed by default on the VyOS 1.3 (equuleus) branch. The configuration is +also versioned so we get comparable results. `systemd-bootchart` is configured +using this file: [bootchart.conf] + +To enable boot time graphing change the Kernel commandline and add the following +string: `init=/usr/lib/systemd/systemd-bootchart` + +This can also be done permanently by changing `/boot/grub/grub.cfg`. + +## Priorities + +VyOS CLI is all about priorities. Every CLI node has a corresponding +`node.def` file and possibly an attached script that is executed when the +node is present. Nodes can have a priority, and on system bootup - or any +other `commit` to the config all scripts are executed from lowest to highest +priority. This is good as this gives a deterministic behavior. + +To debug issues in priorities or to see what's going on in the background +you can use the `/opt/vyatta/sbin/priority.pl` script which lists to you +the execution order of the scripts. + + +```{include} /_include/common-references.txt +``` + + +[bootchart.conf]: https://github.com/vyos/vyos-build/blob/current/data/live-build-config/includes.chroot/etc/systemd/bootchart.conf +[vyatta-cfg]: https://github.com/vyos/vyatta-cfg diff --git a/docs/contributing/md-development.md b/docs/contributing/md-development.md new file mode 100644 index 00000000..dcfe257a --- /dev/null +++ b/docs/contributing/md-development.md @@ -0,0 +1,694 @@ +(development)= + +# Development + +All VyOS source code is hosted on GitHub under the VyOS organization which can +be found here: <https://github.com/vyos> + +Our code is split into several modules. VyOS is composed of multiple individual +packages, some of them are forks of upstream packages and are periodically +synced with upstream, so keeping the whole source under a single repository +would be very inconvenient and slow. There is now an ongoing effort to +consolidate all VyOS-specific framework/config packages into vyos-1x package, +but the basic structure is going to stay the same, just with fewer and fewer +packages while the base code is rewritten from Perl/BASH into Python using and +XML based interface definition for the CLI. + +The repository that contains all the ISO build scripts is: +<https://github.com/vyos/vyos-build> + +The README.md file will guide you to use the this top level repository. + +## Submit a Patch + +Patches are always more than welcome. To have a clean and easy to maintain +repository we have some guidelines when working with Git. A clean repository +eases the automatic generation of a changelog file. + +A good approach for writing commit messages is actually to have a look at the +file(s) history by invoking `git log path/to/file.txt`. + +(prepare_commit)= + +### Prepare patch/commit + +In a big system, such as VyOS, that is comprised of multiple components, it's +impossible to keep track of all the changes and bugs/feature requests in one's +head. We use a bugtracker known as [Phabricator] for it ("issue tracker" would +be a better term, but this one stuck). + +The information is used in three ways: + +- Keep track of the progress (what we've already done in this branch and what + we still need to do). +- Prepare release notes for upcoming releases +- Help future maintainers of VyOS (it could be you!) to find out why certain + things have been changed in the codebase or why certain features have been + added + +To make this approach work, every change must be associated with a task number +(prefixed with **T**) and a component. If there is no bug report/feature request +for the changes you are going to make, you have to create a [Phabricator] task +first. Once there is an entry in [Phabricator], you should reference its id in +your commit message, as shown below: + +- `ddclient: T1030: auto create runtime directories` +- `Jenkins: add current Git commit ID to build description` + +If there is no [Phabricator] reference in the commits of your pull request, we +have to ask you to amend the commit message. Otherwise we will have to reject +it. + +#### Writing good commit messages + +The format should be and is inspired by: <https://git-scm.com/book/ch5-2.html> +It is also worth reading <https://chris.beams.io/posts/git-commit/> + +- A single, short, summary of the commit (recommended 50 characters or less, + not exceeding 80 characters) containing a prefix of the changed component + and the corresponding [Phabricator] reference e.g. `snmp: T1111:` or + `ethernet: T2222:` - multiple components could be concatenated as in + `snmp: ethernet: T3333` + +- In some contexts, the first line is treated as the subject of an email and + the rest of the text as the body. The blank line separating the summary from + the body is critical (unless you omit the body entirely); tools like rebase + can get confused if you run the two together. + +- Followed by a message which describes all the details like: + + - What/why/how something has been changed, makes everyone's life easier when + working with `git bisect` + - All text of the commit message should be wrapped at 72 characters if + possible which makes reading commit logs easier with `git log` on a + standard terminal (which happens to be 80x25) + - If applicable a reference to a previous commit should be made linking + those commits nicely when browsing the history: `After commit abcd12ef + ("snmp: this is a headline") a Python import statement is missing, + throwing the following exception: ABCDEF` + +- Always use the `-x` option to the `git cherry-pick` command when back or + forward porting an individual commit. This automatically appends the line: + `(cherry picked from commit <ID>)` to the original authors commit message + making it easier when bisecting problems. + +- Every change set must be consistent (self containing)! Do not fix multiple + bugs in a single commit. If you already worked on multiple fixes in the same + file use `git add --patch` to only add the parts related to the one issue + into your upcoming commit. + +Limits: + +- We only accept bugfixes in packages other than <https://github.com/vyos/vyos-1x> + as no new functionality should use the old style templates (`node.def` and + Perl/BASH code. Use the new style XML/Python interface instead. + +Please submit your patches using the well-known GitHub pull-request against our +repositories found in the VyOS GitHub organisation at <https://github.com/vyos> + +### Determinine source package + +Suppose you want to make a change in the webproxy script but yet you do not know +which of the many VyOS packages ship this file. You can determine the VyOS +package name in question by using Debian's `dpkg -S` command of your running +VyOS installation. + +```none +vyos@vyos:~ dpkg -S /opt/vyatta/sbin/vyatta-update-webproxy.pl +vyatta-webproxy: /opt/vyatta/sbin/vyatta-update-webproxy.pl +``` + +This means the file in question (`/opt/vyatta/sbin/vyatta-update-webproxy.pl`) +is located in the `vyatta-webproxy` package which can be found here: +<https://github.com/vyos/vyatta-webproxy> + +### Fork Repository and submit Patch + +Forking the repository and submitting a GitHub pull-request is the preferred +way of submitting your changes to VyOS. You can fork any VyOS repository to your +very own GitHub account by just appending `/fork` to any repository's URL on +GitHub. To e.g. fork the `vyos-1x` repository, open the following URL in your +favourite browser: <https://github.com/vyos/vyos-1x/fork> + +You then can proceed with cloning your fork or add a new remote to your local +repository: + +- Clone: `git clone https://github.com/<user>/vyos-1x.git` +- Fork: `git remote add myfork https://github.com/<user>/vyos-1x.git` + +In order to record you as the author of the fix please identify yourself to Git +by setting up your name and email. This can be done local for this one and only +repository `git config` or globally using `git config --global`. + +```none +git config --global user.name "J. Random Hacker" +git config --global user.email "jrhacker@example.net" +``` + +Make your changes and save them. Do the following for all changes files to +record them in your created Git commit: + +- Add file to Git index using `git add myfile`, or for a whole directory: + `git add somedir/*` +- Commit the changes by calling `git commit`. Please use a meaningful commit + headline (read above) and don't forget to reference the [Phabricator] ID. +- Submit the patch `git push` and create the GitHub pull-request. + +### Attach patch to Phabricator task + +Follow the above steps on how to "Fork repository to submit a Patch". Instead +of uploading "pushing" your changes to GitHub you can export the patches/ +commits and send it to <mailto:maintainers@vyos.net> or attach it directly to the bug +(preferred over email) + +- Export last commit to patch file: `git format-patch` or export the last two + commits into its appropriate patch files: `git format-patch -2` + +## Coding Guidelines + +Like any other project we have some small guidelines about our source code, too. +The rules we have are not there to punish you - the rules are in place to help +us all. By having a consistent coding style it becomes very easy for new +and also longtime contributors to navigate through the sources and all the +implied logic of any one source file.. + +Python 3 **shall** be used. How long can we keep Python 2 alive anyway? No +considerations for Python 2 compatibility **should** be taken at any time. + +### Formatting + +- Python: Tabs **shall not** be used. Every indentation level should be 4 spaces +- XML: Tabs **shall not** be used. Every indentation level should be 2 spaces + +:::{note} +There are extensions to e.g. VIM (xmllint) which will help you to get +your indention levels correct. Add to following to your .vimrc file: +`au FileType xml setlocal equalprg=xmllint\ --format\ --recover\ -\ +2>/dev/null` now you can call the linter using `gg=G` in command mode. +::: + +#### Text generation + +Template processor **should** be used for generating config files. Built-in +string formatting **may** be used for simple line-oriented formats where every +line is self-contained, such as iptables rules. Template processor **must** be +used for structured, multi-line formats such as those used by ISC DHCPd. + +The default template processor for VyOS code is [Jinja2]. + +### Summary + +When modifying the source code, remember these rules of the legacy elimination +campaign: + +- No new features in Perl +- No old style command definitions +- No code incompatible with Python3 + +## Python + +The switch to the Python programming language for new code is not merely a +change of the language, but a chance to rethink and improve the programming +approach. + +Let's face it: VyOS is full of spaghetti code where logic for reading the VyOS +config, generating daemon configs, and restarting processes is all mixed up. + +Python (or any other language, for that matter) does not provide automatic +protection from bad design, so we need to also devise design guidelines and +follow them to keep the system extensible and maintainable. + +But we are here to assist you and want to guide you through how you can become +a good VyOS contributor. The rules we have are not there to punish you - the +rules are in place to help us all. What does it mean? By having a consistent +coding style it becomes very easy for new contributors and also longtime +contributors to navigate through the sources and all the implied logic of +the spaghetti code. + +Please use the following template as good starting point when developing new +modules or even rewrite a whole bunch of code in the new style XML/Python +interface. + +### Configuration Script Structure and Behaviour + +Your configuration script or operation mode script which is also written in +Python3 should have a line break on 80 characters. This seems to be a bit odd +nowadays but as some people also work remotely or program using vi(m) this is +a fair good standard which I hope we can rely on. + +In addition this also helps when browsing the GitHub codebase on a mobile +device if you happen to be a crazy scientist. + +```python +#!/usr/bin/env python3 +# +# Copyright (C) 2020 VyOS maintainers and contributors +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License version 2 or later as +# published by the Free Software Foundation. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see <http://www.gnu.org/licenses/>. + +import sys + +from vyos.config import Config +from vyos import ConfigError + +def get_config(): + if config: + conf = config + else: + conf = Config() + + # Base path to CLI nodes + base = ['...', '...'] + # Convert the VyOS config to an abstract internal representation + config_data = conf.get_config_dict(base, key_mangling=('-', '_'), get_first_key=True) + return config_data + +def verify(config): + # Verify that configuration is valid + if invalid: + raise ConfigError("Descriptive message") + return True + +def generate(config): + # Generate daemon configs + pass + +def apply(config): + # Apply the generated configs to the live system + pass + +try: + c = get_config() + verify(c) + generate(c) + apply(c) +except ConfigError as e: + print(e) + sys.exit(1) +``` + +The `get_config()` function must convert the VyOS config to an abstract, +internal representation. No other function is allowed to call the `vyos.config. +Config` object method directly. The rationale for it is that when config reads +are mixed with other logic, it's very hard to change the config syntax since +you need to weed out every occurrence of the old syntax. If syntax-specific +code is confined to a single function, the rest of the code can be left +untouched as long as the internal representation remains compatible. + +Another advantage is testability of the code. Mocking the entire config +subsystem is hard, while constructing an internal representation by hand is +way simpler. + +The `verify()` function takes your internal representation of the config and +checks if it's valid, otherwise it must raise `ConfigError` with an error +message that describes the problem and possibly suggests how to fix it. It must +not make any changes to the system. The rationale for it is again testability +and, in the future when the config backend is ready and every script is +rewritten in this fashion, ability to execute commit dry run ("commit test" +like in JunOS) and abort commit before making any changes to the system if an +error is found in any component. + +The `generate()` function generates config files for system components. + +The `apply()` function applies the generated configuration to the live +system. It should use non-disruptive reload whenever possible. It may execute +disruptive operations such as daemon process restart if a particular component +does not support non-disruptive reload, or when the expected service degradation +is minimal (for example, in case of auxiliary services such as LLDPd). In case +of high impact services such as VPN daemon and routing protocols, when non- +disruptive reload is supported for some but not all types of configuration +changes, scripts authors should make effort to determine if a configuration +change can be done in a non-disruptive way and only resort to disruptive restart +if it cannot be avoided. + +Unless absolutely necessary, configuration scripts should not modify the active +configuration of system components directly. Whenever at all possible, scripts +should generate a configuration file or files that can be applied with a single +command such as reloading a service through systemd init. Inserting statements +one by one is particularly discouraged, for example, when configuring netfilter +rules, saving them to a file and loading it with iptables-restore should always +be preferred to executing iptables directly. + +The `apply()` and `generate()` functions may `raise ConfigError` if, for +example, the daemon failed to start with the updated config. It shouldn't be a +substitute for proper config checking in the `verify()` function. All +reasonable effort should be made to verify that generated configuration is +valid and will be accepted by the daemon, including, when necessary, cross- +checks with other VyOS configuration subtrees. + +Exceptions, including `VyOSError` (which is raised by `vyos.config.Config` +on improper config operations, such as trying to use `list_nodes()` on a +non-tag node) should not be silenced or caught and re-raised as config error. +Sure this will not look pretty on user's screen, but it will make way better +bug reports, and help users (and most VyOS users are IT professionals) do their +own debugging as well. + +For easy orientation we suggest you take a look on the `ntp.py` or +`interfaces-bonding.py` (for tag nodes) implementation. Both files can be +found in the [vyos-1x] repository. + +## XML (used for CLI definitions) + +The bash (or better vbash) completion in VyOS is defined in *templates*. +Templates are text files (called `node.def`) stored in a directory tree. The +directory names define the command names, and template files define the command +behaviour. Before VyOS 1.2 (crux) this files were created by hand. After a +complex redesign [process] the new style template are automatically generated +from a XML input file. + +XML interface definitions for VyOS come with a RelaxNG schema and are located +in the [vyos-1x] module. This schema is a slightly modified schema from [VyConf] +alias VyOS 2.0 So VyOS 1.2.x interface definitions will be reusable in Nextgen +VyOS Versions with very minimal changes. + +The great thing about schemas is not only that people can know the complete +grammar for certain, but also that it can be automatically verified. The +`scripts/build-command-templates` script that converts the XML definitions to +old style templates also verifies them against the schema, so a bad definition +will cause the package build to fail. I do agree that the format is verbose, but +there is no other format now that would allow this. Besides, a specialized XML +editor can alleviate the issue with verbosity. + +Example: + +```xml +<?xml version="1.0"?> +<!-- Cron configuration --> +<interfaceDefinition> + <node name="system"> + <children> + <node name="task-scheduler"> + <properties> + <help>Task scheduler settings</help> + </properties> + <children> + <tagNode name="task" owner="${vyos_conf_scripts_dir}/task_scheduler.py"> + <properties> + <help>Scheduled task</help> + <valueHelp> + <format><string></format> + <description>Task name</description> + </valueHelp> + <priority>999</priority> + </properties> + <children> + <leafNode name="crontab-spec"> + <properties> + <help>UNIX crontab time specification string</help> + </properties> + </leafNode> + <leafNode name="interval"> + <properties> + <help>Execution interval</help> + <valueHelp> + <format><minutes></format> + <description>Execution interval in minutes</description> + </valueHelp> + <valueHelp> + <format><minutes>m</format> + <description>Execution interval in minutes</description> + </valueHelp> + <valueHelp> + <format><hours>h</format> + <description>Execution interval in hours</description> + </valueHelp> + <valueHelp> + <format><days>d</format> + <description>Execution interval in days</description> + </valueHelp> + <constraint> + <regex>[1-9]([0-9]*)([mhd]{0,1})</regex> + </constraint> + </properties> + </leafNode> + <node name="executable"> + <properties> + <help>Executable path and arguments</help> + </properties> + <children> + <leafNode name="path"> + <properties> + <help>Path to executable</help> + </properties> + </leafNode> + <leafNode name="arguments"> + <properties> + <help>Arguments passed to the executable</help> + </properties> + </leafNode> + </children> + </node> + </children> + </tagNode> + </children> + </node> + </children> + </node> +</interfaceDefinition> +``` + +Command definitions are purely declarative, and cannot contain any logic. All +logic for generating config files for target applications, restarting services +and so on is implemented in configuration scripts instead. + +### GNU Preprocessor + +XML interface definition files use the `xml.in` file extension which was +implemented in {vytask}`T1843`. XML interface definitions tend to have a lot of +duplicated code in areas such as: + +- VIF (incl. VIF-S/VIF-C) +- Address +- Description +- Enabled/Disabled + +Instead of supplying all those XML nodes multiple times there are now include +files with predefined features. Brief overview: + +- [IPv4, IPv6 and DHCP(v6)] address assignment +- [IPv4, IPv6] address assignment +- [VLAN (VIF)] definition +- [MAC address] assignment + +All interface definition XML input files (.in suffix) will be sent to the GCC +preprocess and the output is stored in the `build/interface-definitions` +folder. The previously mentioned `scripts/build-command-templates` script +operates on the `build/interface-definitions` folder to generate all required +CLI nodes. + +```none +$ make interface_definitions +install -d -m 0755 build/interface-definitions +install -d -m 0755 build/op-mode-definitions +Generating build/interface-definitions/intel_qat.xml from interface-definitions/intel_qat.xml.in +Generating build/interface-definitions/interfaces-bonding.xml from interface-definitions/interfaces-bonding.xml.in +Generating build/interface-definitions/cron.xml from interface-definitions/cron.xml.in +Generating build/interface-definitions/pppoe-server.xml from interface-definitions/pppoe-server.xml.in +Generating build/interface-definitions/mdns-repeater.xml from interface-definitions/mdns-repeater.xml.in +Generating build/interface-definitions/tftp-server.xml from interface-definitions/tftp-server.xml.in +[...] +``` + +### Guidelines + +#### Use of numbers + +Use of numbers in command names **should** be avoided unless a number is a +part of a protocol name or similar. Thus, `protocols ospfv3` is perfectly +fine, but something like `server-1` is questionable at best. + +#### Help String + +To ensure uniform look and feel, and improve readability, we should follow a +set of guidelines consistently. + +##### Capitalization and punctuation + +The first word of every help string **must** be capitalized. There **must not** +be a period at the end of help strings. + +Rationale: this seems to be the unwritten standard in network device CLIs, and +a good aesthetic compromise. + +Examples: + +- Good: "Frobnication algorithm" +- Bad: "frobnication algorithm" +- Bad: "Frobnication algorithm." +- Horrible: "frobnication algorithm." + +##### Use of abbreviations and acronyms + +Abbreviations and acronyms **must** be capitalized. + +Examples: + +- Good: "TCP connection timeout" +- Bad: "tcp connection timeout" +- Horrible: "Tcp connection timeout" + +Acronyms also **must** be capitalized to visually distinguish them from normal +words: + +Examples: + +- Good: RADIUS (as in remote authentication for dial-in user services) +- Bad: radius (unless it's about the distance between a center of a circle and + any of its points) + +Some abbreviations are traditionally written in mixed case. Generally, if it +contains words "over" or "version", the letter **should** be lowercase. If +there's an accepted spelling (especially if defined by an RFC or another +standard), it **must** be followed. + +Examples: + +- Good: PPPoE, IPsec +- Bad: PPPOE, IPSEC +- Bad: pppoe, ipsec + +##### Use of verbs + +Verbs **should** be avoided. If a verb can be omitted, omit it. + +Examples: + +- Good: "TCP connection timeout" +- Bad: "Set TCP connection timeout" + +If a verb is essential, keep it. For example, in the help text of `set system +ipv6 disable-forwarding`, "Disable IPv6 forwarding on all interfaces" is a +perfectly justified wording. + +##### Prefer infinitives + +Verbs, when they are necessary, **should** be in their infinitive form. + +Examples: + +- Good: "Disable IPv6 forwarding" +- Bad: "Disables IPv6 forwarding" + +### Migrating old CLI + +```{eval-rst} +.. list-table:: + :widths: 25 25 50 + :header-rows: 1 + + * - Old concept/syntax + - New syntax + - Notes + * - mynode/node.def + - <node name="mynode"> </node> + - Leaf nodes (nodes with values) use <leafNode> tag instead + * - mynode/node.tag , tag: + - <tagNode name="mynode> </node> + - + * - help: My node + - <properties> <help>My node</help> + - + * - val_help: <format>; some string + - <properties> <valueHelp> <format> format </format> <description> some + string </description> + - Do not add angle brackets around the format, they will be inserted + automatically + * - syntax:expression: pattern + - <properties> <constraint> <regex> ... + - <constraintErrorMessage> will be displayed on failure + * - syntax:expression: $VAR(@) in "foo", "bar", "baz" + - None + - Use regex + * - syntax:expression: exec ... + - <properties> <constraint> <validator> <name ="foo" argument="bar"> + - "${vyos_libexecdir}/validators/foo bar $VAR(@)" will be executed, + <constraintErrorMessage> will be displayed on failure + * - syntax:expression: (arithmetic expression) + - None + - External arithmetic validator may be added if there's demand, complex + validation is better left to commit-time scripts + * - priority: 999 + - <properties> <priority>999</priority> + - Please leave a comment explaining why the priority was chosen + (e.g. "after interfaces are configured") + * - multi: + - <properties> <multi/> + - Only applicable to leaf nodes + * - allowed: echo foo bar + - <properties> <completionHelp> <list> foo bar </list> + - + * - allowed: cli-shell-api listNodes vpn ipsec esp-group + - <properties> <completionHelp> <path> vpn ipsec esp-group </path> ... + - + * - allowed: /path/to/script + - <properties> <completionHelp> <script> /path/to/script </script> ... + - + * - default: + - None + - Move default values to scripts + * - commit:expression: + - None + - All commit time checks should be in the verify() function of the script + * - begin:/create:/delete: + - None + - All logic should be in the scripts +``` + +## C++ Backend Code + +The CLI parser used in VyOS is a mix of bash, bash-completion helper and the +C++ backend library \[vyatta-cfg\](<https://github.com/vyos/vyatta-cfg>). This +section is a reference of common CLI commands and the respective entry point +in the C/C++ code. + +- `set` + + - <https://github.com/vyos/vyatta-cfg/blob/0f42786a0b3/src/cstore/cstore.cpp#L352> + - <https://github.com/vyos/vyatta-cfg/blob/0f42786a0b3/src/cstore/cstore.cpp#L2549> + +- `commit` + + - <https://github.com/vyos/vyatta-cfg/blob/0f42786a0b3/src/commit/commit-algorithm.cpp#L1252> + +## Continuous Integration + +VyOS makes use of [Jenkins] as our Continuous Integration (CI) service. Our +[VyOS CI] server is publicly accessible here: <https://ci.vyos.net>. You can get +a brief overview of all required components shipped in a VyOS ISO. + +To build our modules we utilize a CI/CD Pipeline script. Each and every VyOS +component comes with it's own `Jenkinsfile` which is (more or less) a copy. +The Pipeline utilizes the Docker container from the {ref}`build_iso` section - +but instead of building it from source on every run, we rather always fetch a +fresh copy (if needed) from [Dockerhub]. + +Each module is build on demand if a new commit on the branch in question is +found. After a successful run the resulting Debian Package(s) will be deployed +to our Debian repository which is used during build time. It is located here: +<http://dev.packages.vyos.net/repositories/>. + + +```{include} /_include/common-references.txt +``` + + +[dockerhub]: https://hub.docker.com/u/vyos/ +[ipv4, ipv6]: https://github.com/vyos/vyos-1x/blob/current/interface-definitions/include/interface/address-ipv4-ipv6.xml.i +[ipv4, ipv6 and dhcp(v6)]: https://github.com/vyos/vyos-1x/blob/current/interface-definitions/include/interface/address-ipv4-ipv6-dhcp.xml.i +[jenkins]: https://jenkins.io/ +[jinja2]: https://jinja.palletsprojects.com/ +[mac address]: https://github.com/vyos/vyos-1x/blob/current/interface-definitions/include/interface/mac.xml.i +[process]: https://blog.vyos.io/vyos-development-digest-10 +[vlan (vif)]: https://github.com/vyos/vyos-1x/blob/current/interface-definitions/include/interface/vif.xml.i +[vyconf]: https://github.com/vyos/vyconf/tree/master/data/schemata +[vyos-1x]: https://github.com/vyos/vyos-1x/tree/current/schema diff --git a/docs/contributing/md-issues-features.md b/docs/contributing/md-issues-features.md new file mode 100644 index 00000000..6a748f36 --- /dev/null +++ b/docs/contributing/md-issues-features.md @@ -0,0 +1,73 @@ +(issues_features)= + +# Issues/Feature requests + +(bug_report)= + +## Bug Report/Issue + +Issues or bugs are found in any software project. VyOS is not an exception. + +All issues should be reported to the developers. This lets the developers know +what is not working properly. Without this sort of feedback every developer +will believe that everything is working correctly. + +### I have found a bug, what should I do? + +When you believe you have found a bug, it is always a good idea to verify the +issue prior to opening a bug request. + +- Consult the [documentation] to ensure that you have configured your system + correctly +- Get community support via [Slack] or our [Forum] + +### Ensure the problem is reproducible + +When you are able to verify that it is actually a bug, spend some time to +document how to reproduce the issue. This documentation can be invaluable. + +When you wish to have a developer fix a bug that you found, helping them +reproduce the issue is beneficial to everyone. Be sure to include information +about the hardware you are using, commands that you were running, any other +activities that you may have been doing at the time. This additional +information can be very useful. + +- What were you attempting to achieve? +- What was the configuration prior to the change? +- What commands did you use? Use e.g. `run show configuration commands` + +### Include output + +The output you get when you find a bug can provide lots of information. If you +get an error message on the screen, copy it exactly. Having the exact message +can provide detail that the developers can use. Like wise if you have any log +messages that also are from the time of the issue, include those. They may +also contain information that is helpful for the development team. + +### Report a Bug + +In order to open up a bug-report/feature request you need to create yourself +an account on VyOS [Phabricator]. On the left side of the specific project (VyOS +1.2 or VyOS 1.3) you will find quick-links for opening a bug-report/feature +request. + +- Provide as much information as you can +- Which version of VyOS are you using? `run show version` +- How can we reproduce this Bug? + +(feature-request)= + +## Feature Request + +You have an idea of how to make VyOS better or you are in need of a specific +feature which all users of VyOS would benefit from? To send a feature request +please search [Phabricator] if there is already a request pending. You can +enhance it or if you don't find one, create a new one by use the quick link in +the left side under the specific project. + +```{include} /_include/common-references.txt +``` + +[documentation]: https://docs.vyos.io +[forum]: https://forum.vyos.io +[slack]: https://slack.vyos.io diff --git a/docs/contributing/md-testing.md b/docs/contributing/md-testing.md new file mode 100644 index 00000000..b2929936 --- /dev/null +++ b/docs/contributing/md-testing.md @@ -0,0 +1,214 @@ +(testing)= + +# Testing + +One of the major advantages introduced in VyOS 1.3 is an automated test +framework. When assembling an ISO image multiple things can go wrong badly and +publishing a faulty ISO makes no sense. The user is disappointed by the quality +of the image and the developers get flodded with bug reports over and over +again. + +As the VyOS documentation is not only for users but also for the developers - +and we keep no secret documentation - this section describes how the automated +testing works. + +## Jenkins CI + +Our [VyOS CI] system is based on Jenkins and builds all our required packages +for VyOS 1.2 to 1.4. In addition to the package build, there is the vyos-build +Job which builds and tests the VyOS ISO image which is published after a +successful test drive. + +We differentiate in two independent tests, which are both run in parallel by +two separate QEmu instances which are launched via `make test` and `make +testc` from within the [vyos-build] repository. + +## Smoketests + +Smoketests executes predefined VyOS CLI commands and checks if the desired +daemon/service configuration is rendert - that is how to put it "short". + +When and ISO image is assembled by the [VyOS CI], the `BUILD_SMOKETEST` +parameter is enabled by default, which will extend the ISO configuration line +with the following packages: + +```python +def CUSTOM_PACKAGES = '' + if (params.BUILD_SMOKETESTS) + CUSTOM_PACKAGES = '--custom-package vyos-1x-smoketest' +``` + +So if you plan to build your own custom ISO image and want to make use of our +smoketests, ensure that you have the `vyos-1x-smoketest` package installed. + +The `make test` command from the [vyos-build] repository will launch a new +QEmu instance and the ISO image is first installed to the virtual harddisk. + +After its first boot into the newly installed system the main Smoketest script +is executed, it can be found here: `/usr/bin/vyos-smoketest` + +The script only searches for executable "test-cases" under +`/usr/libexec/vyos/tests/smoke/cli/` and executes them one by one. + +:::{note} +As Smoketests will alter the system configuration and you are logged +in remote you may loose your connection to the system. +::: + +### Manual Smoketest Run + +On the other hand - as each test is contain in its own file - one can always +execute a single Smoketest by hand by simply running the Python test scripts. + +Example: + +```none +vyos@vyos:~$ /usr/libexec/vyos/tests/smoke/cli/test_protocols_bgp.py +test_bgp_01_simple (__main__.TestProtocolsBGP) ... ok +test_bgp_02_neighbors (__main__.TestProtocolsBGP) ... ok +test_bgp_03_peer_groups (__main__.TestProtocolsBGP) ... ok +test_bgp_04_afi_ipv4 (__main__.TestProtocolsBGP) ... ok +test_bgp_05_afi_ipv6 (__main__.TestProtocolsBGP) ... ok +test_bgp_06_listen_range (__main__.TestProtocolsBGP) ... ok +test_bgp_07_l2vpn_evpn (__main__.TestProtocolsBGP) ... ok +test_bgp_08_zebra_route_map (__main__.TestProtocolsBGP) ... ok +test_bgp_09_distance_and_flowspec (__main__.TestProtocolsBGP) ... ok +test_bgp_10_vrf_simple (__main__.TestProtocolsBGP) ... ok +test_bgp_11_confederation (__main__.TestProtocolsBGP) ... ok +test_bgp_12_v6_link_local (__main__.TestProtocolsBGP) ... ok +test_bgp_13_solo (__main__.TestProtocolsBGP) ... ok + +---------------------------------------------------------------------- +Ran 13 tests in 348.191s + +OK +``` + +### Interface based tests + +Our smoketests not only test daemons and serives, but also check if what we +configure for an interface works. Thus there is a common base classed named: +`base_interfaces_test.py` which holds all the common code that an interface +supports and is tested. + +Those common tests consists out of: + +- Add one or more IP addresses + +- DHCP client and DHCPv6 prefix delegation + +- MTU size + +- IP and IPv6 options + +- Port description + +- Port disable + +- VLANs (QinQ and regular 802.1q) + +- ... + +:::{note} +When you are working on interface configuration and you also want to +test if the Smoketests pass you would normally loose the remote SSH connection +to your {abbr}`DUT (Device Under Test)`. To handle this issue, some of the +interface based tests can be called with an environment variable beforehand +to limit the number of interfaces used in the test. By default all interface +e.g. all Ethernet interfaces are used. +::: + +```none +vyos@vyos:~$ TEST_ETH="eth1 eth2" /usr/libexec/vyos/tests/smoke/cli/test_interfaces_bonding.py +test_add_multiple_ip_addresses (__main__.BondingInterfaceTest) ... ok +test_add_single_ip_address (__main__.BondingInterfaceTest) ... ok +test_bonding_hash_policy (__main__.BondingInterfaceTest) ... ok +test_bonding_lacp_rate (__main__.BondingInterfaceTest) ... ok +test_bonding_min_links (__main__.BondingInterfaceTest) ... ok +test_bonding_remove_member (__main__.BondingInterfaceTest) ... ok +test_dhcpv6_client_options (__main__.BondingInterfaceTest) ... ok +test_dhcpv6pd_auto_sla_id (__main__.BondingInterfaceTest) ... ok +test_dhcpv6pd_manual_sla_id (__main__.BondingInterfaceTest) ... ok +test_interface_description (__main__.BondingInterfaceTest) ... ok +test_interface_disable (__main__.BondingInterfaceTest) ... ok +test_interface_ip_options (__main__.BondingInterfaceTest) ... ok +test_interface_ipv6_options (__main__.BondingInterfaceTest) ... ok +test_interface_mtu (__main__.BondingInterfaceTest) ... ok +test_ipv6_link_local_address (__main__.BondingInterfaceTest) ... ok +test_mtu_1200_no_ipv6_interface (__main__.BondingInterfaceTest) ... ok +test_span_mirror (__main__.BondingInterfaceTest) ... ok +test_vif_8021q_interfaces (__main__.BondingInterfaceTest) ... ok +test_vif_8021q_lower_up_down (__main__.BondingInterfaceTest) ... ok +test_vif_8021q_mtu_limits (__main__.BondingInterfaceTest) ... ok +test_vif_8021q_qos_change (__main__.BondingInterfaceTest) ... ok +test_vif_s_8021ad_vlan_interfaces (__main__.BondingInterfaceTest) ... ok +test_vif_s_protocol_change (__main__.BondingInterfaceTest) ... ok + +---------------------------------------------------------------------- +Ran 23 tests in 244.694s + +OK +``` + +This will limit the `bond` interface test to only make use of `eth1` and `eth2` +as member ports. + +## Config Load Tests + +The other part of our tests are called "config load tests". The config load tests +will load - one after another - arbitrary configuration files to test if the +configuration migration scripts work as designed and that a given set of +functionality still can be loaded with a fresh VyOS ISO image. + +The configurations are all derived from production systems and can not only act +as a testcase but also as reference if one wants to enable a certain feature. +The configurations can be found here: +<https://github.com/vyos/vyos-1x/tree/current/smoketest/configs> + +The entire test is controlled by the main wrapper script `/usr/bin/vyos-configtest` +which behaves in the same way as the main smoketest script. It scans the folder +for potential configuration files and issues a `load` command one after another. + +### Manual config load test + +One is not bound to load all configurations one after another but can also load +individual test configurations on his own. + +```none +vyos@vyos:~$ configure +load[edit] + +vyos@vyos# load /usr/libexec/vyos/tests/config/ospf-small +Loading configuration from '/usr/libexec/vyos/tests/config/ospf-small' +Load complete. Use 'commit' to make changes effective. +[edit] +vyos@vyos# compare +[edit interfaces ethernet eth0] +-hw-id 00:50:56:bf:c5:6d +[edit interfaces ethernet eth1] ++duplex auto +-hw-id 00:50:56:b3:38:c5 ++speed auto +[edit interfaces] +-ethernet eth2 { +- hw-id 00:50:56:b3:9c:1d +-} +-vti vti1 { +- address 192.0.2.1/30 +-} +... + +vyos@vyos# commit +vyos@vyos# +``` + +:::{note} +Some of the configurations have preconditions which need to be met. +Those most likely include generation of crypographic keys before the config +can be applied - you will get a commit error otherwise. If you are interested +how those preconditions are fulfilled check the [vyos-build] repository and +the `scripts/check-qemu-install` file. +::: + +```{include} /_include/common-references.txt +``` diff --git a/docs/contributing/md-upstream-packages.md b/docs/contributing/md-upstream-packages.md new file mode 100644 index 00000000..6e7a7fb6 --- /dev/null +++ b/docs/contributing/md-upstream-packages.md @@ -0,0 +1,79 @@ +(upstream-packages)= + +# Upstream packages + +Many base system packages are pulled straight from Debian's main and contrib +repositories, but there are exceptions. + +This chapter lists those exceptions and gives you a brief overview what we +have done on those packages. If you only want to build yourself a fresh ISO +you can completely skip this chapter. It may become interesting once you have +a VyOS deep dive. + +## vyos-netplug + +Due to issues in the upstream version that sometimes set interfaces down, a +modified version is used. + +The source is located at <https://github.com/vyos/vyos-netplug> + +In the future, we may switch to using systemd infrastructure instead. Building +it doesn't require a special procedure. + +## keepalived + +Keepalived normally isn't updated to newer feature releases between Debian +versions, so we are building it from source. + +Debian does keep their package in git, but it's upstream tarball imported into +git without its original commit history. To be able to merge new tags in, we +keep a fork of the upstream repository with packaging files imported from +Debian at <https://github.com/vyos/keepalived-upstream> + +## strongswan + +Our StrongSWAN build differs from the upstream: + +- strongswan-nm package build is disabled since we don't use NetworkManager +- Patches for DMVPN are merged in + +The source is at <https://github.com/vyos/vyos-strongswan> + +DMVPN patches are added by this commit: +<https://github.com/vyos/vyos-strongswan/commit/1cf12b0f2f921bfc51affa3b81226> + +Our op mode scripts use the python-vici module, which is not included in +Debian's build, and isn't quite easy to integrate in that build. For this +reason we debianize that module by hand now, using this procedure: + +0. Install <https://pypi.org/project/stdeb/> +1. `cd vyos-strongswan` +2. `./configure --enable-python-eggs` +3. `cd src/libcharon/plugins/vici/python` +4. `make` +5. `python3 setup.py --command-packages=stdeb.command bdist_deb` + +The package ends up in deb_dist dir. + +## mdns-repeater + +This package doesn't exist in Debian. A debianized fork is kept at +<https://github.com/vyos/mdns-repeater> + +No special build procedure is required. + +## udp-broadcast-relay + +This package doesn't exist in Debian. A debianized fork is kept at +<https://github.com/vyos/udp-broadcast-relay> + +No special build procedure is required. + +## hvinfo + +A fork with packaging changes for VyOS is kept at <https://github.com/vyos/hvinfo> + +The original repo is at <https://github.com/dmbaturin/hvinfo> + +It's an Ada program and requires GNAT and gprbuild for building, dependencies +are properly specified so just follow debuild's suggestions. diff --git a/docs/installation/cloud/md-aws-ha.md b/docs/installation/cloud/md-aws-ha.md new file mode 100644 index 00000000..f32e2ab5 --- /dev/null +++ b/docs/installation/cloud/md-aws-ha.md @@ -0,0 +1,135 @@ +# VyOS High Availability (HA) Deployment on AWS + +This document describes how to deploy VyOS in a High Availability (HA) configuration on AWS using Terraform and a VPC Route Server to provide sub-second failover. + +## Why Use HA on AWS? + +This solution helps organizations achieve **high availability** routing with dynamic connectivity to multiple AWS VPCs or hybrid environments. + +Key Advantages: + +- Utilizes **AWS VPC Route Server** to manage BGP routes dynamically. + +- Deploys two VyOS EC2 instances as BGP peers connected to the Route Server. Although both participate, one is typically preferred as the next-hop. + +- Employs **Bidirectional Forwarding Detection (BFD)** for rapid failure detection. + +- On failure: + + - Withdraws the failed peer’s routes from the RIB. + - Recomputes the optimal path in the FIB. + - Updates VPC route tables to point to the active instance. + +- Enables **sub-second failover** (< 1 s), outperforming AWS API-based route table failover. + +This architecture supports: + +- Cloud edge routing with failover. +- Hybrid cloud resiliency. +- Rapid recovery during instance crashes, upgrades, or network disruptions. +- Continuity for mission-critical operations. + +## HA Architecture Diagram + +:::{figure} /_static/images/cloud-aws-ha-architecture.png +:alt: VyOS HA topology diagram +::: + +## Terraform Automation + +To streamline and standardize the process, we developed a Terraform project that automates the deployment of VyOS in High Availability (HA) mode on AWS. + +This Terraform project automates the deployment of: + +- Two VyOS instances in HA mode. +- VPC Route Server. +- Transit Gateway. +- A Transit VPC and a Data VPC containing a test Amazon Linux EC2 instance for connectivity validation. + +To integrate with existing AWS infrastructure: + +- Remove the Data VPC, its subnets, and EC2 test instance. +- Update `main.tf`, `network.tf`, `transit_gateway.tf`, `variables.tf`, and `outputs.tf` accordingly. + +## Prerequisites + +AWS Environment: + +- Active AWS account with permissions for EC2, VPC, Transit Gateway, Route Server, and IAM (for keypair and role management). + +Local Environment: + +- AWS CLI installed: <https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html> +- Terraform installed: <https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli> + +Set AWS credentials in your shell: + +```none +export AWS_ACCESS_KEY_ID="<AWS_ACCESS_KEY_ID>" +export AWS_SECRET_ACCESS_KEY="<AWS_SECRET_ACCESS_KEY>" +export AWS_SESSION_TOKEN="<AWS_SESSION_TOKEN>" +export AWS_DEFAULT_REGION="<AWS_REGION>" # e.g., us-east-1 +``` + +Obtain VyOS AMI ID and Owner ID: + +Subscribe to VyOS via AWS Marketplace. Then run: + +```none +aws ec2 describe-images \ + --owners aws-marketplace \ + --filters "Name=product-code,Values=8wqdkv3u2b9sa0y73xob2yl90" \ + --query 'Images[*].[ImageId,OwnerId,Name]' \ + --output table +``` + +Alternatively, set the `vyos_ami_id` variable directly in `variables.tf`. + +Generate an SSH keypair (or use the included demo key): + +```none +ssh-keygen -b 2048 -t rsa -m PEM -f keys/vyos_custom_key.pem +chmod 400 keys/vyos_custom_key.pem +``` + +## Usage + +Configure variables in `variables.tf`, including instance type, region, and `vyos_ami_id`. + +Terraform Workflow: + +```none +terraform init +terraform fmt +terraform validate +terraform plan +terraform apply +``` + +On completion, run: + +```none +terraform output +``` + +This displays the management IP and connectivity test results. + +To clean up: + +```none +terraform destroy +``` + +## Management + +SSH into VyOS: + +```none +ssh vyos@<vyos_public_ip> -i keys/vyos_custom_key.pem +``` + +## GitHub Repository + +You can clone or download the Terraform project and use them in your environment: + +<https://github.com/vyos/vyos-automation/tree/main/Terraform/AWS/ha-instances-with-configs> diff --git a/docs/installation/cloud/md-aws-to-azure.md b/docs/installation/cloud/md-aws-to-azure.md new file mode 100644 index 00000000..246df5f3 --- /dev/null +++ b/docs/installation/cloud/md-aws-to-azure.md @@ -0,0 +1,175 @@ +# VyOS Deployment on AWS and Azure for Secure Cloud-to-Cloud Connectivity + +This document provides step-by-step guidance for deploying VyOS routers on both AWS and Azure. +It describes how to establish secure inter-cloud connectivity using IPsec tunnels with BGP, +automated through Terraform. Example workloads (Amazon Linux EC2 on AWS and Ubuntu VM on Azure) +are also deployed for connectivity validation. + +## Why Cloud-to-Cloud Connectivity? + +Cloud-to-cloud connectivity is needed in modern multi-cloud environments for several reasons: + +- **Inter-Cloud Connectivity** + + Enable secure and reliable communication between workloads in different clouds + (for example, AWS applications connecting to Azure-hosted identity services). + +- **Cloud-to-Cloud Migration** + + During migration projects, workloads may temporarily run in both clouds. + Direct tunnels ensure smooth transition and synchronization. + +- **Testing and Validation** + + Labs and proof-of-concepts often simulate multi-cloud architectures. + A VyOS-based tunnel lets teams test routing, encryption, and failover before production rollout. + +## Architecture + +The architecture consists of VyOS routers deployed in both AWS and Azure, connected via secure IPsec tunnels. +BGP is used for dynamic routing between the clouds, allowing for seamless communication. + +:::{figure} /_static/images/cloud-aws-to-azure.png +:alt: VyOS Cloud-to-Cloud topology diagram +::: + +## Terraform Automation + +To streamline and standardize the deployment process, a set of **Terraform projects** has been developed. +These projects automate the provisioning of **VyOS instances** and the required networking resources across **AWS** and **Azure**. + +In addition to deploying VyOS, these projects also provision an **Amazon Linux EC2 instance** on AWS and an **Ubuntu VM** on Azure. +These serve as test endpoints to validate connectivity between the cloud environments. + +## Prerequisites + +### AWS Environment + +- Active AWS account with permissions for EC2, VPC, Transit Gateway, Route Server, and IAM (for keypair and role management). + +Local Environment: + +- AWS CLI installed: <https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html> +- Terraform installed: <https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli> + +Set AWS credentials in your shell: + +```none +export AWS_ACCESS_KEY_ID="<AWS_ACCESS_KEY_ID>" +export AWS_SECRET_ACCESS_KEY="<AWS_SECRET_ACCESS_KEY>" +export AWS_SESSION_TOKEN="<AWS_SESSION_TOKEN>" +export AWS_DEFAULT_REGION="<AWS_REGION>" # e.g., us-east-1 +``` + +Obtain VyOS AMI ID and Owner ID: + +Subscribe to VyOS via AWS Marketplace. Then run: + +```none +aws ec2 describe-images \ + --owners aws-marketplace \ + --filters "Name=product-code,Values=8wqdkv3u2b9sa0y73xob2yl90" \ + --query 'Images[*].[ImageId,OwnerId,Name]' \ + --output table +``` + +Alternatively, set the `vyos_ami_id` variable directly in `variables.tf`. + +Generate an SSH keypair (or use the included demo key): + +```none +ssh-keygen -b 2048 -t rsa -m PEM -f keys/vyos_custom_key.pem +chmod 400 keys/vyos_custom_key.pem +``` + +### Azure Environment + +- Active Azure subscription: + +```none +az account set --subscription "<subscription ID or name>" +``` + +- Azure CLI installed: + + <https://learn.microsoft.com/en-us/cli/azure/install-azure-cli> + +- Logged in with Azure credentials: + +```none +az version +az login +``` + +- Azure Resource Group (RG) created: + +```none +az group create --name demoResourceGroup --location westus +az group list +az group show --name demoResourceGroup +``` + +- Terraform installed: + + <https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli> + +- SSH key generated: + +```none +ssh-keygen -t rsa -b 4096 -f keys/id_rsa +chmod 400 keys/id_rsa +``` + +## Usage + +### AWS + +All variables needed for customization are defined in `variables.tf`. +Adjust them according to your requirements, such as EC2 instance type and networking configurations. + +Before deployment, ensure you check `aws_region`, `availability_zone`, and update `vyos_ami_id` as necessary. + +### Azure + +All variables needed for customization are defined in `variables.tf`. +Adjust them according to your requirements, such as VM size and networking configurations. + +Before deployment, ensure you check `azure_region`, `availability_zone`, and update `subscription_id` and `resource_group_name` as necessary. + +### Terraform Workflow + +```none +terraform init +terraform fmt +terraform validate +terraform plan +terraform apply +``` + +On completion, run: + +```none +terraform output +``` + +This displays the public IP addresses of the VyOS instances. + +To clean up: + +```none +terraform destroy +``` + +## Management + +SSH into VyOS: + +```none +ssh vyos@<vyos_public_ip> -i keys/vyos_custom_key.pem +``` + +## GitHub Repository + +You can clone or download the Terraform projects and use them in your environment: + +<https://github.com/vyos/vyos-automation/tree/main/Terraform/Cloud-to-Cloud> diff --git a/docs/installation/cloud/md-azure-ha.md b/docs/installation/cloud/md-azure-ha.md new file mode 100644 index 00000000..fa94c222 --- /dev/null +++ b/docs/installation/cloud/md-azure-ha.md @@ -0,0 +1,128 @@ +# VyOS High Availability (HA) Deployment on Azure + +This document describes how to deploy VyOS in a High Availability (HA) configuration on Azure using Terraform and Azure Route Server to provide sub-second failover. + +## Why Use HA on Azure? + +This module provides a robust, repeatable foundation for building **resilient network architectures** in Azure. By combining VyOS routing features with Terraform and Azure-native services, it enables: + +- Rapid deployment of cloud edge routers. +- Full control over BGP route advertisement and filtering. +- Realistic HA and disaster recovery simulations. +- Seamless integration with hybrid or multi-cloud infrastructure. + +The architecture includes: + +- Two VyOS routers in a Transit VNet, configured with BGP. +- Azure Route Server for dynamic route distribution. +- Site-to-Site VPN connections to a simulated on-premises VyOS router. +- An Ubuntu VM for connectivity and routing validation. +- A Data VNet for testing and diagnostics. + +## Key Features + +- **High Availability**: Dual VyOS routers for redundancy and failover. +- **Dynamic Routing**: BGP-based routing via Azure Route Server. +- **Hybrid Connectivity**: Site-to-Site VPN integration with a simulated on-prem VyOS. +- **Testing Environment**: Includes Ubuntu VM for verification and diagnostics. +- **Modular & Flexible**: Easily configurable via variables. + +## HA Architecture Diagram + +:::{figure} /_static/images/cloud-azure-ha-architecture.png +:alt: VyOS HA topology diagram +::: + +This deployment architecture simulates a real-world enterprise network scenario for testing and validation purposes. + +## Terraform Automation + +To streamline and standardize the process, we developed a Terraform project that automates the deployment of VyOS in High Availability (HA) mode on Azure. + +This Terraform project automates the deployment of: + +- Two VyOS instances in HA mode. +- Azure Route Server. +- A Transit VNet and a Data VNet containing a test Ubuntu VM for connectivity validation. + +## Prerequisites + +Ensure you have: + +- Active Azure subscription: + +```none +az account set --subscription "<subscription ID or name>" +``` + +- Azure CLI installed: + + <https://learn.microsoft.com/en-us/cli/azure/install-azure-cli> + +- Logged in with Azure credentials: + +```none +az version +az login +``` + +- Azure Resource Group (RG) created: + +```none +az group create --name demoResourceGroup --location westus +az group list +az group show --name demoResourceGroup +``` + +- Terraform installed: + + <https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli> + +- SSH key generated: + +```none +ssh-keygen -t rsa -b 4096 -f keys/vyos_custom_key.pem +chmod 400 keys/vyos_custom_key.pem +``` + +## Usage + +All variables are defined in `variables.tf`. Adjust them to match your environment. + +Terraform Workflow: + +```none +terraform init +terraform fmt +terraform validate +terraform plan +terraform apply +``` + +On completion, run: + +```none +terraform output +``` + +This displays the management IP and connectivity test results. + +To clean up: + +```none +terraform destroy +``` + +## Management + +SSH into VyOS: + +```none +ssh adminuser@<vyos_public_ip> -i keys/vyos_custom_key.pem +``` + +## GitHub Repository + +You can clone or download the Terraform project and use them in your environment: + +<https://github.com/vyos/vyos-automation/tree/main/Terraform/Azure/azure-ha-deployment-with-configs> diff --git a/docs/installation/cloud/md-azure.md b/docs/installation/cloud/md-azure.md new file mode 100644 index 00000000..aa577aa1 --- /dev/null +++ b/docs/installation/cloud/md-azure.md @@ -0,0 +1,378 @@ +# VyOS Deployment on Azure + +This manual provides detailed step-by-step instructions for deploying a VyOS instance and required resources (Virtual Networks, Network Interfaces, Subnets, Security Groups) on Azure via the Azure Portal. + +## Prerequisites for Deploying VyOS on Azure + +### Azure Account + +Ensure you have an active Azure subscription. + +### Microsoft Entra ID Permissions + +To manage resources in **Azure Entra ID** (formerly Azure AD), you need appropriate permissions to handle **Virtual Networks**, **Public IP Addresses**, **Subnets**, and **Virtual Machines**. + +**Reference Documentation:** + +<https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/manage-roles-portal> + +<https://learn.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal> + +<https://learn.microsoft.com/en-us/azure/role-based-access-control/overview> + +## Deployment Steps + +### Step 1: Create a Resource Group + +A resource group is a container that holds related resources for an Azure solution. The resource group can include all the resources for the solution, or only those resources that you want to manage as a group. + +#### Create resource groups + +- Go to the Azure Portal <https://portal.azure.com/>. +- Sign in with your Azure account credentials. +- In the portal, search for and select **Resource groups**. +- Select **Create**. + +:::{figure} /_static/images/cloud-azure-rg-01.png +::: + +- Enter the following values: +- **Subscription**: Select your Azure subscription. +- **Resource group**: Enter a new resource group name, e.g., `VyOSResourceGroup`. +- **Region**: Select an Azure location, such as Central US. +- Select **Review + Create** +- Select **Create**. It takes a few seconds to create a resource group. + +:::{figure} /_static/images/cloud-azure-rg-02.png +::: + +### Step 2: Create a Virtual Network (VNet) and Subnets + +Sign in to the Azure portal with your Azure account <https://portal.azure.com/> + +- In the portal, search for and select **Virtual networks**. +- On the **Virtual networks** page, select **+ Create**. +- On the **Basics** tab of **Create virtual network**, enter, or select the following information: +- **Subscription**: Select your Subscription +- **Resource Group**: Select e.g., `VyOSResourceGroup` +- **Name**: e.g., `VyOS-VirtualNetwork` +- **Region**: e.g., `West Europe`. + +:::{figure} /_static/images/cloud-azure-vnet-01.png +::: + +**IP addresses**: + +- Address Space: `10.1.0.0/16` + +:::{figure} /_static/images/cloud-azure-vnet-02.png +::: + +**Add two subnets**: + +- Name: e.g., `VyOS-Private-Subnet` + + Starting address: e.g., `10.1.1.0` + + Size: `/24` + +- Name: e.g., `VyOS-Public-Subnet` + + Starting address: e.g., `10.1.11.0` + + Size: `/24` + +:::{figure} /_static/images/cloud-azure-vnet-03.png +::: + +:::{figure} /_static/images/cloud-azure-vnet-04.png +::: + +:::{figure} /_static/images/cloud-azure-vnet-05.png +::: + +- Click **Review + Create** and then **Create**. + +### Step 3: Create and configure Network Security Group (NSG) + +- In the Azure Portal, search for and select **Network Security Groups**. +- On the **Network Security Groups** page, select **+ Create**. + +Enter the details: + +- **Subscription**: Select your Subscription +- **Resource Group**: Select `VyOSResourceGroup` +- **Name**: e.g., `VyOS-SecurityGroup` +- **Region**: e.g., `West Europe`. + +:::{figure} /_static/images/cloud-azure-sg-01.png +::: + +- Click **Review + Create** and then **Create**. + +**Add inbound rules**: + +- Navigate to the **Network Security Groups** select **VyOS-SecurityGroup** go to **Inbound security rules** under **Settings** + +:::{figure} /_static/images/cloud-azure-sg-02.png +::: + +**Add Rule Example:** + +- **Rule 1**: AllowSSH + + > - **Port**: 22 + > - **Protocol**: TCP + > - **Source**: Any + > - **Priority**: 1001 + +**Add Additional Rules**: + +You can add inbound rules based on your specific services, such as: + +> - ESP +> - OpenVPN +> - WireGuard, etc. + +:::{figure} /_static/images/cloud-azure-sg-03.png +::: + +**Associate subnets**: + +- Navigate to the **Network Security Groups**, select **Subnets** click **+ Associate** button. Then select your virtual network and the subnet to which you want to associate the NSG. Select **OK**: + +:::{figure} /_static/images/cloud-azure-sg-04.png +::: + +### Step 4: Create Public IP Address + +- In the Azure Portal, search for and select **Public IP Addresses**. +- On the **Public IP Addresses** page, select **+ Create**. +- Provide the following details: +- **Subscription**: Select your Subscription +- **Resource Group**: Select `VyOSResourceGroup` +- **Region**: `West Europe` + +:::{figure} /_static/images/cloud-azure-pub-ip-01.png +::: + +- **Name**: `VyOS-Pub-IP` +- **IP Version**: `IPv4` +- **SKU**: `Standard` +- **Availability zone**: Select Availability Zone + +:::{figure} /_static/images/cloud-azure-pub-ip-02.png +::: + +- **IP address assignment**: `Static` +- **Idle timeout (minutes)** `30` (max) + +:::{figure} /_static/images/cloud-azure-pub-ip-03.png +::: + +- Click **Review + Create**, then **Create**. + +### Step 5: Deploy the VyOS Network Virtual Machine (NVA) + +- In the Azure Portal, search for and select **Virtual Machines**. +- On the **Virtual Machines** page, click **+ Create** and select **Azure virtual machine**. +- Provide the following details: +- **Subscription**: Select your Subscription +- **Resource Group**: Select `VyOSResourceGroup` +- **Virtual machine name**: e.g., `VyOS` +- **Region**: e.g., `West Europe` +- **Security type**: `Standard` +- **Image**: `VyOS` (On the marketplace search `VyOS` and choose the appropriate subscription). + +:::{figure} /_static/images/cloud-azure-vm-01.png +::: + +- **Size**: Select a VM size to support the workload that you want to run. The size that you choose then determines factors such as processing power, memory, and storage capacity. + +:::{figure} /_static/images/cloud-azure-vm-02.png +::: + +- **Password/SSH Key**: Choose whether the administrator account will use username/password or SSH keys for authentication. +- **Username**: The administrator username for the VM, e.g., `vyos`. +- **SSH Key**: You can use your existing SSH key pair or Azure automatically generates it for you and allows you to store it for future use. + +:::{figure} /_static/images/cloud-azure-vm-03.png +::: + +- **Virtual network**: Select `VyOS-VirtualNetwork`. +- **Subnet**: Select `VyOS-Public-Subnet`. +- **Public IP**: Select public IP address which created before `VyOS-Pub-IP`. + +:::{figure} /_static/images/cloud-azure-vm-04.png +::: + +- **Configure network security group**: Select existing Security Group `VyOS-SecurityGroup`. + +:::{figure} /_static/images/cloud-azure-vm-05.png +::: + +- Click **Review + Create**, then **Create**. +- Click **Download the private key and create resource** this will download private key to your computer and start creating Virtual Machine. + +:::{figure} /_static/images/cloud-azure-vm-06.png +::: + +- Wait until deployment is complete. After the deployment complete navigate to **Virtual Machines** click new created Virtual Machine. Check **Public IP address**. + +:::{figure} /_static/images/cloud-azure-vm-07.png +::: + +### Step 6: Access the VyOS instance + +- Access the VyOS instance using **SSH** protocol, **Public IP Address**, **Private Key**: + + ```none + $ ssh vyos@51.124.120.235 -i vyos_key.pem + vyos@VyOS:~$ + ``` + +### Step 7: Enable IP Forwarding in Network Interface + +This option allows the virtual machine on this network interface to act as a router and receive traffic addressed to other destinations. + +- On the **Virtual Machines** page, select `VyOS` VM, under **Networking** tab select **Network settings**, click network interface. + +:::{figure} /_static/images/cloud-azure-vm-12.png +::: + +- Enable IP forwarding and click the **Apply** button. + +:::{figure} /_static/images/cloud-azure-vm-13.png +::: + +### Step 8: Create and attach the second network interface (optional) + +Now instance has been deployed with one **eth0** `WAN` interface and want to add +new one. To add new interface an example **eth1** `LAN` you need shutdown the +instance. Attach the interface in the Azure portal and then start the instance. + +:::{note} +Azure does not allow you attach interface when the instance in the +**Running** state. +::: + +#### Create network interface: + +- In the Azure Portal, search for and select **Network Interfaces**. +- On the **Network Interfaces** page, select **+ Create**. + +:::{figure} /_static/images/cloud-azure-nic-01.png +::: + +- **Subscription**: Select your Subscription +- **Resource Group**: Select `VyOSResourceGroup` +- **Name**: `VyOS-PRIV-NIC` +- **Subnet**: `VyOS-Private-Subnet` +- **Private IP**: `Dynamic` +- Click **Review + Create**, then **Create** + +:::{figure} /_static/images/cloud-azure-nic-02.png +::: + +- Enable **IP Forwarding** +- Navigate to **Network Interfaces** select `VyOS-PRIV-NIC` + +:::{figure} /_static/images/cloud-azure-nic-03.png +::: + +- Go to **Settings**, select **IP configurations**. Enable IP Forwarding and select **Apply**. + +:::{figure} /_static/images/cloud-azure-nic-04.png +::: + +#### Attach reate network interface: + +- Navigate to **Virtual Machines**, click new created Virtual Machine and click the **Stop** button + +:::{figure} /_static/images/cloud-azure-vm-08.png +::: + +- Go to **Networking** select **Network settings** and then select **Attach network interface** + +:::{figure} /_static/images/cloud-azure-vm-09.png +::: + +- Select existing (before created) network interface `VyOS-PRIV-NIC` and click the **OK** button. + +:::{figure} /_static/images/cloud-azure-vm-10.png +::: + +- Now you have attached second interface to your instance and you can start Virtual Machine. +- Go to **Overview** and click the **Start** button. + +:::{figure} /_static/images/cloud-azure-vm-11.png +::: + +### Setp 8: Absorbing Routes + +To route traffic from your Virtual Network (VNET) through the LAN interface of your VyOS Network Virtual Appliance (NVA), you need to create and configure a custom route table in Azure. + +- Step-by-Step Instructions: +- Navigate to **Route Tables** and click **+ Create**. + +Provide the following details: + +> - **Subscription**: Select your Subscription +> - **Resource Group**: Select `VyOSResourceGroup` +> - **Name**: `Route-VyOS` +> - **Region**: e.g., `West Europe` + +:::{figure} /_static/images/cloud-azure-route-01.png +::: + +- Click **Review + Create**, then **Create**. + +**Add a Route**: + +- Navigate to **Route Tables** and click the new created route (`Route-VyOS`). +- Go to **Routes** and click **+ Add** button. + +:::{figure} /_static/images/cloud-azure-route-02.png +::: + +Add following parameters: + +- **Name**: `Default-Route` +- **Destination type**: `IP Addresses` +- **Destination IP addresses/CIDR ranges**: `0.0.0.0/0` +- **Next Hop Type**: `Virtual Appliance` +- **Next Hop IP Address**: `10.1.11.4` (The private Network Interface Card IP Address) + +:::{figure} /_static/images/cloud-azure-route-03.png +::: + +- Click the **Add** button. + +**Associate the Route Table with subnet**: + +- Navigate to **Route Tables** and click the new created route (`VyOSResourceGroup`). +- Go to **Subnets** and click **+ Associate** button. + +:::{figure} /_static/images/cloud-azure-route-04.png +::: + +- **Virtual network**: Select `VyOS-VirtualNetwork`. +- **Subnet**: Select `VyOS-Public-Subnet`. + +:::{figure} /_static/images/cloud-azure-route-05.png +::: + +:::{note} +If you want to create a new default route for VMs on the subnet, use **Address Prefix** `0.0.0.0/0` Also note that if you want to use this as a typical edge device, you'll want masquerade NAT for the `WAN` interface. +::: + +### Deploy VyOS Instance and Required Resources Automatically (via Terraform) + +You can deploy a VyOS instance and its associated resources in **Azure** using Terraform modules available in the GitHub repository. +All necessary parameters will be configured automatically, and you will receive **management and access information** from the outputs. + +You can also edit/change these parameters based on your requirements. + +- Download/Clone the Repository following GitHub repository: + +<https://github.com/vyos/vyos-automation/tree/main/Terraform/Azure> diff --git a/docs/installation/cloud/md-gcp.md b/docs/installation/cloud/md-gcp.md new file mode 100644 index 00000000..7144f083 --- /dev/null +++ b/docs/installation/cloud/md-gcp.md @@ -0,0 +1,260 @@ +# VyOS Deployment on Google Cloud Platform + +This guide provides step-by-step instructions for deploying a VyOS instance with two NICs and the required resources on Google Cloud Platform (GCP). + +## Prerequisites + +Before proceeding, ensure the following: + +- A GCP account with billing enabled. +- Permissions to deploy Marketplace images. +- Access to enable APIs and create resources (e.g., Compute Engine Admin, Network Admin). +- An SSH key pair for VyOS instance access. +- GA Google Cloud Project. + +## Deployment Steps + +### Step 1: Add SSH Key + +1. If you don’t already have SSH keys, generate an SSH key pair of type `ssh-rsa` on your local machine: + +> Example: +> +> ```none +> ssh-keygen -t rsa -f ~/.ssh/vyos_gcp -C "vyos@mypc" +> ``` + +:::{note} +In the comment `vyos@mypc`, the username must start with vyos. +This is because the default user in the VyOS image is `vyos`, and the Google Cloud API uses this value for SSH access. +::: + +2. Open GCP console and navigate to the **Compute Engine** > **Metadata** > **SSH Keys**. Choose + **SSH Keys**. + +:::{figure} /_static/images/cloud-gcp-01.png +::: + +3. Click **edit** and **Add item**. +4. Paste your public ssh key and **Save**. + +:::{figure} /_static/images/cloud-gcp-02.png +::: + +For more information, please visit the official Google Cloud documentation: + +<https://cloud.google.com/compute/docs/connect/add-ssh-keys> + +<https://cloud.google.com/compute/docs/connect/create-ssh-keys> + +### Step 2: Create a Service Account (If You Don't Have One) + +1. In the Google Cloud console **IAM & Admin > Service Accounts**. +2. Select select a project. + +:::{figure} /_static/images/cloud-gcp-proj.png +::: + +3. Click **Create Service Account**: + + - Name: e.g., `vyos-test` + - Service account ID: e.g., `vyos-test` + - Description: e.g., `VyOS Test Service Account` + +4. Click **Done**. + +:::{figure} /_static/images/cloud-gcp-svc.png +::: + +For more information, please visit the official Google Cloud documentation: + +<https://cloud.google.com/iam/docs/service-accounts-create> + +<https://cloud.google.com/iam/docs/service-account-overview> + +### Step 3: Create VPC Networks and Subnets + +1. In the Google Cloud console **VPC Network > VPC Networks** <https://console.cloud.google.com/networking/networks/list> +2. Select select a project. + +:::{figure} /_static/images/cloud-gcp-proj.png +::: + +3. Click **Create VPC Network**. + + **Public VPC**: + + - Name: e.g., `vyos-public-vpc` + - Subnet creation mode: `Custom` + - Subnet name: e.g., `vyos-public-subnet` + - Region: e.g., `europe-west1` + - IP range: e.g., `10.0.1.0/24` + - Leave all other settings at default, then click **Create**. + +:::{figure} /_static/images/cloud-gcp-vpc-01.png +::: + +:::{figure} /_static/images/cloud-gcp-vpc-02.png +**Private VPC**: + +- Name: `vyos-private-vpc` +- Subnet creation mode: `Custom` +- Subnet name: `vyos-private-subnet` +- Region: e.g., `europe-west1` +- IP range: `10.0.11.0/24` +- Leave all other settings at default, then click **Create**. +::: + +:::{figure} /_static/images/cloud-gcp-vpc-03.png +::: + +:::{figure} /_static/images/cloud-gcp-vpc-04.png +::: + +4. Add firewall rules to allow specific network traffic from the Internet if needed. By default, all incoming traffic from outside the network is blocked. Typically, a VyOS deployment from the GCP Marketplace configures this automatically, ensuring that SSH access is enabled after deployment. + +:::{figure} /_static/images/cloud-gcp-vpc-05.png +::: + +:::{figure} /_static/images/cloud-gcp-vpc-06.png +::: + +:::{figure} /_static/images/cloud-gcp-vpc-07.png +::: + +For more information, please visit the official Google Cloud documentation: + +<https://cloud.google.com/vpc/docs/create-modify-vpc-networks> + +### Step 4: Deploy VyOS instance from Marketplace + +1. Go to the Google Cloud Marketplace page in the Google Cloud console <https://console.cloud.google.com/marketplace> +2. Choose the project where you want to deploy the VyOS instance. + +:::{figure} /_static/images/cloud-gcp-proj.png +::: + +3. In the search bar, type `vyos` to find the VyOS image in the Marketplace. + +:::{figure} /_static/images/cloud-gcp-market-01.png +::: + +:::{figure} /_static/images/cloud-gcp-market-02.png +::: + +4. On the next page, review details such as support, pricing, and other details. + +:::{figure} /_static/images/cloud-gcp-market-03.png +::: + +5. Click the `GET STARTED` button to start deployment process. + +:::{figure} /_static/images/cloud-gcp-market-04.png +::: + +:::{figure} /_static/images/cloud-gcp-market-05.png +::: + +6. General settings. + + - Deployment name: e.g., `vyos-test-vm` + - Select a Service Account: Select the service account created earlier. + - Image: Select VyOS image for deployment. + - Zone: e.g., `europe-west1-b` + - Machine type: Choose based on performance and resource needs. + +:::{figure} /_static/images/cloud-gcp-vm-01.png +::: + +:::{figure} /_static/images/cloud-gcp-vm-02.png +::: + +7. Configure the network interfaces. + + **Public Network interface:** + + Edit the first (default) network interface and select following settings: + + > - Network: `vyos-public-vpc` + > - Subnetwork: `vyos-public-subnet` + > - External IP: `Ephemeral` + > - Private Network interface: + + **Private Network Interface:** + + Click **ADD A NETWORK INTERFACE** button to create a second (private) interface, and select following settings: + + > - Network: `vyos-private-vpc` + > - Subnetwork: `vyos-private-subnet` + > - External IP: `None` + +:::{figure} /_static/images/cloud-gcp-vm-03.png +::: + +8. Deployment automation. + + - You can use `cloud-init` `User Data` to automatically inject specific configuration commands into the VyOS instance during deployment. + - Example: + +> ```none +> #cloud-config +> vyos_config_commands: +> - set system host-name 'VyOS-for-GCP' +> - set system login banner pre-login 'Welcome to the VyOS for on GCP' +> - set interfaces ethernet eth0 description 'WAN' +> - set interfaces ethernet eth1 description 'LAN' +> - set interfaces ethernet eth1 address 'dhcp' +> - set interfaces ethernet eth1 dhcp-options no-default-route +> ``` + +For more information, please visit the documentation: + +<https://docs.vyos.io/en/stable/automation/cloud-init.html#module-vyos-userdata> + +:::{figure} /_static/images/cloud-gcp-vm-09.png +::: + +9. Click `Deploy` button. + +:::{figure} /_static/images/cloud-gcp-vm-06.png +::: + +:::{figure} /_static/images/cloud-gcp-vm-07.png +::: + +### Connect to the VyOS instance + +To connect to the VyOS instance, use the SSH key that was generated in the first step. + +To retrieve the public IP address, go to the **Google Cloud Console** and navigate to: **Compute Engine** > **VM instances** <https://console.cloud.google.com/compute/instances?project=vyos-images> + +:::{figure} /_static/images/cloud-gcp-vm-08.png +::: + +Example: + +> ```none +> ssh vyos@35.233.97.132 -i .ssh/vyos_gcp +> +> The authenticity of host '35.233.97.132 (35.233.97.132)' can't be established. +> ED25519 key fingerprint is SHA256:KCsCnwCGhwX2ba5RcPUAO3ZUSNzS4sXIkujFoScCd0g. +> This key is not known by any other names +> Are you sure you want to continue connecting (yes/no/[fingerprint])? yes +> Warning: Permanently added '35.233.97.132' (ED25519) to the list of known hosts. +> Welcome to the VyOS for on GCP +> Welcome to VyOS! +> +> ┌── ┐ +> . VyOS 1.4.2 +> └ ──┘ sagitta +> +> * Documentation: https://docs.vyos.io/en/sagitta +> * Project news: https://blog.vyos.io +> * Bug reports: https://vyos.dev +> +> You can change this banner using "set system login banner post-login" command. +> +> VyOS is a free software distribution that includes multiple components, +> you can check individual component licenses under /usr/share/doc/*/copyright +> vyos@VyOS-for-GCP:~$ +> ``` diff --git a/docs/installation/cloud/md-index.md b/docs/installation/cloud/md-index.md new file mode 100644 index 00000000..f64883fc --- /dev/null +++ b/docs/installation/cloud/md-index.md @@ -0,0 +1,14 @@ +# Running VyOS in Cloud Environments + +```{eval-rst} +.. toctree:: + :caption: Content + + aws + aws-ha + azure + azure-ha + aws-to-azure + gcp + oracle +``` diff --git a/docs/installation/cloud/md-oracel.md b/docs/installation/cloud/md-oracel.md new file mode 100644 index 00000000..9ed07ff9 --- /dev/null +++ b/docs/installation/cloud/md-oracel.md @@ -0,0 +1,5 @@ +# Oracle + +## References + +<https://www.oracle.com/cloud/> diff --git a/docs/installation/md-image.md b/docs/installation/md-image.md new file mode 100644 index 00000000..7581d065 --- /dev/null +++ b/docs/installation/md-image.md @@ -0,0 +1,122 @@ +(image-mgmt)= + +# Image Management + +The VyOS image-based installation is implemented by creating a directory for +each image on the storage device selected during the install process. + +The directory structure of the boot device: + +```none +/ +/boot +/boot/grub +/boot/1.2.0-rolling+201810021347 +``` + +The image directory contains the system kernel, a compressed image of the root +filesystem for the OS, and a directory for persistent storage, such as +configuration. On boot, the system will extract the OS image into memory and +mount the appropriate live-rw sub-directories to provide persistent storage +system configuration. + +This process allows for a system to always boot to a known working state, as +the OS image is fixed and non-persistent. It also allows for multiple releases +of VyOS to be installed on the same storage device. The image can be selected +manually at boot if needed, but the system will otherwise boot the image +configured to be the default. + +```{eval-rst} +.. opcmd:: show system image + + List all available system images which can be booted on the current system. + + .. code-block:: none + + vyos@vyos:~$ show system image + The system currently has the following image(s) installed: + + 1: 1.2.0-rolling+201810021347 (default boot) + 2: 1.2.0-rolling+201810021217 + 3: 1.2.0-rolling+201809252218 + +``` + +```{eval-rst} +.. opcmd:: delete system image [image-name] + + Delete no longer needed images from the system. You can specify an optional + image name to delete, the image name can be retrieved via a list of available + images can be shown using the {opcmd}`show system image`. + + .. code-block:: none + + vyos@vyos:~$ delete system image + The following image(s) can be deleted: + + 1: 1.3-rolling-201912181733 (default boot) (running image) + 2: 1.3-rolling-201912180242 + 3: 1.2.2 + 4: 1.2.1 + + Select the image to delete: 2 + + Are you sure you want to delete the + "1.3-rolling-201912180242" image? (Yes/No) [No]: y + Deleting the "1.3-rolling-201912180242" image... + Done +``` + +```{eval-rst} +.. opcmd:: show version + + Show current system image version. + + .. code-block:: none + + vyos@vyos:~$ show version + Version: VyOS 1.3-rolling-201912181733 + Built by: autobuild@vyos.net + Built on: Wed 18 Dec 2019 17:33 UTC + Build UUID: bccde2c3-261c-49cc-b421-9b257204e06c + Build Commit ID: f7ce0d8a692f2d + + Architecture: x86_64 + Boot via: installed image + System type: bare metal + + Hardware vendor: VMware, Inc. + Hardware model: VMware Virtual Platform + Hardware S/N: VMware-42 1d 83 b9 fe c1 bd b2-7d 3d 49 db 94 18 f5 c9 + Hardware UUID: b9831d42-c1fe-b2bd-7d3d-49db9418f5c9 + + Copyright: VyOS maintainers and contributors + + + + +``` + +## System rollback + +If you need to rollback to a previous image, you can easily do so. First +check the available images through the {opcmd}`show system image` +command and then select your image with the following command: + +```{eval-rst} +.. opcmd:: set system image default-boot [image-name] + + Select the default boot image which will be started on the next boot + of the system. +``` + +Then reboot the system. + +:::{note} +VyOS automatically associates the configuration to the image, +so you don't need to worry about that. Each image has a unique copy +of its configuration. +::: + +If you have access to the console, there is a another way to select +your booting image: reboot and use the GRUB menu at startup. diff --git a/docs/installation/md-index.md b/docs/installation/md-index.md new file mode 100644 index 00000000..f9e230fc --- /dev/null +++ b/docs/installation/md-index.md @@ -0,0 +1,28 @@ +# Installation and Image Management + +:::{note} +This is most likely only relevant for virtual installations: + +When installing VyOS ensure that the MAC address selected for your NICs is +not a locally administered MAC address. Locally administered addresses are +distinguished from universally administered addresses by setting (assigning +the value of 1 to) the second-least-significant bit of the first octet of +the address: + +Example: `02:00:00:00:00:01`, where the second-least-significant bit +(`02` in hex) is set to `1`. +::: + +```{eval-rst} +.. toctree:: + :maxdepth: 2 + :caption: Content + + install + virtual/index + cloud/index + vyos-on-baremetal + update + image + migrate-from-vyatta +``` diff --git a/docs/installation/md-install.md b/docs/installation/md-install.md new file mode 100644 index 00000000..a02b3292 --- /dev/null +++ b/docs/installation/md-install.md @@ -0,0 +1,396 @@ +(installation)= + +# Installation + +VyOS installation requires a downloaded VyOS .iso file. That file is +a live install image that lets you boot a live VyOS. From the live +system, you can proceed to a permanent installation on a hard drive or +any other type of storage. + +```{eval-rst} +.. table:: Comparison of VyOS image releases + + +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ + | Release Type | Description | Release Cycle | Intended Use | Access to Images | Access to Source | + +==============+===================================================+===================+=======================================+=======================+==================+ + | **Nightly | Automatically built from the current branch. | Every night | Developing VyOS, testing new | Everyone | Everyone | + | (Current)** | Always up to date with cutting edge development | | features, experimenting. | | | + | | but guaranteed to contain bugs. | | | | | + +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ + | **Stream** | VyOS Stream serves as a technology preview and | Every quarter | Non-critical production environments, | Everyone | Everyone | + | | a quality gate for the upcoming LTS release. | | preparing for the LTS release. | | | + | | Allows everyone to try new features and check | | | | | + | | if they work well or need improvements | | | | | + +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ + | **Release | Rather stable. All development focuses on testing | Irregularly until | Labs, small offices and non-critical | Everyone | Everyone | + | Candidate** | and hunting down remaining bugs following the | EPA comes out | production systems backed by a | | | + | | feature freeze. | | high-availability setup. | | | + +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ + | **Early | Highly stable with no known bugs. Needs to be | Irregularly until | Non-critical production environments, | Everyone | Everyone | + | Production | tested repeatedly under different conditions | LTS comes out | preparing for the LTS release. | | | + | Access** | before it can become the final release. | | | | | + +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ + | **Long-Term | Guaranteed to be stable and carefully maintained | Every major | Large-scale enterprise networks, | Subscribers, | Everyone | + | Support** | for several years after the release. No features | version | internet service providers, | contributors, | | + | | are introduced but security updates are released | | critical production environments | non-profits, | | + | | in a timely manner. | | that call for minimum downtime. | emergency services, | | + | | | | | academic institutions | | + +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ +``` + +## Hardware requirements + +The minimum system requirements are 4 GB RAM and 10 GB storage. +Depending on your use, you might need additional RAM and CPU resources e.g. +when having multiple BGP full tables in your system. + +## Download + +### Registered Subscribers + +Registered subscribers can log into <https://support.vyos.io/> to access a +variety of different downloads via the "Downloads" link. These downloads +include LTS (Long-Term Support), the associated hot-fix releases, early public +access releases, pre-built VM images, as well as device specific installation +ISOs. See this [article] for more information on downloads. + +:::{figure} /_static/images/vyosnew-downloads.png +::: + +### Rolling Release + +Everyone can download bleeding-edge VyOS rolling images from: +<https://downloads.vyos.io/> + +:::{note} +Rolling releases contain all the latest enhancements and fixes. This +means that there will be new bugs of course. If you think you hit a bug +please follow the guide at {ref}`bug_report`. We depend on your feedback +to improve VyOS! +::: + +The following link contains the list of the most recent VyOS builds for AMD64 +systems from the current branch: +<https://vyos.net/get/nightly-builds/> + +### Download Verification + +LTS images are signed by the VyOS lead package-maintainer private key. With the +official public key, the authenticity of the package can be verified. +Minisign is used for verification. + +(minisign-verification)= + +#### Minisign verification + +Currently we are using Minisign for release signing which is a simple tool to +sign files and verify signatures. + +In 2015, OpenBSD introduced signify. An alternative implementation of the same +protocol is minisign, which is also available for Windows and macOS, and in most +GNU/Linux distros it's in the repositories now. It is portable, lightweight, and +uses the highly secure Ed25519 public-key signature system. + +{vytask}`T2108` switched the validation system to prefer minisign over GPG keys. + +To verify a VyOS image starting off with VyOS 1.3.0-rc6 you can run: + +```none +$ minisign -V -P RWTR1ty93Oyontk6caB9WqmiQC4fgeyd/ejgRxCRGd2MQej7nqebHneP -m vyos-1.3.0-rc6-amd64.iso vyos-1.3.0-rc6-amd64.iso.minisig +Signature and comment signature verified +Trusted comment: timestamp:1629997936 file:vyos-1.3.0-rc6-amd64.iso +``` + +During an image upgrade VyOS performs the following command: + +```none +$ minisign -V -p /usr/share/vyos/keys/vyos-release.minisign.pub -m vyos-1.3.0-rc6-amd64.iso vyos-1.3.0-rc6-amd64.iso.minisig +Signature and comment signature verified +Trusted comment: timestamp:1629997936 file:vyos-1.3.0-rc6-amd64.iso +``` + +:::{note} +Starting with 1.4.3, VyOS uses Minisign exclusively. This should not +be a problem for anyone because Minisign signature verification has already +been present in all releases for years. But if you see an unexpected verification +error, you can solve that by updating your system to 1.4.2 first. +Removed support for GnuPG signatures({vytask}`T7301`). +::: + +(live_installation)= + +## Live installation + +:::{note} +A permanent VyOS installation always requires to go first +through a live installation. +::: + +VyOS, as other GNU+Linux distributions, can be tested without installing +it in your hard drive. **With your downloaded VyOS .iso file you can +create a bootable USB drive that will let you boot into a fully +functional VyOS system**. Once you have tested it, you can either decide +to begin a {ref}`permanent_installation` in your hard drive or power +your system off, remove the USB drive, and leave everything as it was. + +If you have a GNU+Linux system, you can create your VyOS bootable USB +stick with with the `dd` command: + +> 1. Open your terminal emulator. +> 2. Find out the device name of your USB drive (you can use the `lsblk` +> command) +> 3. Unmount the USB drive. Replace X in the example below with the +> letter of your device and keep the asterisk (wildcard) to unmount +> all partitions. +> +> ```none +> $ umount /dev/sdX* +> ``` +> +> 4. Write the image (your VyOS .iso file) to the USB drive. +> Note that here you want to use the device name (e.g. /dev/sdb), not +> the partition name (e.g. /dev/sdb1). +> +> > **Warning**: This will destroy all data on the USB drive! +> +> ```none +> # dd if=/path/to/vyos.iso of=/dev/sdX bs=8M; sync +> ``` +> +> 5. Wait until you get the outcome (bytes copied). Be patient, in some +> computers it might take more than one minute. +> 6. Once `dd` has finished, pull the USB drive out and plug it into +> the powered-off computer where you want to install (or test) VyOS. +> 7. Power the computer on, making sure it boots from the USB drive (you +> might need to select booting device or change booting settings). +> 8. Once VyOS is completely loaded, enter the default credentials +> (login: vyos, password: vyos). + +If you find difficulties with this method, prefer to use a GUI program, +or have a different operating system, there are other programs you can +use to create a bootable USB drive, like [balenaEtcher] (for GNU/Linux, +macOS and Windows), [Rufus] (for Windows) and [many others]. You can +follow their instructions to create a bootable USB drive from an .iso +file. + +:::{hint} +The default username and password for the live system is *vyos*. +::: + +(permanent_installation)= + +## Permanent installation + +:::{note} +Before a permanent installation, VyOS requires a +{ref}`live_installation`. +::: + +Unlike general purpose Linux distributions, VyOS uses "image installation" that +mimics the user experience of traditional hardware routers and allows keeping +multiple VyOS versions installed simultaneously. This makes it possible to +switch to a previous version if something breaks or miss-behaves after an image +upgrade. + +Every version is contained in its own squashfs image that is mounted in a union +filesystem together with a directory for mutable data such as configurations, +keys, or custom scripts. + +:::{note} +Older versions (prior to VyOS 1.1) used to support non-image +installation (`install system` command). Support for this has been removed +from VyOS 1.2 and newer releases. Older releases can still be upgraded via +the general `add system image <image_path>` upgrade command (consult +{ref}`image-mgmt` for further information). +::: + +In order to proceed with a permanent installation: + +> 1. Log into the VyOS live system (use the default credentials: vyos, +> vyos) +> 2. Run the `install image` command and follow the wizard: + +:::{figure} /_static/images/permanent_install.png +3. After the installation is completed, remove the live USB stick or + CD. +4. Reboot the system. + +```none +vyos@vyos:~$ reboot +Proceed with reboot? (Yes/No) [No] Yes +``` + +You will boot now into a permanent VyOS system. +::: + +## PXE Boot + +VyOS can also be installed through PXE. This is a more complex +installation method that allows deploying VyOS through the network. + +**Requirements** + +- Clients (where VyOS is to be installed) with a PXE-enabled NIC +- {ref}`dhcp-server` +- {ref}`tftp-server` +- Webserver (HTTP) - optional, but we will use it to speed up installation +- VyOS ISO image to be installed (do not use images prior to VyOS 1.2.3) +- Files *pxelinux.0* and *ldlinux.c32* [from the Syslinux distribution](https://kernel.org/pub/linux/utils/boot/syslinux/) + +### Configuration + +#### Step 1: DHCP + +Configure a DHCP server to provide the client with: + +- An IP address +- The TFTP server address (DHCP option 66). Sometimes referred as *boot server* +- The *bootfile name* (DHCP option 67), which is *pxelinux.0* + +In this example we configured an existent VyOS as the DHCP server: + +```none +vyos@vyos# show service dhcp-server + shared-network-name mydhcp { + subnet 192.168.1.0/24 { + bootfile-name pxelinux.0 + bootfile-server 192.168.1.50 + default-router 192.168.1.50 + range 0 { + start 192.168.1.70 + stop 192.168.1.100 + } + } + } +``` + +(install_from_tftp)= + +#### Step 2: TFTP + +Configure a TFTP server so that it serves the following: + +- The *pxelinux.0* file from the Syslinux distribution +- The *ldlinux.c32* file from the Syslinux distribution +- The kernel of the VyOS software you want to deploy. That is the + *vmlinuz* file inside the */live* directory of the extracted + contents from the ISO file. +- The initial ramdisk of the VyOS ISO you want to deploy. That is the + *initrd.img* file inside the */live* directory of the extracted + contents from the ISO file. Do not use an empty (0 bytes) initrd.img + file you might find, the correct file may have a longer name. +- A directory named pxelinux.cfg which must contain the configuration + file. We will use the [configuration] file shown below, which we named + [default]. + +In the example we configured our existent VyOS as the TFTP server too: + +```none +vyos@vyos# show service tftp-server + directory /config/tftpboot + listen-address 192.168.1.50 +``` + +Example of the contents of the TFTP server: + +```none +vyos@vyos# ls -hal /config/tftpboot/ +total 29M +drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 . +drwxrwsr-x 9 root vyattacfg 4.0K Oct 18 00:05 .. +-r--r--r-- 1 root vyattacfg 25M Oct 13 23:24 initrd.img-4.19.54-amd64-vyos +-rwxr-xr-x 1 root vyattacfg 120K Oct 13 23:44 ldlinux.c32 +-rw-r--r-- 1 root vyattacfg 46K Oct 13 23:24 pxelinux.0 +drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 pxelinux.cfg +-r--r--r-- 1 root vyattacfg 3.7M Oct 13 23:24 vmlinuz + +vyos@vyos# ls -hal /config/tftpboot/pxelinux.cfg +total 12K +drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 . +drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 .. +-rw-r--r-- 1 root root 191 Oct 14 01:10 default +``` + +Example of simple (no menu) configuration file: + +```none +vyos@vyos# cat /config/tftpboot/pxelinux.cfg/default +DEFAULT VyOS123 + +LABEL VyOS123 + KERNEL vmlinuz + APPEND initrd=initrd.img-4.19.54-amd64-vyos boot=live nopersistence noautologin nonetworking fetch=http://address:8000/filesystem.squashfs +``` + +#### Step 3: HTTP + +We also need to provide the *filesystem.squashfs* file. That is a heavy +file and TFTP is slow, so you could send it through HTTP to speed up the +transfer. That is how it is done in our example, you can find that in +the configuration file above. + +**First** run a web server - you can use a simple one like +[Python's SimpleHTTPServer] and start serving the `filesystem.squashfs` +file. The file can be found inside the `/live` directory of the +extracted contents of the ISO file. + +**Second**, edit the configuration file of the {ref}`install_from_tftp` +so that it shows the correct URL at +`fetch=http://<address_of_your_HTTP_server>/filesystem.squashfs`. + +:::{note} +Do not change the name of the *filesystem.squashfs* file. If +you are working with different versions, you can create different +directories instead. +::: + +And **third**, restart the TFTP service. If you are using VyOS as your +TFTP Server, you can restart the service with +`sudo service tftpd-hpa restart`. + +:::{note} +Make sure the available directories and files in both TFTP +and HTTP server have the right permissions to be accessed from the +booting clients. +::: + +### Client Boot + +Finally, turn on your PXE-enabled client or clients. They will +automatically get an IP address from the DHCP server and start booting +into VyOS live from the files automatically taken from the TFTP and HTTP +servers. + +Once finished you will be able to proceed with the `install image` +command as in a regular VyOS installation. + +## Known Issues + +This is a list of known issues that can arise during installation. + +### Black screen on install + +GRUB attempts to redirect all output to a serial port for ease of installation +on headless hosts. This appears to cause an hard lockup on some hardware that +lacks a serial port, with the result being a black screen after selecting the +`Live system` option from the installation image. + +The workaround is to type `e` when the boot menu appears and edit the GRUB boot +options. Specifically, remove the: + +`console=ttyS0,115200` + +option, and type CTRL-X to boot. + +Installation can then continue as outlined above. + + + +[article]: https://customers.support.vyos.com/servicedesk/customer/portal/1/article/159055913 +[balenaetcher]: https://www.balena.io/etcher/ +[configuration]: https://wiki.syslinux.org/wiki/index.php?title=Config +[default]: https://wiki.syslinux.org/wiki/index.php?title=PXELINUX#Configuration +[many others]: https://en.wikipedia.org/wiki/List_of_tools_to_create_Live_USB_systems +[python's simplehttpserver]: https://docs.python.org/2/library/simplehttpserver.html +[rufus]: https://rufus.ie/ +[syslinux]: http://www.syslinux.org/ diff --git a/docs/installation/md-update.md b/docs/installation/md-update.md new file mode 100644 index 00000000..e2c16ceb --- /dev/null +++ b/docs/installation/md-update.md @@ -0,0 +1,86 @@ +(update_vyos)= + +# Update VyOS + +New system images can be added using the {opcmd}`add system image` +command. The command will extract the chosen image and will prompt you +to use the current system configuration and SSH security keys, allowing +for the new image to boot using the current configuration. + +:::{note} +Only LTS releases are PGP-signed. +::: + +```{eval-rst} +.. opcmd:: add system image <url | path> [vrf name] + [username user [password pass]] + + Use this command to install a new system image. You can reach the + image from the web (``http://``, ``https://``) or from your local system, + e.g. /tmp/vyos-1.2.3-amd64.iso. + + The `add system image` command also supports installing new versions + of VyOS through an optional given VRF. Also if URL in question requires + authentication, you can specify an optional username and password via + the commandline which will be passed as "Basic-Auth" to the server. +``` + +If there is not enough **free disk space available**, the installation +will be canceled. To delete images use the {opcmd}`delete system image` +command. + +VyOS configuration is associated to each image, and **each image has a +unique copy of its configuration**. This is different than a traditional +network router where the configuration is shared across all images. + +:::{note} +If you have any personal files, like some scripts you created, +and you don't want them to be lost during the upgrade, make sure +those files are stored in `/config` as this directory is always copied +to newer installed images. +::: + +You can access files from a previous installation and copy them to your +current image if they were located in the `/config` directory. This +can be done using the {opcmd}`copy` command. So, for instance, in order +to copy `/config/config.boot` from VyOS 1.2.1 image, you would use the +following command: + +```{code} +copy file 1.2.1://config/config.boot to /tmp/config.boot.1.2.1 +``` + +## Example + +```none +vyos@vyos:~$ add system image https://s3.amazonaws.com/s3-us.vyos.io/rolling/current/vyos-1.4-rolling-202201120317-amd64.iso +Trying to fetch ISO file from https://s3.amazonaws.com/s3-us.vyos.io/rolling/current/vyos-1.4-rolling-202201120317-amd64.iso + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed +100 338M 100 338M 0 0 3837k 0 0:01:30 0:01:30 --:--:-- 3929k +ISO download succeeded. +Checking for digital signature file... + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0 +curl: (22) The requested URL returned error: 404 Not Found + +Unable to fetch digital signature file. +Do you want to continue without signature check? (yes/no) [yes] +Checking MD5 checksums of files on the ISO image...OK. +Done! + +What would you like to name this image? [vyos-1.3-rolling-201912201452]: + +OK. This image will be named: vyos-1.3-rolling-201912201452 +``` + +:::{hint} +The most up-do-date Rolling Release for AMD64 can be accessed using +the following URL: + +<https://vyos.net/get/nightly-builds/> +::: + +After reboot you might want to verify the version you are running with +the {opcmd}`show version` command. diff --git a/docs/installation/md-vyos-on-baremetal.md b/docs/installation/md-vyos-on-baremetal.md new file mode 100644 index 00000000..b551a811 --- /dev/null +++ b/docs/installation/md-vyos-on-baremetal.md @@ -0,0 +1,626 @@ +(vyosonbaremetal)= + +# Running on Bare Metal + +## Supermicro A2SDi (Atom C3000) + +I opted to get one of the new Intel Atom C3000 CPUs to spawn VyOS on it. +Running VyOS on an UEFI only device is supported as of VyOS release 1.2. + +### Supermicro Shopping Cart + +- 1x Supermicro CSE-505-203B (19" 1U chassis, inkl. 200W PSU) +- 1x Supermicro MCP-260-00085-0B (I/O Shield for A2SDi-2C-HLN4F) +- 1x Supermicro A2SDi-2C-HLN4F (Intel Atom C3338, 2C/2T, 4MB cache, Quad LAN + with Intel C3000 SoC 1GbE) +- 1x Crucial CT4G4DFS824A (4GB DDR4 RAM 2400 MT/s, PC4-19200) +- 1x SanDisk Ultra Fit 32GB (USB-A 3.0 SDCZ43-032G-G46 mass storage for OS) +- 1x Supermicro MCP-320-81302-0B (optional FAN tray) + +### Optional (10GE) + +If you want to get additional ethernet ports or even 10GE connectivity +the following optional parts will be required: + +- 1x Supermicro RSC-RR1U-E8 (Riser Card) +- 1x Supermicro MCP-120-00063-0N (Riser Card Bracket) + +Latest VyOS rolling releases boot without any problem on this board. You also +receive a nice IPMI interface realized with an ASPEED AST2400 BMC (no +information about [OpenBMC](https://www.openbmc.org/) so far on this +motherboard). + +### Pictures + +:::{figure} /_static/images/1u_vyos_back.jpg +:alt: CSE-505-203B Back +:scale: 25 % +::: + +:::{figure} /_static/images/1u_vyos_front.jpg +:alt: CSE-505-203B Front +:scale: 25 % +::: + +:::{figure} /_static/images/1u_vyos_front_open_1.jpg +:alt: CSE-505-203B Open 1 +:scale: 25 % +::: + +:::{figure} /_static/images/1u_vyos_front_open_2.jpg +:alt: CSE-505-203B Open 2 +:scale: 25 % +::: + +:::{figure} /_static/images/1u_vyos_front_open_3.jpg +:alt: CSE-505-203B Open 3 +:scale: 25 % +::: + +:::{figure} /_static/images/1u_vyos_front_10ge_open_1.jpg +:alt: CSE-505-203B w/ 10GE Open 1 +:scale: 25 % +::: + +:::{figure} /_static/images/1u_vyos_front_10ge_open_2.jpg +:alt: CSE-505-203B w/ 10GE Open 2 +:scale: 25 % +::: + +:::{figure} /_static/images/1u_vyos_front_10ge_open_3.jpg +:alt: CSE-505-203B w/ 10GE Open 3 +:scale: 25 % +::: + +:::{figure} /_static/images/1u_vyos_front_10ge_open_4.jpg +:alt: CSE-505-203B w/ 10GE Open +:scale: 25 % +::: + +(pc-engines-apu4)= + +## PC Engines APU4 + +As this platform seems to be quite common in terms of noise, cost, power and +performance it makes sense to write a small installation manual. + +This guide was developed using an APU4C4 board with the following specs: + +- AMD Embedded G series GX-412TC, 1 GHz quad Jaguar core with 64 bit and AES-NI + support, 32K data + 32K instruction cache per core, shared 2MB L2 cache. +- 4 GB DDR3-1333 DRAM, with optional ECC support +- About 6 to 10W of 12V DC power depending on CPU load +- 2 miniPCI express (one with SIM socket for 3G modem). +- 4 Gigabit Ethernet channels using Intel i211AT NICs + +The board can be powered via 12V from the front or via a 5V onboard connector. + +(vyos-on-baremetal-apu4-shopping)= + +### APU4 Shopping Cart + +- 1x apu4c4 = 4 i211AT LAN / AMD GX-412TC CPU / 4 GB DRAM / dual SIM +- 1x Kingston SUV500MS/120G +- 1x VARIA Group Item 326745 19" dual rack for APU4 + +The 19" enclosure can accommodate up to two APU4 boards - there is a single and +dual front cover. + +#### Extension Modules + +##### WiFi + +Refer to {ref}`wireless-interface` for additional information, below listed +modules have been tested successfully on this Hardware platform: + +- Compex WLE900VX mini-PCIe WiFi module, only supported in mPCIe slot 1. +- Intel Corporation AX200 mini-PCIe WiFi module, only supported in mPCIe slot 1. + (see {ref}`wireless-interface-intel-ax200`) + +##### WWAN + +Refer to {ref}`wwan-interface` for additional information, below listed modules +have been tested successfully on this Hardware platform using VyOS 1.3 +(equuleus): + +- Sierra Wireless AirPrime MC7304 miniPCIe card (LTE) +- Sierra Wireless AirPrime MC7430 miniPCIe card (LTE) +- Sierra Wireless AirPrime MC7455 miniPCIe card (LTE) +- Sierra Wireless AirPrime MC7710 miniPCIe card (LTE) +- Huawei ME909u-521 miniPCIe card (LTE) + +### VyOS 1.4 (sagitta) + +Depending on the VyOS versions you intend to install there is a difference in +the serial port settings ({vytask}`T1327`). + +Create a bootable USB pendrive using e.g. [Rufus] on a Windows machine. + +Connect serial port to a PC through null modem cable (RXD / TXD crossed over). +Set terminal emulator to 115200 8N1. + + +```none +PC Engines apu4 +coreboot build 20171130 +BIOS version v4.6.4 +4080 MB ECC DRAM +SeaBIOS (version rel-1.11.0.1-0-g90da88d) + +Press F10 key now for boot menu: + +Select boot device: + +1. ata0-0: KINGSTON SUV500MS120G ATA-11 Hard-Disk (111 GiBytes) +2. USB MSC Drive Generic Flash Disk 8.07 +3. Payload [memtest] +4. Payload [setup] +``` + + +Now boot from the `USB MSC Drive Generic Flash Disk 8.07` media by pressing +`2`, the VyOS boot menu will appear, just wait 10 seconds or press `Enter` +to continue. + +```none +lqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqk +x VyOS - Boot Menu x +tqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqu +x Live system (amd64-vyos) x +x Live system (amd64-vyos fail-safe mode) x +x Live system (amd64-vyos) - Serial console x +x x +mqqqqqqPress ENAutomatic boot in 10 seconds...nu entryqqqqqqqj +``` + +The image will be loaded and the last lines you will get will be: + +```none +Loading /live/vmlinuz... ok +Loading /live/initrd.img... +... +Welcome to VyOS - vyos ttyS0 + +vyos login: +``` + +You can now proceed with a regular image installation as described in +{ref}`installation`. + +(vyos-on-baremetal-apu4-pictures)= + +### Pictures + +:::{note} +Both device types operate without any moving parts and emit zero +noise. +::: + +#### Rack Mount + +:::{figure} /_static/images/apu4_rack_1.jpg +:alt: APU4 rack closed +:scale: 25 % +::: + +:::{figure} /_static/images/apu4_rack_2.jpg +:alt: APU4 rack front +:scale: 25 % +::: + +:::{figure} /_static/images/apu4_rack_3.jpg +:alt: 'APU4 rack module #1' +:scale: 25 % +::: + +:::{figure} /_static/images/apu4_rack_4.jpg +:alt: 'APU4 rack module #2' +:scale: 25 % +::: + +:::{figure} /_static/images/apu4_rack_5.jpg +:alt: 'APU4 rack module #3 with PSU' +:scale: 25 % +::: + +##### VyOS custom print + +:::{figure} /_static/images/apu4_rack_vyos_print.jpg +:alt: APU4 custom VyOS powder coat +:scale: 25 % +::: + +#### Desktop / Bench Top + +:::{figure} /_static/images/apu4_desk_1.jpg +:alt: APU4 desktop closed +:scale: 25 % +::: + +:::{figure} /_static/images/apu4_desk_2.jpg +:alt: APU4 desktop closed +:scale: 25 % +::: + +:::{figure} /_static/images/apu4_desk_3.jpg +:alt: APU4 desktop back +:scale: 25 % +::: + +:::{figure} /_static/images/apu4_desk_4.jpg +:alt: APU4 desktop back +:scale: 25 % +::: + +## Qotom Q355G4 + +The install on this Q355G4 box is pretty much plug and play. The port numbering +the OS does might differ from the labels on the outside, but the UEFI firmware +has a port blink test built in with MAC addresses so you can very quickly +identify which is which. MAC labels are on the inside as well, and this test +can be done from VyOS or plain Linux too. Default settings in the UEFI will +make it boot, but depending on your installation wishes (i.e. storage type, +boot type, console type) you might want to adjust them. This Qotom company +seems to be the real OEM/ODM for many other relabelling companies like +Protectli. + +### Hardware + +There are a number of other options, but they all seem to be close to Intel +reference designs, with added features like more serial ports, more network +interfaces and the likes. Because they don't deviate too much from standard +designs all the hardware is well-supported by mainline. It accepts one LPDDR3 +SO-DIMM, but chances are that if you need more than that, you'll also want +something even beefier than an i5. There are options for antenna holes, and SIM +slots, so you could in theory add an LTE/Cell modem (not tested so far). + +The chassis is a U-shaped alu extrusion with removable I/O plates and removable +bottom plate. Cooling is completely passive with a heatsink on the SoC with +internal and external fins, a flat interface surface, thermal pad on top of +that, which then directly attaches to the chassis, which has fins as well. It +comes with mounting hardware and rubber feet, so you could place it like a +desktop model or mount it on a VESA mount, or even wall mount it with the +provided mounting plate. The closing plate doubles as internal 2.5" mounting +place for an HDD or SSD, and comes supplied with a small SATA cable and SATA +power cable. + +Power supply is a 12VDC barrel jack, and included switching power supply, which +is why SATA power regulation is on-board. Internally it has a NUC-board-style +on-board 12V input header as well, the molex locking style. + +There are WDT options and auto-boot on power enable, which is great for remote +setups. Firmware is reasonably secure (no backdoors found, BootGuard is enabled +in enforcement mode, which is good but also means no coreboot option), yet has +most options available to configure (so it's not locked out like most firmwares +are). + +An external RS232 serial port is available, internally a GPIO header as well. +It does have Realtek based audio on board for some reason, but you can disable +that. Booting works on both USB2 and USB3 ports. Switching between serial BIOS +mode and HDMI BIOS mode depends on what is connected at startup; it goes into +serial mode if you disconnect HDMI and plug in serial, in all other cases it's +HDMI mode. + +## Partaker i5 + +:::{figure} ../_static/images/600px-Partaker-i5.jpg +::: + +I believe this is actually the same hardware as the Protectli. I purchased it +in June 2018. It came pre-loaded with pfSense. + +[Manufacturer product page](http://www.inctel.com.cn/product/detail/338.html). + +### Installation + +- Write VyOS ISO to USB drive of some sort +- Plug in VGA, power, USB keyboard, and USB drive +- Press "SW" button on the front (this is the power button; I don't know what + "SW" is supposed to mean). +- Begin rapidly pressing delete on the keyboard. The boot prompt is very quick, + but with a few tries you should be able to get into the BIOS. +- Chipset > South Bridge > USB Configuration: set XHCI to Disabled and USB 2.0 + (EHCI) to Enabled. Without doing this, the USB drive won't boot. +- Boot to the VyOS installer and install as usual. + +Warning the interface labels on my device are backwards; the left-most "LAN4" +port is eth0 and the right-most "LAN1" port is eth3. + +## Acrosser AND-J190N1 + +:::{figure} ../_static/images/480px-Acrosser_ANDJ190N1_Front.jpg +::: + +:::{figure} ../_static/images/480px-Acrosser_ANDJ190N1_Back.jpg +::: + +This microbox network appliance was build to create OpenVPN bridges. It can +saturate a 100Mbps link. It is a small (serial console only) PC with 6 Gb LAN + +You may have to add your own RAM and HDD/SSD. There is no VGA connector. But +Acrosser provides a DB25 adapter for the VGA header on the motherboard (not +used). + +### BIOS Settings: + +First thing you want to do is getting a more user friendly console to configure +BIOS. Default VT100 brings a lot of issues. Configure VT100+ instead. + +For practical issues change speed from 115200 to 9600. 9600 is the default +speed at which both linux kernel and VyOS will reconfigure the serial port +when loading. + +Connect to serial (115200bps). Power on the appliance and press Del in the +console when requested to enter BIOS settings. + +Advanced > Serial Port Console Redirection > Console Redirection Settings: + +- Terminal Type : VT100+ +- Bits per second : 9600 + +Save, reboot and change serial speed to 9600 on your client. + +Some options have to be changed for VyOS to boot correctly. With XHCI enabled +the installer can’t access the USB key. Enable EHCI instead. + +Reboot into BIOS, Chipset > South Bridge > USB Configuration: + +- Disable XHCI +- Enable USB 2.0 (EHCI) Support + +Perform Image installation using `install image` CLI command. + +(gowin-gw-fn-1ur1-10g)= + +## Gowin GW-FN-1UR1-10G + +A platform utilizing an Intel Alder Lake-N100 CPU with 6M cache, TDP 6W. +Onboard LPDDR5 16GB RAM and 128GB eMMC (can be used for image installation). + +The appliance comes with 2 * 2.5GbE Intel I226-V and 3 * 1GbE Intel I210 +where one supports IEEE802.3at PoE+ (Typical 30W). + +In addition there is a Mellanox ConnectX-3 2\* 10GbE SFP+ NIC available. + +**NOTE:** This is the entry level platform. Other derivates exists with +i3-N305 CPU and 2x 25GbE! + +### Gowin Shopping Cart + +- 1x Gowin GW-FN-1UR1-10G +- 2x 128GB M.2 NVMe SSDs + +### Optional (WiFi + WWAN) + +- 1x MediaTek 7921E M.2 NGFF WIFI module (not tested as this currently leads to + a Kernel crash) +- 1x HP LT4120 Snapdragon X5 LTE WWAN module + +### Pictures + +:::{figure} ../_static/images/gowin-01.png +::: + +:::{figure} ../_static/images/gowin-02.png +::: + +:::{figure} ../_static/images/gowin-03.png +::: + +:::{figure} ../_static/images/gowin-04.png +::: + +### Cooling + +The device itself is passivly cooled, whereas the power supply has an active fan. +Even if the main processor is powered off, the power supply fan is operating and +the entire chassis draws 7.5W. During operation the chassis drew arround 38W. + +### BIOS Settings + +No settings needed to be altered, everything worked out of the box! + +### Installation + +The system provides a regular RS232 console port using 115200,8n1 setting which +is sufficient to install VyOS from a USB pendrive. + +### First Boot + +Please note that there is a weirdness on the network interface mapping. +The interface \<-> MAC mapping is going upwards but the NICs are placed +somehow swapped on the mainboard/MACs programmed in a swapped order. + +See interface description for more detailed mapping. + +```none +vyos@vyos:~$ show interfaces +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address MAC VRF MTU S/L Description +----------- -------------- ----------------- ------- ----- ----- ------------- +eth0 - 00:f0:cb:00:00:99 default 1500 u/D Intel I226-V - Front eth2 +eth1 - 00:f0:cb:00:00:9a default 1500 u/D Intel I226-V - Front eth1 +eth2 - 00:f0:cb:00:00:9b default 1500 u/D Intel I210 - Front eth4 +eth3 - 00:f0:cb:00:00:9c default 1500 u/D Intel I210 - Front eth3 +eth4 - 00:f0:cb:00:00:9d default 1500 u/D Intel I210 - Front POE +eth5 - 00:02:c9:00:00:30 default 1500 u/D Mellanox ConnectX-3 - SFP2 +eth6 - 00:02:c9:00:00:31 default 1500 u/D Mellanox ConnectX-3 - SFP1 +lo 127.0.0.1/8 00:00:00:00:00:00 default 65536 u/u + ::1/128 +wwan0 - d2:39:76:8e:05:12 default 1500 A/D +``` + +#### VyOS 1.4 (sagitta) + +Connect serial port to a PC through a USB \<-> RJ45 console cable. Set terminal +emulator to 115200 8N1. You can also perform the installation using VGA or HDMI +ports. + +In this example I choose to install VyOS as RAID-1 on both NVMe drives. However, +a previous installation on the 128GB eMMC storage worked without any issues, +too. + +```none +Welcome to VyOS - vyos ttyS0 + +vyos login: +``` + +Perform Image installation using `install image` CLI command. This installation +uses two 128GB NVMe disks setup as RAID1. + +```none +Welcome to VyOS! + + ┌── ┐ + . VyOS 1.4.0 + └ ──┘ sagitta + +* Support portal: https://support.vyos.io +* Documentation: https://docs.vyos.io/en/sagitta +* Project news: https://blog.vyos.io +* Bug reports: https://vyos.dev + +You can change this banner using "set system login banner post-login" command. + +VyOS is a free software distribution that includes multiple components, +you can check individual component licenses under /usr/share/doc/*/copyright +Use of this pre-built image is governed by the EULA you can find in +/usr/share/vyos/EULA + +vyos@vyos:~$ install image + +Welcome to VyOS installation! +This command will install VyOS to your permanent storage. +Would you like to continue? [y/N] y + +What would you like to name this image? (Default: 1.4.0) + +Please enter a password for the "vyos" user: +Please confirm password for the "vyos" user: + +What console should be used by default? (K: KVM, S: Serial)? (Default: S) + +Probing disks +4 disk(s) found +Would you like to configure RAID-1 mirroring? [Y/n] y + +The following disks were found: + /dev/sda (14.4 GB) + /dev/mmcblk0 (116.5 GB) +Would you like to configure RAID-1 mirroring on them? [Y/n] n + +Would you like to choose two disks for RAID-1 mirroring? [Y/n] y +Disks available: + 1: /dev/sda (14.4 GB) + 2: /dev/mmcblk0 (116.5 GB) + 3: /dev/nvme1n1 (119.2 GB) + 4: /dev/nvme0n1 (119.2 GB) +Select first disk: 3 + +Remaining disks: + 1: /dev/sda (14.4 GB) + 2: /dev/mmcblk0 (116.5 GB) + 3: /dev/nvme0n1 (119.2 GB) +Select second disk: 3 + +Installation will delete all data on both drives. Continue? [y/N] y + +Searching for data from previous installations +No previous installation found +Creating partitions on /dev/nvme1n1 +Creating partition table... +Creating partitions on /dev/nvme0n1 +Creating partition table... +Creating RAID array +Updating initramfs +Creating filesystem on RAID array +The following config files are available for boot: + 1: /opt/vyatta/etc/config/config.boot + 2: /opt/vyatta/etc/config.boot.default + +Which file would you like as boot config? (Default: 1) +Creating temporary directories +Mounting new partitions +Creating a configuration file +Copying system image files +Installing GRUB configuration files +Installing GRUB to the drives +Cleaning up +Unmounting target filesystems +Removing temporary files +The image installed successfully; please reboot now. +``` + +### Hardware + +```none +vyos@vyos:~$ lspci +00:00.0 Host bridge: Intel Corporation Device 461c +00:02.0 VGA compatible controller: Intel Corporation Alder Lake-N [UHD Graphics] +00:0a.0 Signal processing controller: Intel Corporation Platform Monitoring Technology (rev 01) +00:0d.0 USB controller: Intel Corporation Device 464e +00:14.0 USB controller: Intel Corporation Device 54ed +00:14.2 RAM memory: Intel Corporation Device 54ef +00:15.0 Serial bus controller: Intel Corporation Device 54e8 +00:16.0 Communication controller: Intel Corporation Device 54e0 +00:1a.0 SD Host controller: Intel Corporation Device 54c4 +00:1c.0 PCI bridge: Intel Corporation Device 54b8 +00:1c.2 PCI bridge: Intel Corporation Device 54ba +00:1c.3 PCI bridge: Intel Corporation Device 54bb +00:1c.6 PCI bridge: Intel Corporation Device 54be +00:1d.0 PCI bridge: Intel Corporation Device 54b0 +00:1f.0 ISA bridge: Intel Corporation Device 5481 +00:1f.4 SMBus: Intel Corporation Device 54a3 +00:1f.5 Serial bus controller: Intel Corporation Device 54a4 +01:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +02:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +02:02.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +02:06.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +02:0e.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +03:00.0 Ethernet controller: Intel Corporation Ethernet Controller I226-V (rev 04) +04:00.0 Ethernet controller: Intel Corporation Ethernet Controller I226-V (rev 04) +05:00.0 Network controller: MEDIATEK Corp. MT7922 802.11ax PCI Express Wireless Network Adapter +06:00.0 SATA controller: ASMedia Technology Inc. Device 0622 (rev 01) +07:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +08:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +08:02.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +08:06.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +08:0e.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +09:00.0 Ethernet controller: Intel Corporation I210 Gigabit Network Connection (rev 03) +0a:00.0 Ethernet controller: Intel Corporation I210 Gigabit Network Connection (rev 03) +0b:00.0 Ethernet controller: Intel Corporation I210 Gigabit Network Connection (rev 03) +0d:00.0 Non-Volatile memory controller: Device 1ed0:2283 +0f:00.0 Non-Volatile memory controller: Device 1ed0:2283 +11:00.0 Ethernet controller: Mellanox Technologies MT27500 Family [ConnectX-3] +``` + +```none +vyos@vyos:~$ lsusb +Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub +Bus 003 Device 005: ID 0e8d:c616 MediaTek Inc. Wireless_Device +Bus 003 Device 003: ID 413c:2113 Dell Computer Corp. KB216 Wired Keyboard +Bus 003 Device 004: ID 03f0:9d1d HP, Inc HP lt4120 Snapdragon X5 LTE +Bus 003 Device 002: ID 05e3:0610 Genesys Logic, Inc. Hub +Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub +Bus 002 Device 002: ID 05e3:0620 Genesys Logic, Inc. GL3523 Hub +Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub +Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub +``` + +#### WWAN + +The LTE module can be enabled as simple as this config snippet: + +```none +interfaces { + wwan wwan0 { + address "dhcp" + apn "YOUR-APN-GOES-HERE" + } +} +``` + +For more information please refer to chapter: {ref}`wwan-interface` + +[rufus]: https://rufus.ie/ diff --git a/docs/installation/virtual/md-docker.md b/docs/installation/virtual/md-docker.md new file mode 100644 index 00000000..10da8d41 --- /dev/null +++ b/docs/installation/virtual/md-docker.md @@ -0,0 +1,67 @@ +(docker)= + +# Running in Docker Container + +Docker is an open-source project for deploying applications as standardized +units called containers. Deploying VyOS in a container provides a simple and +lightweight mechanism for both testing and packet routing for container +workloads. + +## IPv6 Support for docker + +VyOS requires an IPv6-enabled docker network. Currently linux distributions +do not enable docker IPv6 support by default. You can enable IPv6 support in +two ways. + +### Method 1: Create a docker network with IPv6 support + +Here is a example using the macvlan driver. + +```none +docker network create --ipv6 -d macvlan -o parent=eth0 --subnet 2001:db8::/64 --subnet 192.0.2.0/24 mynet +``` + +### Method 2: Add IPv6 support to the docker daemon + +Edit /etc/docker/daemon.json to set the `ipv6` key to `true` and to specify +the `fixed-cidr-v6` to your desired IPv6 subnet. + +```none +{ + "ipv6": true, + "fixed-cidr-v6": "2001:db8::/64" +} +``` + +Reload the docker configuration. + +```none +$ sudo systemctl reload docker +``` + +## Deploy container from ISO + +Download the ISO on which you want to base the container. In this example, +the name of the ISO is `vyos-1.4-rolling-202308240020-amd64.iso`. If you +created a custom IPv6-enabled network, the `docker run` command below +will require that this network be included as the `--net` parameter to +`docker run`. + +```none +$ mkdir vyos && cd vyos +$ curl -o vyos-1.4-rolling-202308240020-amd64.iso https://github.com/vyos/vyos-rolling-nightly-builds/releases/download/1.4-rolling-202308240020/vyos-1.4-rolling-202308240020-amd64.iso +$ mkdir rootfs +$ sudo mount -o loop vyos-1.4-rolling-202308240020-amd64.iso rootfs +$ sudo apt-get install -y squashfs-tools +$ mkdir unsquashfs +$ sudo unsquashfs -f -d unsquashfs/ rootfs/live/filesystem.squashfs +$ sudo tar -C unsquashfs -c . | docker import - vyos:1.4-rolling-202111281249 +$ sudo umount rootfs +$ cd .. +$ sudo rm -rf vyos +$ docker run -d --rm --name vyos --privileged -v /lib/modules:/lib/modules \ +> vyos:1.4-rolling-202111281249 /sbin/init +$ docker exec -ti vyos su - vyos +``` + +You can execute `docker stop vyos` when you are finished with the container. diff --git a/docs/installation/virtual/md-eve-ng.md b/docs/installation/virtual/md-eve-ng.md new file mode 100644 index 00000000..3e32e61f --- /dev/null +++ b/docs/installation/virtual/md-eve-ng.md @@ -0,0 +1,5 @@ +# EVE-NG + +## References + +<https://www.eve-ng.net/> diff --git a/docs/installation/virtual/md-gns3.md b/docs/installation/virtual/md-gns3.md new file mode 100644 index 00000000..d903c9a4 --- /dev/null +++ b/docs/installation/virtual/md-gns3.md @@ -0,0 +1,187 @@ +(vyos-on-gns3)= + +# Running on GNS3 + +Sometimes you may want to test VyOS in a lab environment. +[GNS3](http://www.gns3.com) is a network emulation software you +might use for it. + +This guide will provide the necessary steps for installing +and setting up VyOS on GNS3. + +## Requirements + +The following items are required: + +- A VyOS installation image (.iso file). You + can find how to get it on the {ref}`installation` page +- A working GNS3 installation. For further information see the + [GNS3 documentation](https://docs.gns3.com/). + +(vm-setup)= + +## VM setup + +First, a virtual machine (VM) for the VyOS installation must be created +in GNS3. + +Go to the GNS3 **File** menu, click **New template** and choose select +**Manually create a new Template**. + +:::{figure} /_static/images/gns3-01.png +::: + +Select **Quemu VMs** and then click on the `New` button. + +:::{figure} /_static/images/gns3-02.png +::: + +Write a name for your VM, for instance "VyOS", and click `Next`. + +:::{figure} /_static/images/gns3-03.png +::: + +Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM +and click `Next`. + +:::{figure} /_static/images/gns3-04.png +::: + +Select **telnet** as your console type and click `Next`. + +:::{figure} /_static/images/gns3-05.png +::: + +Select **New image** for the base disk image of your VM and click +`Create`. + +:::{figure} /_static/images/gns3-06.png +::: + +Use the defaults in the **Binary and format** window and click +`Next`. + +:::{figure} /_static/images/gns3-07.png +::: + +Use the defaults in the **Qcow2 options** window and click `Next`. + +:::{figure} /_static/images/gns3-08.png +::: + +Set the disk size to 2000 MiB, and click `Finish` to end the **Quemu +image creator**. + +:::{figure} /_static/images/gns3-09.png +::: + +Click `Finish` to end the **New QEMU VM template** wizard. + +:::{figure} /_static/images/gns3-10.png +::: + +Now the VM settings have to be edited. + +Being again at the **Preferences** window, having **Qemu VMs** +selected and having our new VM selected, click the `Edit` button. + +:::{figure} /_static/images/gns3-11.png +::: + +In the **General settings** tab of your **QEMU VM template +configuration**, do the following: + +- Click on the `Browse...` button to choose the **Symbol** you want to + have representing your VM. +- In **Category** select in which group you want to find your VM. +- Set the **Boot priority** to **CD/DVD-ROM**. + +:::{figure} /_static/images/gns3-12.png +::: + +At the **HDD** tab, change the Disk interface to **sata** to speed up +the boot process. + +:::{figure} /_static/images/gns3-13.png +::: + +At the **CD/DVD** tab click on `Browse...` and locate the VyOS image +you want to install. + +:::{figure} /_static/images/gns3-14.png +::: + +:::{note} +You probably will want to accept to copy the .iso file to your +default image directory when you are asked. +::: + +In the **Network** tab, set **0** as the number of adapters, set the +**Name format** to **eth\{0}** and the **Type** to **Paravirtualized +Network I/O (virtio-net-pci)**. + +:::{figure} /_static/images/gns3-15.png +::: + +In the **Advanced** tab, unmark the checkbox **Use as a linked base +VM** and click `OK`, which will save and close the **QEMU VM template +configuration** window. + +:::{figure} /_static/images/gns3-16.png +::: + +At the general **Preferences** window, click `OK` to save and close. + +:::{figure} /_static/images/gns3-17.png +::: + +(vyos-installation)= + +## VyOS installation + +- Create a new project. +- Drag the newly created VyOS VM into it. +- Start the VM. +- Open a console. + The console should show the system booting. It will ask for the login + credentials, you are at the VyOS live system. +- {ref}`Install VyOS <installation>` + as normal (that is, using the `install image` command). +- After a successful installation, shutdown the VM with the `poweroff` + command. +- **Delete the VM** from the GNS3 project. + +The *VyOS-hda.qcow2* file now contains a working VyOS image and can be +used as a template. But it still needs some fixes before we can deploy +VyOS in our labs. + +(vyos-vm-configuration)= + +## VyOS VM configuration + +To turn the template into a working VyOS machine, further steps are +necessary as outlined below: + +**General settings** tab: Set the boot priority to **HDD** + +:::{figure} /_static/images/gns3-20.png +::: + +**CD/DVD** tab: Unmount the installation image file by clearing the +**Image** entry field. + +:::{figure} /_static/images/gns3-21.png +::: + +Set the number of required network adapters, for example **4**. + +:::{figure} /_static/images/gns3-215.png +::: + +**Advanced** settings tab: Mark the checkbox **Use as a linked +base VM** and click `OK` to save the changes. + +:::{figure} /_static/images/gns3-22.png +::: + +The VyOS VM is now ready to be deployed. diff --git a/docs/installation/virtual/md-index.md b/docs/installation/virtual/md-index.md new file mode 100644 index 00000000..12ac179e --- /dev/null +++ b/docs/installation/virtual/md-index.md @@ -0,0 +1,13 @@ +# Running VyOS in Virtual Environments + +```{eval-rst} +.. toctree:: + :caption: Content + + libvirt + proxmox + vmware + gns3 + eve-ng + docker +``` diff --git a/docs/installation/virtual/md-libvirt.md b/docs/installation/virtual/md-libvirt.md new file mode 100644 index 00000000..5acefd43 --- /dev/null +++ b/docs/installation/virtual/md-libvirt.md @@ -0,0 +1,171 @@ +(libvirt)= + +# Running on Libvirt Qemu/KVM + +Libvirt is an open-source API, daemon and management tool for managing platform +virtualization. There are several ways to deploy VyOS on libvirt kvm. +Use Virt-manager and native CLI. In an example we will be use use 4 gigabytes +of memory, 2 cores CPU and default network virbr0. + +## CLI + +### Deploy from ISO + +Create VM name `vyos_r1`. You must specify the path to the `ISO` image, +the disk `qcow2` will be created automatically. The `default` network is +the virtual network (type Virtio) created by the hypervisor with NAT. + +```none +$ virt-install -n vyos_r1 \ + --ram 4096 \ + --vcpus 2 \ + --cdrom /var/lib/libvirt/images/vyos.iso \ + --os-type linux \ + --os-variant debian10 \ + --network network=default \ + --graphics vnc \ + --hvm \ + --virt-type kvm \ + --disk path=/var/lib/libvirt/images/vyos_r1.qcow2,bus=virtio,size=8 \ + --noautoconsole +``` + +Connect to VM with command `virsh console vyos_r1` + +```none +$ virsh console vyos_r1 + +Connected to domain vyos_r1 +Escape character is ^] + +vyos login: vyos +Password: + +vyos@vyos:~$ install image +``` + +After installation - exit from the console using the key combination +`Ctrl + ]` and reboot the system. + +### Deploy from qcow2 + +The convenience of using {abbr}`KVM (Kernel-based Virtual Machine)` +images is that they don't need to be installed. +Download predefined VyOS.qcow2 image for `KVM` + +```none +curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 +``` + +Create VM with `import` qcow2 disk option. + +```none +$ virt-install -n vyos_r2 \ + --ram 4096 \ + --vcpus 2 \ + --os-type linux \ + --os-variant debian10 \ + --network network=default \ + --graphics vnc \ + --hvm \ + --virt-type kvm \ + --disk path=/var/lib/libvirt/images/vyos_kvm.qcow2,bus=virtio \ + --import \ + --noautoconsole +``` + +Connect to VM with command `virsh console vyos_r2` + +```none +$ virsh console vyos_r2 + +Connected to domain vyos_r2 +Escape character is ^] + +vyos login: vyos +Password: + +vyos@vyos:~$ +``` + +The system is fully operational. + +## Virt-manager + +The virt-manager application is a desktop user interface for managing virtual +machines through libvirt. On the linux open +{abbr}`VMM (Virtual Machine Manager)`. + +(libvirt-virt-manager-iso)= + +### Deploy from ISO + +1. Open {abbr}`VMM (Virtual Machine Manager)` and Create a new + {abbr}`VM (Virtual Machine)` +2. Choose `Local install media` (ISO) + +:::{figure} /_static/images/virt-libvirt-01.png +::: + +3. Choose path to iso vyos.iso. Operating System can be any Debian based. + +:::{figure} /_static/images/virt-libvirt-02.png +::: + +4. Choose Memory and CPU + +:::{figure} /_static/images/virt-libvirt-03.png +::: + +5. Disk size + +:::{figure} /_static/images/virt-libvirt-04.png +::: + +6. Name of VM and network selection + +:::{figure} /_static/images/virt-libvirt-05.png +::: + +7. Then you will be taken to the console. + +:::{figure} /_static/images/virt-libvirt-06.png +::: + +(libvirt-virt-manager-qcow2)= + +### Deploy from qcow2 + +Download predefined VyOS.qcow2 image for `KVM` + +```none +curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 +``` + +1. Open {abbr}`VMM (Virtual Machine Manager)` and Create a new + {abbr}`VM (Virtual Machine)` +2. Choose `Import existing disk` image + +:::{figure} /_static/images/virt-libvirt-qc-01.png +::: + +3. Choose the path to the image `vyos_kvm.qcow2` that was previously + downloaded . Operation System can be any Debian based. + +:::{figure} /_static/images/virt-libvirt-qc-02.png +::: + +4. Choose Memory and CPU + +:::{figure} /_static/images/virt-libvirt-03.png +::: + +5. Name of VM and network selection + +:::{figure} /_static/images/virt-libvirt-05.png +::: + +6. Then you will be taken to the console. + +:::{figure} /_static/images/virt-libvirt-qc-03.png +::: diff --git a/docs/installation/virtual/md-proxmox.md b/docs/installation/virtual/md-proxmox.md new file mode 100644 index 00000000..cad22137 --- /dev/null +++ b/docs/installation/virtual/md-proxmox.md @@ -0,0 +1,45 @@ +(proxmox)= + +# Running on Proxmox + +Proxmox is an open-source platform for virtualization. Please visit +<https://vyos.io> to see how to get a qcow2 image that can be imported +into Proxmox. + +## Deploy VyOS from CLI with qcow2 image + +1. Copy the qcow2 image to a temporary directory on the Proxmox server. +2. The commands below assume that virtual machine ID 200 is unused and that the user wants the disk stored in a storage pool called `local-lvm`. + +```none +$ qm create 200 --name vyos2 --memory 2048 --net0 virtio,bridge=vmbr0 +$ qm importdisk 200 /path/to/image/vyos-1.2.8-proxmox-2G.qcow2 local-lvm +$ qm set 200 --virtio0 local-lvm:vm-200-disk-0 +$ qm set 200 --boot order=virtio0 +``` + +3. Optionally, the user can attach a CDROM with an ISO as a cloud-init data source. The below command assumes the ISO has been uploaded to the `local` storage pool with the name `seed.iso`. + +```none +$ qm set 200 --ide2 media=cdrom,file=local:iso/seed.iso +``` + +4. Start the virtual machine in the proxmox GUI or CLI using `qm start 200`. + +## Deploy VyOS from CLI with rolling release ISO + +1. Download the rolling release iso from <https://vyos.net/get/nightly-builds/>. Non-subscribers can always get the LTS release by building it from source. Instructions can be found in the {ref}`build` section of this manual. VyOS source code repository is available <https://github.com/vyos/vyos-build>. +2. Prepare VM for installation from ISO media. The commands below assume that your iso is available in a storage pool 'local', that you want it to have a VM ID '200' and want to create a new disk on storage pool 'local-lvm' of size 15GB. + +```none +qm create 200 --name vyos --memory 2048 --net0 virtio,bridge=vmbr0 --ide2 media=cdrom,file=local:iso/live-image-amd64.hybrid.iso --virtio0 local-lvm:15 +``` + +3. Start the VM using the command `qm start 200` or using the start button located in the proxmox GUI. +4. Using the proxmox webGUI, open the virtual console for your newly created vm. Login username/password is `vyos/vyos`. +5. Once booted into the live system, type `install image` into the command line and follow the prompts to install VyOS to the virtual drive. +6. After installation has completed, remove the installation iso using the GUI or `qm set 200 --ide2 none`. +7. Reboot the virtual machine using the GUI or `qm reboot 200`. + +Visit <https://www.proxmox.com/en/> for more information about the download +and installation of this hypervisor. diff --git a/docs/installation/virtual/md-vmware.md b/docs/installation/virtual/md-vmware.md new file mode 100644 index 00000000..0338067c --- /dev/null +++ b/docs/installation/virtual/md-vmware.md @@ -0,0 +1,39 @@ +(vyosonvmware)= + +# Running on VMware ESXi + +## ESXi 5.5 or later + +.ova files are available for supporting users, and a VyOS can also be stood up +using a generic Linux instance, and attaching the bootable ISO file and +installing from the ISO using the normal process around `install image`. + +:::{NOTE} +There have been previous documented issues with GRE/IPSEC tunneling +using the E1000 adapter on the VyOS guest, and use of the VMXNET3 has been +advised. +::: + +### Memory Contention Considerations + +When the underlying ESXi host is approaching ~92% memory utilisation it will +start the balloon process in a 'soft' state to start reclaiming memory from +guest operating systems. This causes an artificial pressure using the vmmemctl +driver on memory usage on the virtual guest. As VyOS by default does not have +a swap file, this vmmemctl pressure is unable to force processes to move in +memory data to the paging file, and blindly consumes memory forcing the +virtual guest into a low memory state with no way to escape. The balloon +can expand to 65% of guest allocated memory, so a VyOS guest running >35% of +memory usage, can encounter an out of memory situation, and trigger the kernel +oom_kill process. At this point a weighted lottery favouring memory hungry +processes will be run with the unlucky winner being terminated by the kernel. + +It is advised that VyOS routers are configured in a resource group with +adequate memory reservations so that ballooning is not inflicted on +virtual VyOS guests. + +### References + + +<https://muralidba.blogspot.com/2018/03/how-does-linux-out-of-memory-oom-killer.html> + diff --git a/docs/introducing/md-about.md b/docs/introducing/md-about.md new file mode 100644 index 00000000..16eac6e5 --- /dev/null +++ b/docs/introducing/md-about.md @@ -0,0 +1,25 @@ +(about)= + +# About + +VyOS is an open source network operating system based on Debian GNU/Linux. + +VyOS provides a free routing platform that competes directly with other +commercially available solutions from well known network providers. Because +VyOS runs on standard amd64, i586 and ARM systems, it is able to be used +as a router and firewall platform for cloud deployments. + +We use multiple live versions of our manual, hosted thankfully by +<https://readthedocs.org>. We will provide one version of the manual for every +VyOS major version starting with VyOS 1.2 which will receive Long-term support +(LTS). + +The manual version is selected/specified by it's Git branch name. You can +switch between versions of the documentation by selecting the appropriate +branch on the bottom left corner. + +VyOS CLI syntax may change between major (and sometimes minor) versions. Please +always refer to the documentation matching your current, running installation. +If a change in the CLI is required, VyOS will ship a so called migration script +which will take care of adjusting the syntax. No action needs to be taken by +you. diff --git a/docs/introducing/md-history.md b/docs/introducing/md-history.md new file mode 100644 index 00000000..b400455f --- /dev/null +++ b/docs/introducing/md-history.md @@ -0,0 +1,124 @@ +(history)= + +# History + +## In the beginning... + +There once was a network operating system based on Debian GNU/Linux, +called Vyatta. [^footnote-1] 2006 onwards, it was a great free software +alternative to Cisco IOS and Jupiter JUNOS. It came in two editions: +Vyatta Core (previously Vyatta Community Edition) that was completely +free software, and Vyatta Subscription Edition that had proprietary +features and was only available to paying customers. [^footnote-2] + +Vyatta was acquired by Brocade Communication Systems in 2012. Shortly +after, Brocade renamed Vyatta Subscription Edition to Brocade vRouter, +discontinued Vyatta Core and shut down the community forum without a +notice. The bug tracker and Git repositories followed next year. + +It's worth noting that by the time Brocade acquired Vyatta, +development of Vyatta Core was already stagnated. Vyatta Subscription +Edition (and thus, Vyatta development as a whole) had been replacing +core components with proprietary software, meaning few features made +it to Vyatta Core, and those that did were bug-ridden and hamstrung. + +In 2013, soon after Vyatta Core was abandoned, the community forked +the last Vyatta Core version (6.6R1) and VyOS Project came into being. +[Sentrium SL](https://blog.vyos.io/sentrium-what-sentrium) was +established by VyOS maintainers in 2014 to fund VyOS development by +selling support, consulting services and prebuilt long-term support +images. + +Brocade was acquired by Broadcom in 2016 and sold what remains of +erstwhile Vyatta to AT&T in 2017, who in turn sold it to Ciena in 2021. + +## Major releases + +VyOS major versions used to be named after elements in order of atomic +numbers. With 1.2, this naming scheme was replaced with the much +cooler scheme of Latin names of [IAU](https://en.wikipedia.org/wiki/IAU_designated_constellations_by_area) +designated constellations by solid angle area, starting from the smallest. + +### Hydrogen (1.0) + +Released just in time for holidays on 22 December 2013, Hydrogen was +the first major VyOS release. It fixed features that were broken in +Vyatta Core 6.6 (such as IPv4 BGP peer groups and DHCPv6 relay) and +introduced command scripting, a task scheduler and web proxy LDAP +authentication. + +### Helium (1.1) + +Helium was released on 9 October 2014, exactly on the day VyOS Project +first came into being in the previous year. Helium came with a lot of +new features, including an event handler and support for L2TPv3, +802.1ad QinQ and IGMP proxy, as well as experimental support for VXLAN +and DMVPN (the latter of which was also broken in Vyatta Core due to +its reliance on a proprietary NHRP implementation). + +### Crux (1.2) + +Crux (the Southern Cross) came out on 28 January 2019 and was the +first major release of VyOS as we know it today. The underlying +Debian base was upgraded from Squeeze (6) to Jessie (8). + +Although Crux came with too many new features to mention here, some +noteworthy ones are: an mDNS repeater, a broadcast relay, +a high-performance PPPoE server, an HFSC scheduler, as well as support +for Wireguard, unicast VRRP, RPKI for BGP and fully 802.1ad-compliant +QinQ ethertype. The telnet server and support for P2P filtering were +removed. + +Crux is the first version to feature the modular image build system. +CLI definitions began to be written in the modern, verifiable XML +templates. Python APIs were introduced for command scripting and +configuration migration. Introduction of new Perl and shell code was +proscribed and the rewriting of legacy Perl code in pure Python began +with Crux. + +As of 2022, Crux is still supported and maintained. + +### Equuleus (1.3) + +The current long-term support version of VyOS, Equuleus (the Pony) +came out on 21 December 2021, once again in time for the winter +holidays. + +Equuleus brought many long-desired features with it, most notably +an SSTP VPN server, an IPoE server, an OpenConnect VPN server and +a serial console server, in addition to reworked support for WWAN +interfaces, support for GENEVE and MACSec interfaces, VRF, IS-IS +routing, preliminary support for MPLS and LDP, and many other +initialisms. + +As of 2022, Equuleus is in the stable. + +### Sagitta (1.4) + +Sagitta (the Arrow) is the codename of the current development +branch, so there's no VyOS 1.4 yet. + +### Circinus (1.5) + +Circinus (the Compass) is the codename of the upcoming development +branch, so there's no VyOS 1.5 yet. + +## A note on copyright + +Unlike Vyatta, VyOS never had (nor will ever have) proprietary code. +The only proprietary material in VyOS is non-code assets, such as +graphics and the trademark "VyOS". [^footnote-3] This means you can build your +own long-term support images (as the entire toolchain we use is free +software) and even distribute them, given you rename it and remove +such assets before building. Although note that we do not provide +support for images distributed by a third-party. See the +[artwork license](https://github.com/vyos/vyos-build/blob/current/LICENSE.artwork) +and the end-user license agreement at `/usr/share/vyos/EULA` in +any pre-built image for more precise information. + +[^footnote-1]: From the Sanskrit adjective "Vyātta" (व्यात्त), meaning opened. + +[^footnote-2]: A business model comparable to that of Redis, rather than that + of VyOS today. + +[^footnote-3]: This is not unlike how Linus Torvalds owns the trademark "Linux". diff --git a/docs/md-404.md b/docs/md-404.md new file mode 100644 index 00000000..f5530747 --- /dev/null +++ b/docs/md-404.md @@ -0,0 +1,13 @@ +--- +orphan: true +--- + +# Page Not Found + +Sorry, we could not find a page. +Try using the search box or go to the release homepage: + +- [1.2.x (crux)](https://docs.vyos.io/en/crux/) +- [1.3.x (equuleus)](https://docs.vyos.io/en/equuleus/) +- [1.4.x (sagitta)](https://docs.vyos.io/en/sagitta/) +- [rolling release (circinus)](https://docs.vyos.io/en/latest/) diff --git a/docs/md-coverage.md b/docs/md-coverage.md new file mode 100644 index 00000000..73bd9396 --- /dev/null +++ b/docs/md-coverage.md @@ -0,0 +1,55 @@ +# Coverage + +Overview over all commands, which are documented in the +`.. cfgcmd::` or `.. opcmd::` Directives. + +The build process take all xml definition files +from [vyos-1x](https://github.com/vyos/vyos-1x) and a periodical export of +all VyOS commands and extract each leaf command or executable command. +After this the commands are compare and shown in +the following two tables. The script compare only the fixed part of a command. +All varables or values will be erase and then compare: + +for example there are these two commands: + +> - documentation: `interfaces ethernet <interface> address +> <address | dhcp | dhcpv6>` +> - xml: `interfaces ethernet <ethernet> address <address>` +> - VyOS: `interfaces ethernet <text> address <value>` + +Now the script earse all in between `<` and `>` and simply compare +the strings. + +**There are 3 kind of problems:** + +`Not documented yet` + +> - A XML command are not found in `.. cfgcmd::` or `.. opcmd::` Commands +> - The command should be documented + +`Nothing found in XML Definitions` + +> - `.. cfgcmd::` or `.. opcmd::` Command are not found in a XML command +> - Maybe the command where changed in the XML Definition, the feature is +> not anymore in VyOS, or there is a typo + +`Nothing found in VyOS` + +> - `.. cfgcmd::` or `.. opcmd::` Command are not found in a VyOS command +> - Maybe the command where changed, the feature is +> not anymore in VyOS, or there is a typo + +## Configuration Commands + +```{eval-rst} +.. cfgcmdlist:: + :show-coverage: + +``` + +## Operational Commands + +```{eval-rst} +.. opcmdlist:: + :show-coverage: +``` diff --git a/docs/md-documentation.md b/docs/md-documentation.md new file mode 100644 index 00000000..9493f807 --- /dev/null +++ b/docs/md-documentation.md @@ -0,0 +1,430 @@ +--- +lastproofread: '2021-06-25' +--- + +(documentation)= + +# Write Documentation + +We encourage every VyOS user to help us improve our documentation as we have +a deficit like most software projects. This not only helps you when reading +but also everyone else. + +If you are willing to contribute to our documentation this is the definite +guide how to do so. + +:::{note} +In contrast to submitting code patches, there is no requirement that +you open up a [Phabricator] task prior to submitting a Pull-Request to the +documentation. +::: + +VyOS documentation is written in reStructuredText and generated to Read the Docs +pages with Sphinx, as per the Python tradition, as well as PDF files for offline +use through LaTeX. We welcome all sorts of contributions to the documentation. +Not just new additions but also corrections to existing documentation. + +The documentation source is kept in the Git repository at +<https://github.com/vyos/vyos-documentation> and you can follow the instructions +in the [README.md] to build and test your changes. + +You can either install Sphinx (and TeX Live for PDF output) and build the +documentation locally, or use the [Dockerfile] to build it in a container. + +## Guidelines + +There are a few things to keep in mind when contributing to the +documentation, for the sake of consistency and readability. + +Take a look at the {doc}`/documentation` page for an intricate explanation +of the documentation process. + +The following is a quick summary of the rules: + +- Use American English at all times. It's always a good idea to run + your text through a grammar and spell checker, such as [Grammarly]. +- Don't forget to update `index.rst` when adding a new node. +- Try not to exceed 80 characters per line, but don't break URLs over this. +- Properly quote commands, filenames and brief code snippets with double backticks. +- Use literal blocks for longer snippets. +- Leave a newline before and after a header. +- Indent with two spaces. +- When in doubt, follow the style of existing documentation. + +And finally, remember that the reStructuredText files aren't +exclusively for generating HTML and PDF. They should be human-readable +and easily perused from a console. + +## Forking Workflow + +The Forking Workflow is fundamentally different from other popular Git +workflows. Instead of using a single server-side repository to act as the +"central" codebase, it gives every developer their own server-side repository. +This means that each contributor has not one, but two Git repositories: a +private local one and a public server-side one. + +The main advantage of the Forking Workflow is that contributions can be +integrated without the need for everybody to push to a single central +repository. Developers push to their own server-side repositories, and only the +project maintainer can push to the official repository. This allows the +maintainer to accept commits from any developer without giving them write +access to the official codebase. + +:::{note} +Updates to our documentation should be delivered by a GitHub +pull-request. This requires you already have a GitHub account. +::: + +- Fork this project on GitHub <https://github.com/vyos/vyos-documentation/fork> + +- Clone fork to local machine, then change to that directory + `$ cd vyos-documentation` + +- Install the requirements `$ pip install -r requirements.txt` + (or something similar) + +- Create a new branch for your work, use a descriptive name of your work: + `$ git checkout -b <branch-name>` + +- Make all your changes - please keep our commit rules in mind + ({ref}`prepare_commit`). This mainly applies to proper commit messages + describing your change (how and why). Please check out the documentation of + [Sphinx-doc] or [reStructuredText] if you are not familiar with it. This is used + for writing our docs. Additional directives how to write in RST can be + obtained from [reStructuredTextDirectives]. + +- Check your changes by locally building the documentation `$ make livehtml`. + Sphinx will build the html files in the `docs/_build` folder. We provide + you with a Docker container for an easy-to-use user experience. Check the + [README.md] file of this repository. + +- View modified files by calling `$ git status`. You will get an overview of + all files modified by you. You can add individual files to the Git Index in + the next step. + +- Add modified files to Git index `$ git add path/to/filename` or add all + unstaged files `$ git add .`. All files added to the Git index will be part + of you following Git commit. + +- Commit your changes with the message, `$ git commit -m "<commit message>"` + or use `$ git commit -v` to have your configured editor launched. You can + type in a commit message. Again please make yourself comfortable without + rules ({ref}`prepare_commit`). + +- Push commits to your GitHub project: `$ git push -u origin <branch-name>` + +- Submit pull-request. In GitHub visit the main repository and you should + see a banner suggesting to make a pull request. Fill out the form and + describe what you do. + +- Once pull requests have been approved, you may want to locally update + your forked repository too. First you'll have to add a second remote + called `upstream` which points to our main repository. `$ git remote add + upstream https://github.com/vyos/vyos-documentation.git` + + Check your configured remote repositories: + + ```none + $ git remote -v + origin https://github.com/<username>/vyos-documentation.git (fetch) + origin https://github.com/<username>/vyos.documentation.git (push) + upstream https://github.com/vyos/vyos-documentation.git (fetch) + upstream https://github.com/vyos/vyos-documentation.git (push) + ``` + + Your remote repo on Github is called `origin`, while the original repo you + have forked is called `upstream`. Now you can locally update your forked + repo. + + ```none + $ git fetch upstream + $ git checkout master + $ git merge upstream/master + ``` + +- If you also want to update your fork on GitHub, use the following: `$ git + push origin master` + +## Style Guide + +### Formatting and Sphinxmarkup + +#### TOC Level + +We use the following syntax for Headlines. + +```none +##### +Title +##### + +******** +Chapters +******** + +Sections +======== + +Subsections +----------- + +Subsubsections +^^^^^^^^^^^^^^ + +Paragraphs +"""""""""" +``` + +#### Cross-References + +A plugin will be used to generate a reference label for each headline. +To reference a page or a section in the documentation use the +`{ref}` command. + +For example, you want to reference the headline **VLAN** in the +**ethernet.rst** page. The plugin generates the label based on +the headline and the file path. + +`` {ref}`configuration/interfaces/ethernet:vlan `` + +to use an alternative hyperlink use it this way: + +`` {ref}`Check out VLAN<configuration/interfaces/ethernet:vlan> `` + +##### handle build errors + +The plugin will warn on build if a headline has a duplicate name in the +same document. To prevent this warning, you have to put a custom link on +top of the headline. + +```none +Section A +========== + +Lorem ipsum dolor sit amet, consetetur sadipscing elitr + +Example +------- + +Lorem ipsum dolor sit amet, consetetur sadipscing elitr + +Section B +========== + +Lorem ipsum dolor sit amet, consetetur sadipscing elitr + +.. _section B example: + +Example +------- + +Lorem ipsum dolor sit amet, consetetur sadipscing elitr +``` + +#### Address space + +Note the following RFCs ({rfc}`5737`, {rfc}`3849`, {rfc}`5389` and +{rfc}`7042`), which describe the reserved public IP addresses and autonomous +system numbers for the documentation: + +> - `192.0.2.0/24` +> - `198.51.100.0/24` +> - `203.0.113.0/24` +> - `2001:db8::/32` +> - 16bit ASN: `64496 - 64511` +> - 32bit ASN: `65536 - 65551` +> - Unicast MAC Addresses: `00-53-00` to `00-53-FF` +> - Multicast MAC-Addresses: `90-10-00` to `90-10-FF` + +Please do not use other public address space. + +#### Line length + +Limit all lines to a maximum of 80 characters. + +Except in `.. code-block::` because it uses the html tag `<pre>` and +renders the same line format from the source rst file. + +#### Autolinter + +Each GitHub pull request is automatically linted to check the address space and +line length. + +Sometimes it is necessary to provide real IP addresses like in the +{ref}`examples`. For this, please use the sphinx comment syntax +`.. stop_vyoslinter` to stop the linter and `.. start_vyoslinter` to start. + +#### Custom Sphinx-doc Markup + +Custom commands have been developed for writing the documentation. Please +make yourself comfortable with those commands as this eases the way we +render the documentation. + +##### cfgcmd + +When documenting CLI commands, use the `.. cfgcmd::` directive +for all configuration mode commands. An explanation of the described command +should be added below this statement. +Replace all variable contents with \<value> or something similar. + +With those custom commands, it will be possible to render them in a more +descriptive way in the resulting HTML/PDF manual. + +```none +.. cfgcmd:: protocols static arp <ipaddress> hwaddr <macaddress> + + This will configure a static ARP entry, always resolving `192.0.2.100` to + `00:53:27:de:23:aa`. +``` + +For an inline configuration level command, use `{cfgcmd}` + +```none +{cfgcmd}`set interface ethernet eth0` +``` + +To extract a defaultvalue from the XML definitions add a `:defaultvalue:` +to `.. cfgcmd::` directive. +To have this feature locally, the vyos-1x submodule must be initialized before. +Please be aware to not update the submodule in your PR. + +```none +.. cfgcmd:: set system conntrack table-size <1-50000000> + :defaultvalue: + + The connection tracking table contains one entry for each connection being + tracked by the system. +``` + +##### opcmd + +When documenting operational level commands, use the `.. opcmd::` directive. +An explanation of the described command should be added below this statement. + +With those custom commands, it is possible to render them in a more +descriptive way in the resulting HTML/PDF manual. + +```none +.. opcmd:: show protocols static arp + + Display all known ARP table entries spanning across all interfaces +``` + +For an inline operational level command, use `{opcmd}` + +```none +{opcmd}`add system image` +``` + +##### cmdinclude + +To minimize redundancy, there is a special include directive. It includes a txt +file and replace the `{{ var0 }}` - `{{ var9 }}` with the correct value. + +```none +.. cmdincludemd:: /_include/interface-address.txt + :var0: ethernet + :var1: eth1 +``` + +the content of interface-address.txt looks like this + +```none +.. cfgcmd:: set interfaces {{ var0 }} <interface> address <address | dhcp | + dhcpv6> + + Configure interface `<interface>` with one or more interface + addresses. + + * **address** can be specified multiple times as IPv4 and/or IPv6 + address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64 + * **dhcp** interface address is received by DHCP from a DHCP server + on this segment. + * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 + server on this segment. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} address 192.0.2.1/24 + set interfaces {{ var0 }} {{ var1 }} address 192.0.2.2/24 + set interfaces {{ var0 }} {{ var1 }} address 2001:db8::ffff/64 + set interfaces {{ var0 }} {{ var1 }} address 2001:db8:100::ffff/64 +``` + +##### vytask + +When referencing to VyOS Phabricator Tasks, there is a custom Sphinx Markup +command called `vytask` that automatically renders to a proper Phabricator +URL. This is heavily used in the {ref}`release-notes` section. + +```none +* {vytask}`T1605` Fixed regression in L2TP/IPsec server +* {vytask}`T1613` Netflow/sFlow captures IPv6 traffic correctly +``` + +### Page content + +The documentation has 3 different types of pages. The same kind of pages must +have the same structure to achieve a recognition factor. + +All RST files must follow the same TOC Level syntax and have to start with + +``` +##### +Title +##### +``` + +#### Configuration mode pages + +The configuration mode folder and the articles cover the specific level of +the commands. The exact level depends on the command. This should provide +stability for URLs used in the forum or blogpost. + +For example: + +> - `set firewall zone` is written in `firewall/zone.rst` +> - `set interfaces ethernet` is written in `interfaces/ethernet.rst` + +The article starts with a short introduction about the command or the +technology. Please include some helpful links or background information. + +An optional section follows. Some commands have requirements like compatible +hardware (e.g. Wifi) or some commands you have to set before. For +example, it is recommended to set a route-map before configuring BGP. + +In the configuration part of the page, all possible configuration options +should be documented. Use `.. cfgcmd::` described above. + +Related operation command must be documented in the next part of the article. +Use `::opcmd..` for these commands. + +If there some troubleshooting guides related to the commands. Explain it in the +next optional part. + +#### Operation mode pages + +Operation mode commands that do not fit in a related configuration mode command +must be documented in this part of the documentation. + +General concepts for troubleshooting and detailed process descriptions belong +here. + +#### Anything else + +Anything else that is not a configuration or an operation command has no +predefined structure. + + +```{include} /_include/common-references.txt +``` + + +[dockerfile]: https://github.com/vyos/vyos-documentation/blob/master/docker/Dockerfile +[grammarly]: https://www.grammarly.com/ +[readme.md]: https://github.com/vyos/vyos-documentation/blob/master/README.md +[restructuredtext]: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html +[restructuredtextdirectives]: https://docutils.sourceforge.io/docs/ref/rst/directives.html +[sphinx-doc]: https://www.sphinx-doc.org diff --git a/docs/md-index.md b/docs/md-index.md new file mode 100644 index 00000000..499a4926 --- /dev/null +++ b/docs/md-index.md @@ -0,0 +1,113 @@ +(index)= + +# VyOS User Guide + +```{eval-rst} +.. grid:: 3 + :gutter: 2 + + .. grid-item-card:: Get / Build VyOS + + + Quickly {ref}`Build<contributing/build-vyos:build vyos>` your own Image or take a look at how to {ref}`download<installation/install:download>` a free or supported version. + + + .. grid-item-card:: Install VyOS + + Read about how to install VyOS on {ref}`Bare Metal<installation/install:installation>` or in a + {ref}`Virtual Environment<installation/virtual/index:running vyos in virtual environments>` and + how to use an image with the usual {ref}`cloud<installation/cloud/index:running VyOS in Cloud Environments>` providers + + + .. grid-item-card:: Configuration and Operation + + Use the {ref}`Quickstart Guide<quick-start:Quick Start>`, to have a fast overview. Or go deeper and + set up {ref}`advanced routing<configuration/protocols/index:protocols>`, + {ref}`VRFs<configuration/vrf/index:vrf>`, or + {ref}`VPNs<configuration/vpn/index:vpn>` for example. + + + .. grid-item-card:: Automate + + Integrate VyOS in your automation Workflow with + {ref}`Ansible<vyos-ansible>`, + have your own {ref}`local scripts<command-scripting>`, or configure VyOS with the {ref}`HTTPS-API<vyosapi>`. + + + .. grid-item-card:: Examples + + Get some inspiration from the {ref}`Configuration Blueprints<configexamples/index:Configuration Blueprints>` + to build your infrastructure. + + + .. grid-item-card:: Contribute and Community + + | There are many ways to contribute to the project. + | Add missing parts or improve the {ref}`Documentation<documentation:Write Documentation>`. + | Discuss in `Slack <https://slack.vyos.io/>`_ or the `Forum <https://forum.vyos.io>`_. + | Or you can pick up a `Task <https://vyos.dev/>`_ and fix the {ref}`code<contributing/development:development>`. + +``` + +```{eval-rst} +.. toctree:: + :hidden: + :maxdepth: 1 + + introducing/about + introducing/history + changelog/index + +``` + +```{eval-rst} +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: First Steps + + installation/index + quick-start + cli +``` + +```{eval-rst} +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: Adminguide + + + configuration/index + operation/index + automation/index + troubleshooting/index + configexamples/index + +``` + +```{eval-rst} +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: Development + + contributing/build-vyos + contributing/development + contributing/issues-features + contributing/upstream-packages + contributing/debugging + contributing/testing + +``` + +```{eval-rst} +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: Misc + + documentation + coverage + copyright +``` diff --git a/docs/md-quick-start.md b/docs/md-quick-start.md new file mode 100644 index 00000000..39bdbb11 --- /dev/null +++ b/docs/md-quick-start.md @@ -0,0 +1,368 @@ +(quick-start)= + +# Quick Start + +This chapter will guide you on how to get up to speed quickly using your new +VyOS system. It will show you a very basic configuration example that will +provide a {ref}`nat` gateway for a device with two network interfaces +(`eth0` and `eth1`). + +(quick-start-configuration-mode)= + +## Configuration Mode + +By default, VyOS is in operational mode, and the command prompt displays +a `$`. To configure VyOS, you will need to enter configuration mode, resulting +in the command prompt displaying a `#`, as demonstrated below: + +```none +vyos@vyos$ configure +vyos@vyos# +``` + +## Commit and Save + +After every configuration change, you need to apply the changes by using the +following command: + +```none +commit +``` + +Once your configuration works as expected, you can save it permanently by using +the following command: + +```none +save +``` + +## Interface Configuration + +- Your outside/WAN interface will be `eth0`. It will receive its interface + address via DHCP. +- Your internal/LAN interface will be `eth1`. It will use a static IP address + of `192.168.0.1/24`. + +After switching to {ref}`quick-start-configuration-mode` issue the following +commands: + +```none +set interfaces ethernet eth0 address dhcp +set interfaces ethernet eth0 description 'OUTSIDE' +set interfaces ethernet eth1 address '192.168.0.1/24' +set interfaces ethernet eth1 description 'LAN' +``` + +## SSH Management + +After switching to {ref}`quick-start-configuration-mode` issue the following +commands, and your system will listen on every interface for incoming SSH +connections. You might want to check the {ref}`ssh` chapter on how to listen +on specific addresses only. + +```none +set service ssh port '22' +``` + +(dhcp-dns-quick-start)= + +## DHCP/DNS quick-start + +The following settings will configure DHCP and DNS services on +your internal/LAN network, where VyOS will act as the default gateway and +DNS server. + +- The default gateway and DNS recursor address will be `192.168.0.1/24` +- The address range `192.168.0.2/24 - 192.168.0.8/24` will be reserved for + static assignments +- DHCP clients will be assigned IP addresses within the range of + `192.168.0.9 - 192.168.0.254` and have a domain name of `internal-network` +- DHCP leases will hold for one day (86400 seconds) +- VyOS will serve as a full DNS recursor, replacing the need to utilize Google, + Cloudflare, or other public DNS servers (which is good for privacy) +- Only hosts from your internal/LAN network can use the DNS recursor + +```none +set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 default-router '192.168.0.1' +set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 name-server '192.168.0.1' +set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 domain-name 'vyos.net' +set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 lease '86400' +set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 range 0 start '192.168.0.9' +set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 range 0 stop '192.168.0.254' + +set service dns forwarding cache-size '0' +set service dns forwarding listen-address '192.168.0.1' +set service dns forwarding allow-from '192.168.0.0/24' +``` + +## NAT + +The following settings will configure {ref}`source-nat` rules for our +internal/LAN network, allowing hosts to communicate through the outside/WAN +network via IP masquerade. + +```none +set nat source rule 100 outbound-interface name 'eth0' +set nat source rule 100 source address '192.168.0.0/24' +set nat source rule 100 translation address masquerade +``` + +## Firewall + +A new firewall structure—which uses the `nftables` backend, rather +than `iptables`—is available on all installations starting from +VyOS `1.4-rolling-202308040557`. The firewall supports creation of distinct, +interlinked chains for each [Netfilter hook](https://wiki.nftables.org/wiki-nftables/index.php/Netfilter_hooks) +and allows for more granular control over the packet filtering process. + +The firewall begins with the base `filter` tables you define for each of the +`forward`, `input`, and `output` Netfiter hooks. Each of these tables is +populated with rules that are processed in order and can jump to other chains +for more granular filtering. + +### Configure Firewall Groups + +To make firewall configuration easier, we can create groups of interfaces, +networks, addresses, ports, and domains that describe different parts of +our network. We can then use them for filtering within our firewall rulesets, +allowing for more concise and readable configuration. + +In this case, we will create two interface groups — a `WAN` group for our +interfaces connected to the public internet and a `LAN` group for the +interfaces connected to our internal network. Additionally, we will create a +network group, `NET-INSIDE-v4`, that contains our internal subnet. + +```none +set firewall group interface-group WAN interface eth0 +set firewall group interface-group LAN interface eth1 +set firewall group network-group NET-INSIDE-v4 network '192.168.0.0/24' +``` + +### Configure Stateful Packet Filtering + +With the new firewall structure, we have have a lot of flexibility in how we +group and order our rules, as shown by the three alternative approaches below. + +#### Option 1: Global State Policies + +Using options defined in `set firewall global-options state-policy`, state +policy rules that applies for both IPv4 and IPv6 are created. These global +state policies also applies for all traffic that passes through the router +(transit) and for traffic originated/destinated to/from the router itself, and +will be evaluated before any other rule defined in the firewall. + +Most installations would choose this option, and will contain: + +```none +set firewall global-options state-policy established action accept +set firewall global-options state-policy related action accept +set firewall global-options state-policy invalid action drop +``` + +#### Option 2: Common/Custom Chain + +We can create a common chain for stateful connection filtering of multiple +interfaces (or multiple netfilter hooks on one interface). Those individual +chains can then jump to the common chain for stateful connection filtering, +returning to the original chain for further rule processing if no action is +taken on the packet. + +The chain we will create is called `CONN_FILTER` and has three rules: + +- A default action of `return`, which returns the packet back to the original + chain if no action is taken. +- A rule to `accept` packets from established and related connections. +- A rule to `drop` packets from invalid connections. + +```none +set firewall ipv4 name CONN_FILTER default-action 'return' + +set firewall ipv4 name CONN_FILTER rule 10 action 'accept' +set firewall ipv4 name CONN_FILTER rule 10 state established +set firewall ipv4 name CONN_FILTER rule 10 state related + +set firewall ipv4 name CONN_FILTER rule 20 action 'drop' +set firewall ipv4 name CONN_FILTER rule 20 state invalid +``` + +Then, we can jump to the common chain from both the `forward` and `input` +hooks as the first filtering rule in the respective chains: + +```none +set firewall ipv4 forward filter rule 10 action 'jump' +set firewall ipv4 forward filter rule 10 jump-target CONN_FILTER + +set firewall ipv4 input filter rule 10 action 'jump' +set firewall ipv4 input filter rule 10 jump-target CONN_FILTER +``` + +#### Option 3: Per-Hook Chain + +Alternatively, you can take the more traditional stateful connection +filtering approach by creating rules on each base hook's chain: + +```none +set firewall ipv4 forward filter rule 5 action 'accept' +set firewall ipv4 forward filter rule 5 state established +set firewall ipv4 forward filter rule 5 state related +set firewall ipv4 forward filter rule 10 action 'drop' +set firewall ipv4 forward filter rule 10 state invalid + +set firewall ipv4 input filter rule 5 action 'accept' +set firewall ipv4 input filter rule 5 state established +set firewall ipv4 input filter rule 5 state related +set firewall ipv4 input filter rule 10 action 'drop' +set firewall ipv4 input filter rule 10 state invalid +``` + +### Block Incoming Traffic + +Now that we have configured stateful connection filtering to allow traffic from +established and related connections, we can block all other incoming traffic +addressed to our local network. + +Create a new chain (`OUTSIDE-IN`) which will drop all traffic that is not +explicitly allowed at some point in the chain. Then, we can jump to that chain +from the `forward` hook when traffic is coming from the `WAN` interface +group and is addressed to our local network. + +```none +set firewall ipv4 name OUTSIDE-IN default-action 'drop' + +set firewall ipv4 forward filter rule 100 action jump +set firewall ipv4 forward filter rule 100 jump-target OUTSIDE-IN +set firewall ipv4 forward filter rule 100 inbound-interface group WAN +set firewall ipv4 forward filter rule 100 destination group network-group NET-INSIDE-v4 +``` + +We should also block all traffic destinated to the router itself that isn't +explicitly allowed at some point in the chain for the `input` hook. As +we've already configured stateful packet filtering above, we only need to +set the default action to `drop`: + +```none +set firewall ipv4 input filter default-action 'drop' +``` + +### Allow Management Access + +We can now configure access to the router itself, allowing SSH +access from the inside/LAN network and rate limiting SSH access from the +outside/WAN network. + +First, create a new dedicated chain (`VyOS_MANAGEMENT`) for management +access, which returns to the parent chain if no action is taken. Add a rule +to accept traffic from the `LAN` interface group: + +```none +set firewall ipv4 name VyOS_MANAGEMENT default-action 'return' +``` + +Configure a rule on the `input` hook filter to jump to the `VyOS_MANAGEMENT` +chain when new connections are addressed to port 22 (SSH) on the router itself: + +```none +set firewall ipv4 input filter rule 20 action jump +set firewall ipv4 input filter rule 20 jump-target VyOS_MANAGEMENT +set firewall ipv4 input filter rule 20 destination port 22 +set firewall ipv4 input filter rule 20 protocol tcp +``` + +Finally, configure the `VyOS_MANAGEMENT` chain to accept connection from the +`LAN` interface group while limiting requests coming from the `WAN` +interface group to 4 per minute: + +```none +set firewall ipv4 name VyOS_MANAGEMENT rule 15 action 'accept' +set firewall ipv4 name VyOS_MANAGEMENT rule 15 inbound-interface group 'LAN' + +set firewall ipv4 name VyOS_MANAGEMENT rule 20 action 'drop' +set firewall ipv4 name VyOS_MANAGEMENT rule 20 recent count 4 +set firewall ipv4 name VyOS_MANAGEMENT rule 20 recent time minute +set firewall ipv4 name VyOS_MANAGEMENT rule 20 state new +set firewall ipv4 name VyOS_MANAGEMENT rule 20 inbound-interface group 'WAN' + +set firewall ipv4 name VyOS_MANAGEMENT rule 21 action 'accept' +set firewall ipv4 name VyOS_MANAGEMENT rule 21 state new +set firewall ipv4 name VyOS_MANAGEMENT rule 21 inbound-interface group 'WAN' +``` + +### Allow Access to Services + +Here we're allowing the router to respond to pings. Then, we can allow access to +the DNS recursor we configured earlier, accepting traffic bound for port 53 from +all hosts on the `NET-INSIDE-v4` network: + +```none +set firewall ipv4 input filter rule 30 action 'accept' +set firewall ipv4 input filter rule 30 icmp type-name 'echo-request' +set firewall ipv4 input filter rule 30 protocol 'icmp' +set firewall ipv4 input filter rule 30 state new + +set firewall ipv4 input filter rule 40 action 'accept' +set firewall ipv4 input filter rule 40 destination port '53' +set firewall ipv4 input filter rule 40 protocol 'tcp_udp' +set firewall ipv4 input filter rule 40 source group network-group NET-INSIDE-v4 +``` + +Finally, we can now configure access to the services running on this router, +allowing all connections coming from localhost: + +```none +set firewall ipv4 input filter rule 50 action 'accept' +set firewall ipv4 input filter rule 50 source address 127.0.0.0/8 +``` + +Commit changes, save the configuration, and exit configuration mode: + +```none +vyos@vyos# commit +vyos@vyos# save +Saving configuration to '/config/config.boot'... +Done +vyos@vyos# exit +vyos@vyos$ +``` + +## Hardening + +Especially if you are allowing SSH remote access from the outside/WAN +interface, there are a few additional configuration steps that should be taken. + +Replace the default `vyos` system user: + +```none +set system login user myvyosuser authentication plaintext-password mysecurepassword +``` + +Set up {ref}`ssh_key_based_authentication`: + +```none +set system login user myvyosuser authentication public-keys myusername@mydesktop type ssh-rsa +set system login user myvyosuser authentication public-keys myusername@mydesktop key contents_of_id_rsa.pub +``` + +Finally, try and SSH into the VyOS install as your new user. Once you have +confirmed that your new user can access your router without a password, delete +the original `vyos` user and completely disable password authentication for +{ref}`ssh`: + +```none +delete system login user vyos +set service ssh disable-password-authentication +``` + +As above, commit your changes, save the configuration, and exit +configuration mode: + +```none +vyos@vyos# commit +vyos@vyos# save +Saving configuration to '/config/config.boot'... +Done +vyos@vyos# exit +vyos@vyos$ +``` + +You now should have a simple yet secure and functioning router to experiment +with further. Enjoy! diff --git a/docs/operation/md-boot-options.md b/docs/operation/md-boot-options.md new file mode 100644 index 00000000..ea077c8a --- /dev/null +++ b/docs/operation/md-boot-options.md @@ -0,0 +1,53 @@ +(boot-options)= + +# Boot Options + +:::{warning} +This function may be highly disruptive. +It may cause major service interruption, so make sure you really +need it and verify your input carefully. +::: + +VyOS has several kernel command line options to modify the normal boot +process. +To add an option, select the desired image in GRUB menu at load +time, press **e**, edit the first line, and press **Ctrl-x** to boot when +ready. + +```{image} /_static/images/boot-options.png +:align: center +:width: 80% +``` + +## Specify custom config file + +Tells the system to use specified file instead of `/config/config.boot`. +If specified file does not exist or is not readable, fall back to +default config. No additional verification is performed, so make sure +you specify a valid config file. + +```none +vyos-config=/path/to/file +``` + +To load the *factory default* config, use: + +```none +vyos-config=/opt/vyatta/etc/config.boot.default +``` + +## Disable specific boot process steps + +These options disable some boot steps. Make sure you understand the +{ref}`boot process <boot-steps>` well before using them! + +```{eval-rst} +.. glossary:: + + no-vyos-migrate + Do not perform config migration. + + no-vyos-firewall + Do not initialize default firewall chains, renders any firewall + configuration unusable. +``` diff --git a/docs/operation/md-index.md b/docs/operation/md-index.md new file mode 100644 index 00000000..f4328541 --- /dev/null +++ b/docs/operation/md-index.md @@ -0,0 +1,12 @@ +# Operation Mode + +```{eval-rst} +.. toctree:: + :maxdepth: 1 + :includehidden: + + information + boot-options + password-recovery + raid +``` diff --git a/docs/operation/md-information.md b/docs/operation/md-information.md new file mode 100644 index 00000000..314811ec --- /dev/null +++ b/docs/operation/md-information.md @@ -0,0 +1,159 @@ +--- +lastproofread: '2021-07-07' +--- + +(information)= + +# Information + +VyOS features a rich set of operational level commands to retrieve arbitrary +information about your running system. + +## Hardware + +(hardware_usb)= + +### USB + +In the past serial interface have been defined as ttySx and ttyUSBx where x was +an instance number of the serial interface. It was discovered that from system +boot to system boot the mapping of USB based serial interfaces will differ, +depending which driver was loaded first by the operating system. This will +become rather painful if you not only have serial interfaces for a console +server connected but in addition also a serial backed {ref}`wwan-interface`. + +To overcome this issue and the fact that in almost 50% of all cheap USB to +serial converters there is no serial number programmed, the USB to serial +interface is now directly identified by the USB root bridge and bus it connects +to. This somehow mimics the new network interface definitions we see in recent +Linux distributions. + +For additional details you can refer to <https://vyos.dev/T2490>. + +```{eval-rst} +.. opcmd:: show hardware usb + + Retrieve a tree like representation of all connected USB devices. + + .. note:: If a device is unplugged and re-plugged it will receive a new + Port, Dev, If identification. + + .. code-block:: none + + vyos@vyos:~$ show hardware usb + /: Bus 03.Port 1: Dev 1, Class=root_hub, Driver=ehci-pci/2p, 480M + |__ Port 1: Dev 2, If 0, Class=Hub, Driver=hub/4p, 480M + |__ Port 3: Dev 4, If 0, Class=Vendor Specific Class, Driver=qcserial, 480M + |__ Port 3: Dev 4, If 2, Class=Vendor Specific Class, Driver=qcserial, 480M + |__ Port 3: Dev 4, If 3, Class=Vendor Specific Class, Driver=qcserial, 480M + |__ Port 3: Dev 4, If 8, Class=Vendor Specific Class, Driver=qmi_wwan, 480M + /: Bus 02.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/2p, 5000M + /: Bus 01.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/2p, 480M + |__ Port 1: Dev 2, If 0, Class=Vendor Specific Class, Driver=pl2303, 12M + |__ Port 2: Dev 3, If 0, Class=Hub, Driver=hub/4p, 480M + |__ Port 4: Dev 5, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 5, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 5, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 5, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 3: Dev 4, If 0, Class=Hub, Driver=hub/4p, 480M + |__ Port 3: Dev 6, If 0, Class=Hub, Driver=hub/4p, 480M + |__ Port 4: Dev 8, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 8, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 8, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 8, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 7, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 7, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 7, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 7, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + +``` + +```{eval-rst} +.. opcmd:: show hardware usb serial + + Retrieve a list and description of all connected USB serial devices. The + device name displayed, e.g. `usb0b2.4p1.0` can be directly used when accessing + the serial console as console-server device. + + .. code-block:: none + + vyos@vyos$ show hardware usb serial + Device Model Vendor + ------ ------ ------ + usb0b1.3p1.0 MC7710 Sierra Wireless, Inc. + usb0b1.3p1.2 MC7710 Sierra Wireless, Inc. + usb0b1.3p1.3 MC7710 Sierra Wireless, Inc. + usb0b1p1.0 USB-Serial_Controller_D Prolific Technology, Inc. + usb0b2.3.3.4p1.0 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.3.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.3.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.3.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.4p1.0 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.4p1.0 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd +``` + +(information-version)= + +## Version + +```{eval-rst} +.. opcmd:: show version + + Return the current running VyOS version and build information. This includes + also the name of the release train which is ``crux`` on VyOS 1.2, ``equuleus`` + on VyOS 1.3 and ``sagitta`` on VyOS 1.4. + + .. code-block:: none + + vyos@vyos:~$ show version + + Version: VyOS 1.4-rolling-202106270801 + Release Train: sagitta + + Built by: autobuild@vyos.net + Built on: Sun 27 Jun 2021 09:50 UTC + Build UUID: ab43e735-edcb-405a-9f51-f16a1b104e52 + Build Commit ID: f544d75eab758f + + Architecture: x86_64 + Boot via: installed image + System type: KVM guest + + Hardware vendor: QEMU + Hardware model: Standard PC (i440FX + PIIX, 1996) + Hardware S/N: + Hardware UUID: Unknown + + Copyright: VyOS maintainers and contributors +``` + +```{eval-rst} +.. opcmd:: show version kernel + + Return version number of the Linux Kernel used in this release. + + .. code-block:: none + + vyos@vyos:~$ show version kernel + 5.10.46-amd64-vyos +``` + +```{eval-rst} +.. opcmd:: show version frr + + Return version number of FRR (Free Range Routing - https://frrouting.org/) + used in this release. This is the routing control plane and a successor to GNU + Zebra and Quagga. + + .. code-block:: none + + vyos@vyos:~$ show version frr + FRRouting 7.5.1-20210625-00-gf07d935a2 (vyos). + Copyright 1996-2005 Kunihiro Ishiguro, et al. +``` diff --git a/docs/operation/md-password-recovery.md b/docs/operation/md-password-recovery.md new file mode 100644 index 00000000..91f3d60f --- /dev/null +++ b/docs/operation/md-password-recovery.md @@ -0,0 +1,24 @@ +(password-recovery)= + +# Password Recovery + +Using the console, restart the VyOS router. The GRUB menu appears. +Select the relevant option from the GRUB menu and press Enter. +The option must start with “Lost password change.” + +:::{figure} /_static/images/password-recovery-01.png +:width: 600 +::: + +The stand-alone user-password recovery tool starts running and prompts +you to reset the local system user password. + +```console +Do you wish to reset the admin password? (y or n) +y +Which admin account do you want to reset?[vyos] +my_username +Enter my_username password: +Retype my_username password: +System will reboot in 10 seconds... +``` diff --git a/docs/operation/md-raid.md b/docs/operation/md-raid.md new file mode 100644 index 00000000..71a6ad5e --- /dev/null +++ b/docs/operation/md-raid.md @@ -0,0 +1,249 @@ +(raid)= + +# RAID-1 + +A Redundant Array of Independent Disks (RAID) uses two or more hard disk drives +to improve disk speed, store more data, and/or provide fault tolerance. +There are several storage schemes possible in a RAID array, each offering a +different combination of storage, reliability, and/or performance. +The VyOS system supports a “RAID 1” deployment. RAID 1 allows two or more +disks to mirror one another to provide system fault tolerance. In a RAID 1 +solution, every sector of one disk is duplicated onto every sector of all +disks in the array. Provided even one disk in the RAID 1 set is operational, +the system continues to run, even through disk replacement (provided that the +hardware supports in-service replacement of drives). +RAID 1 can be implemented using special hardware or it can be implemented in +software. The VyOS system supports software RAID 1 on two disks. +The VyOS implementation of RAID 1 allows the following: + +- Detection and reporting of disk failure +- The ability to maintain system operation with one failed disk +- The ability to boot the system with one failed disk +- The ability to replace a failed disk and initiate re-mirroring +- The ability to monitor the status of remirroring + +(raid-instalation)= + +## Installation Implications + +The VyOS systems installation utility provides several options for installing +to a RAID 1 set. You can: + +- Use the install system to create the RAID 1 set +- Use the underlying Linux commands to create a RAID 1 set before running the + install system command. +- Use a previously-created RAID 1 set. + +:::{note} +Before a permanent installation, VyOS runs a live installation +::: + +## Configuration + +### Single disk, install as normal + +When the VyOS system is installed, it automatically detects the presence of two +disks not currently part of a RAID array. In these cases, the VyOS +installation utility automatically offers you the option of configuring RAID 1 +mirroring for the drives, with the following prompt. + +```none +Would you like to configure RAID 1 mirroring on them? +``` + +- If you do not want to configure RAID 1 mirroring, enter “No” at the prompt + and continue with installation in the normal way. + +### Empty 2+ Disk + +If VyOS system detect two identical disks that are not currently part of a +RAID-1 set, the VyOS installation utility automatically offers you the option +of configuring RAID 1 mirroring for the drives, with the following prompt. + +```none +Would you like to configure RAID 1 mirroring on them? +``` + +1 - To create a new RAID 1 array, enter “Yes” at the prompt. If the system +detects a filesystem on the partitions being used for RAID 1 it will prompt you +to indicate whether you want to continue creating the RAID 1 array. + +```none +Continue creating array? +``` + +2 - To overwrite the old filesystem, enter “Yes”. + +3 - The system informs you that all data on both drives will be erased. You are +prompted to confirm that you want to continue + +```none +Are you sure you want to do this? +``` + +4 - Enter “Yes” at the prompt to retain the current VyOS configuration once +installation is complete. Enter “No” to delete the current VyOS +configuration. + +```none +Would you like me to save the data on it before I delete it? +``` + +5 - Enter “Yes” at the prompt to retain the current VyOS configuration once +installation is complete. Enter “No” to delete the current VyOS configuration. + +6 - Continue with installation in the normal way. + +### Present RAID-1 + +When the VyOS software on a system with a RAID 1 set already configured, +the installation utility will detect the array and will display the following +prompt: + +```none +Would you like to use this one? +``` + +1 - To break apart the current RAID 1 set, enter “No” at the prompt. The + +installation utility detects that there are two identical disks and offers you +the option of configuring RAID 1 mirroring on them, displaying the following +prompt: + +```none +Would you like to configure RAID 1 mirroring on them? +``` + +2 - To decline to set up a new RAID 1 configuration on the disks, enter “No” +at the prompt. The system prompts you to indicate which partition you would +like the system installed on. + +```none +Which partition should I install the root on? [sda1]: +``` + +3 - Enter the partition where you would like the system installed. The system +then prompts you to indicate whether you want to save the old configuration +data. This represents the current VyOS configuration. + +```none +Would you like me to save the data on it before I delete it? +``` + +4 - Enter “Yes” at the prompt to retain the current VyOS configuration once +installation is complete. Enter “No” to delete the current VyOS configuration. + +5 - Continue with installation in the normal way. + +### Detecting and Replacing a Failed RAID 1 Disk + +The VyOS system automatically detects a disk failure within a RAID 1 set and +reports it to the system console. You can verify the failure by issuing the +show raid command. + +To replace a bad disk within a RAID 1 set, perform the following steps: + +1 - Remove the failed disk from the RAID 1 set by issuing the following +command: + +```{eval-rst} +.. opcmd:: delete raid <RAID‐1‐device> member <disk‐partition> + + where RAID-1-device is the name of the RAID 1 device (for example, md0) and + disk-partition is the name of the failed disk partition (for example, sdb2). +``` + +2- Physically remove the failed disk from the system. If the drives are not +hot-swappable, then you must shut down the system before removing the disk. + +3 - Replace the failed drive with a drive of the same size or larger. + +4 - Format the new disk for RAID 1 by issuing the following command: + +```{eval-rst} +.. opcmd:: format disk <disk‐device1> like <disk‐device2> + + where disk-device1 is the replacement disk (for example, sdb) and + disk-device2 is the existing healthy disk (for example, sda). +``` + +5-Add the replacement disk to the RAID 1 set by issuing the following command: + +```{eval-rst} +.. opcmd:: add raid <RAID‐1‐device> member <disk‐partition> + + where RAID-1-device is the name of the RAID 1 device (for example, md0) and + disk-partition is the name of the replacement disk partition + (for example, sdb2). +``` + +## Operation + +This part introduces how to add a disk partition to a RAID-1 set initiates +mirror synchronization, check and display information. + +```{eval-rst} +.. opcmd:: add raid <RAID‐1‐device> member <disk‐partition> + + Use this command to add a member disk partition to the RAID 1 set. Adding a + disk partition to a RAID 1 set initiates mirror synchronization, where all + data on the existing member partition is copied to the new partition. +``` + +```{eval-rst} +.. opcmd:: format disk <disk‐device1> like <disk‐device2> + + This command is typically used to prepare a disk to be added to a preexisting + RAID 1 set (of which disk-device2 is already a member). +``` + +```{eval-rst} +.. opcmd:: show raid <RAID‐1‐device> + + shows output for show raid md0 as sdb1 is being added to the RAID 1 + set and is in the process of being resynchronized. + + .. code-block:: none + + vyos@vyos:~$ show raid md0 + /dev/md0: + Version : 00.90 + Creation Time : Wed Oct 29 09:19:09 2008 + Raid Level : raid1 + Array Size : 1044800 (1020.48 MiB 1069.88 MB) + Used Dev Size : 1044800 (1020.48 MiB 1069.88 MB) + Raid Devices : 2 + Total Devices : 2 + Preferred Minor : 0 + Persistence : Superblock is persistent + Update Time : Wed Oct 29 19:34:23 2008 + State : active, degraded, recovering + Active Devices : 1 + Working Devices : 2 + Failed Devices : 0 + Spare Devices : 1 + Rebuild Status : 17% complete + UUID : 981abd77:9f8c8dd8:fdbf4de4:3436c70f + Events : 0.103 + Number Major Minor RaidDevice State + 0 8 1 0 active sync /dev/sda1 + 2 8 17 1 spare rebuilding /dev/sdb1 +``` + +```{eval-rst} +.. opcmd:: show raid <RAID‐1‐device> + + Use this command to display the formatting of a hard disk. + + .. code-block:: none + + vyos@vyos:~$ show disk sda format + Disk /dev/sda: 1073 MB, 1073741824 bytes + 85 heads, 9 sectors/track, 2741 cylinders + Units = cylinders of 765 * 512 = 391680 bytes + Disk identifier: 0x000b7179 + Device Boot Start End Blocks Id System + /dev/sda1 6 2737 1044922+ fd Linux raid autodetect + + +``` diff --git a/docs/troubleshooting/md-index.md b/docs/troubleshooting/md-index.md new file mode 100644 index 00000000..2ff035c2 --- /dev/null +++ b/docs/troubleshooting/md-index.md @@ -0,0 +1,438 @@ +(troubleshooting)= + +# Troubleshooting + +Sometimes things break or don't work as expected. This section describes +several troubleshooting tools provided by VyOS that can help when something +goes wrong. + +## Connectivity Tests + +### Basic Connectivity Tests + +Verifying connectivity can be done with the familiar `ping` and `traceroute` +commands. The options for each are shown (the options for each command were +displayed using the built-in help as described in the {ref}`cli` +section and are omitted from the output here): + +```{eval-rst} +.. opcmd:: ping <destination> + + Send ICMP echo requests to destination host. There are multiple options to + ping, inkl. VRF support. + + .. code-block:: none + + vyos@vyos:~$ ping 10.1.1.1 + Possible completions: + <Enter> Execute the current command + adaptive Ping options + allow-broadcast + audible + bypass-route + count + deadline + do-not-fragment + flood + interface + interval + mark + no-loopback + numeric + pattern + quiet + record-route + size + timestamp + tos + ttl + verbose + vrf + +``` + +```{eval-rst} +.. opcmd:: traceroute <destination> + + Trace path to target. + + .. code-block:: none + + vyos@vyos:~$ traceroute + Possible completions: + <hostname> Track network path to specified node + <x.x.x.x> + <h:h:h:h:h:h:h:h> + ipv4 Track network path to <hostname|IPv4 address> + ipv6 Track network path to <hostname|IPv6 address> + +``` + +### Advanced Connectivity Tests + +```{eval-rst} +.. opcmd:: monitor traceroute <destination> + + However, another helper is available which combines ping and traceroute + into a single tool. An example of its output is shown: + + .. code-block:: none + + vyos@vyos:~$ mtr 10.62.212.12 + + My traceroute [v0.85] + vyos (0.0.0.0) + Keys: Help Display mode Restart statistics Order of fields quit + Packets Pings + Host Loss% Snt Last Avg Best Wrst StDev + 1. 10.11.110.4 0.0% 34 0.5 0.5 0.4 0.8 0.1 + 2. 10.62.255.184 0.0% 34 1.1 1.0 0.9 1.4 0.1 + 3. 10.62.255.71 0.0% 34 1.4 1.4 1.3 2.0 0.1 + 4. 10.62.212.12 0.0% 34 1.6 1.6 1.6 1.7 0.0 + + .. note:: The output consumes the screen and will replace your command + prompt. + + Several options are available for changing the display output. Press `h` to + invoke the built in help system. To quit, just press `q` and you'll be + returned to the VyOS command prompt. +``` + +### IPv6 Topology Discovery + +IPv6 uses different techniques to discover its Neighbors/topology. + +#### Router Discovery + +```{eval-rst} +.. opcmd:: force ipv6-rd interface <interface> [address <ipv6-address>] + + Discover routers via eth0. + + Example: + + .. code-block:: none + + vyos@vyos:~$ force ipv6-rd interface eth0 + Soliciting ff02::2 (ff02::2) on eth0... + + Hop limit : 60 ( 0x3c) + Stateful address conf. : No + Stateful other conf. : No + Mobile home agent : No + Router preference : high + Neighbor discovery proxy : No + Router lifetime : 1800 (0x00000708) seconds + Reachable time : unspecified (0x00000000) + Retransmit time : unspecified (0x00000000) + Prefix : 240e:fe:8ca7:ea01::/64 + On-link : Yes + Autonomous address conf.: Yes + Valid time : 2592000 (0x00278d00) seconds + Pref. time : 14400 (0x00003840) seconds + Prefix : fc00:470:f1cd:101::/64 + On-link : Yes + Autonomous address conf.: Yes + Valid time : 2592000 (0x00278d00) seconds + Pref. time : 14400 (0x00003840) seconds + Recursive DNS server : fc00:470:f1cd::ff00 + DNS server lifetime : 600 (0x00000258) seconds + Source link-layer address: 00:98:2B:F8:3F:11 + from fe80::298:2bff:fef8:3f11 +``` + +#### Neighbor Discovery + +```{eval-rst} +.. opcmd:: force ipv6-nd interface <interface> address <ipv6-address> + + + Example: + + .. code-block:: none + + vyos@vyos:~$ force ipv6-nd interface eth0 address fc00:470:f1cd:101::1 + + Soliciting fc00:470:f1cd:101::1 (fc00:470:f1cd:101::1) on eth0... + Target link-layer address: 00:98:2B:F8:3F:11 from fc00:470:f1cd:101::1 + +``` + +## Interface names + +If you find the names of your interfaces have changed, this could be because +your MAC addresses have changed. + +- For example, you have a VyOS VM with 4 Ethernet interfaces named + eth0, eth1, eth2 and eth3. Then, you migrate your VyOS VM to a different + host and find your interfaces now are eth4, eth5, eth6 and eth7. + + One way to fix this issue **taking control of the MAC addresses** is: + + Log into VyOS and run this command to display your interface settings. + + ```none + show interfaces detail + ``` + + Take note of MAC addresses. + + Now, in order to update a MAC address in the configuration, run this command + specifying the interface name and MAC address you want. + + ```none + set interfaces eth0 hw-id 00:0c:29:da:a4:fe + ``` + + If it is a VM, go into the settings of the host and set the MAC address to + the settings found in the config.boot file. You can also set the MAC to + static if the host allows so. + +- Another example could be when cloning VyOS VMs in GNS3 and you get into the + same issue: interface names have changed. + + And **a more generic way to fix it** is just deleting every MAC address at + the configuration file of the cloned machine. They will be correctly + regenerated automatically. + +## Monitoring + +VyOS features several monitoring tools. + +```none +vyos@vyos:~$ monitor +Possible completions: + bandwidth Monitor interface bandwidth in real time + bandwidth-test + Initiate or wait for bandwidth test + cluster Monitor clustering service + command Monitor an operational mode command (refreshes every 2 seconds) + conntrack-sync + Monitor conntrack-sync + content-inspection + Monitor Content-Inspection + dhcp Monitor Dynamic Host Control Protocol (DHCP) + dns Monitor a Domain Name Service (DNS) daemon + firewall Monitor Firewall + https Monitor the Secure Hypertext Transfer Protocol (HTTPS) service + lldp Monitor Link Layer Discovery Protocol (LLDP) daemon + log Monitor last lines of messages file + nat Monitor network address translation (NAT) + ndp Monitor the NDP information received by the router through the device + openvpn Monitor OpenVPN + protocol Monitor routing protocols + snmp Monitor Simple Network Management Protocol (SNMP) daemon + stop-all Stop all current background monitoring processes + traceroute Monitor the path to a destination in realtime + traffic Monitor traffic dumps + vpn Monitor VPN + vrrp Monitor Virtual Router Redundancy Protocol (VRRP) + webproxy Monitor Webproxy service +``` + +### Traffic Dumps + +To monitor interface traffic, issue the {code}`monitor traffic interface <name>` +command, replacing `<name>` with your chosen interface. + +```none +vyos@vyos:~$ monitor traffic interface eth0 +tcpdump: verbose output suppressed, use -v or -vv for full protocol decode +listening on eth0, link-type EN10MB (Ethernet), capture size 262144 bytes +15:54:28.581601 IP 192.168.0.1 > vyos: ICMP echo request, id 1870, seq 3848, length 64 +15:54:28.581660 IP vyos > 192.168.0.1: ICMP echo reply, id 1870, seq 3848, length 64 +15:54:29.583399 IP 192.168.0.1 > vyos: ICMP echo request, id 1870, seq 3849, length 64 +15:54:29.583454 IP vyos > 192.168.0.1: ICMP echo reply, id 1870, seq 3849, length 64 +^C +4 packets captured +4 packets received by filter +0 packets dropped by kernel +vyos@vyos:~$ +``` + +To quit monitoring, press `Ctrl-c` and you'll be returned to the VyOS command +prompt. + +Traffic can be filtered and saved. + +```none +vyos@vyos:~$ monitor traffic interface eth0 +Possible completions: + <Enter> Execute the current command + filter Monitor traffic matching filter conditions + save Save traffic dump from an interface to a file +``` + +### Interface Bandwidth Usage + +to take a quick view on the used bandwidth of an interface use the `monitor +bandwidth` command + +```none +vyos@vyos:~$ monitor bandwidth interface eth0 +``` + +show the following: + +```none + B (RX Bytes/second) +198.00 .|....|..................................................... +165.00 .|....|..................................................... +132.00 ||..|.|..................................................... + 99.00 ||..|.|..................................................... + 66.00 |||||||..................................................... + 33.00 |||||||..................................................... + 1 5 10 15 20 25 30 35 40 45 50 55 60 + + KiB (TX Bytes/second) + 3.67 ......|..................................................... + 3.06 ......|..................................................... + 2.45 ......|..................................................... + 1.84 ......|..................................................... + 1.22 ......|..................................................... + 0.61 :::::||..................................................... + 1 5 10 15 20 25 30 35 40 45 50 55 60 +``` + +### Interface Performance + +To take a look on the network bandwidth between two nodes, the `monitor +bandwidth-test` command is used to run iperf. + +```none +vyos@vyos:~$ monitor bandwidth-test +Possible completions: + accept Wait for bandwidth test connections (port TCP/5001) + initiate Initiate a bandwidth test +``` + +- The `accept` command opens a listening iperf server on TCP Port 5001 +- The `initiate` command connects to that server to perform the test. + +```none +vyos@vyos:~$ monitor bandwidth-test initiate +Possible completions: + <hostname> Initiate a bandwidth test to specified host (port TCP/5001) + <x.x.x.x> + <h:h:h:h:h:h:h:h> +``` + +### Monitor command + +The `monitor command` command allows you to repeatedly run a command to view +a continuously refreshed output. The command is run and output every 2 seconds, +allowing you to monitor the output continuously without having to re-run the +command. This can be useful to follow routing adjacency formation. + +```none +vyos@router:~$ monitor command "show interfaces" +``` + +Will clear the screen and show you the output of `show interfaces` every +2 seconds. + +```none +Every 2.0s: /opt/vyatta/bin/vyatta-op-cmd-wrapper Sun Mar 26 02:49:46 2019 + +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +eth0 192.168.1.1/24 u/u +eth0.5 198.51.100.4/24 u/u WAN +lo 127.0.0.1/8 u/u + ::1/128 +vti0 172.25.254.2/30 u/u +vti1 172.25.254.9/30 u/u +``` + +## Terminal/Console + +Sometimes you need to clear counters or statistics to troubleshoot better. + +To do this use the `clear` command in Operational mode. + +to clear the console output + +```none +vyos@vyos:~$ clear console +``` + +to clear interface counters + +```none +# clear all interfaces +vyos@vyos:~$ clear interface ethernet counters +# clear specific interface +vyos@vyos:~$ clear interface ethernet eth0 counters +``` + +The command follow the same logic as the `set` command in configuration mode. + +```none +# clear all counters of a interface type +vyos@vyos:~$ clear interface <interface_type> counters +# clear counter of a interface in interface_type +vyos@vyos:~$ clear interface <interface_type> <interace_name> counters +``` + +to clear counters on firewall rulesets or single rules + +```none +vyos@vyos:~$ clear firewall name <ipv4 ruleset name> counters +vyos@vyos:~$ clear firewall name <ipv4 ruleset name> rule <rule#> counters + +vyos@vyos:~$ clear firewall ipv6-name <ipv6 ruleset name> counters +vyos@vyos:~$ clear firewall ipv6-name <ipv6 ruleset name> rule <rule#> counters +``` + +## System Information + +(boot-steps)= + +### Boot Steps + +VyOS 1.2 uses [Debian Jessie] as the base Linux operating system. Jessie was +the first version of Debian that uses [systemd] as the default init system. + +These are the boot steps for VyOS 1.2 + +1. The BIOS loads Grub (or isolinux for the Live CD) +2. Grub then starts the Linux boot and loads the Linux Kernel `/boot/vmlinuz` +3. Kernel Launches Systemd `/lib/systemd/systemd` +4. Systemd loads the VyOS service file + `/lib/systemd/system/vyos-router.service` +5. The service file launches the VyOS router init script + `/usr/libexec/vyos/init/vyos-router` - this is part of the [vyatta-cfg] + Debian package + +> 1. Starts [FRR] - successor to [GNU Zebra] and [Quagga] +> 2. Initialises the boot configuration file - copies over +> `config.boot.default` if there is no configuration +> 3. Runs the configuration migration, if the configuration is for an older +> version of VyOS +> 4. Runs The pre-config script, if there is one +> `/config/scripts/vyos-preconfig-bootup.script` +> 5. If the config file was upgraded, runs any post upgrade scripts +> `/config/scripts/post-upgrade.d` +> 6. Starts `rl-system` and `firewall` +> 7. Mounts the `/boot` partition +> 8. The boot configuration file is then applied by `/opt/vyatta/sbin/ +> vyatta-boot-config-loader/opt/vyatta/etc/config/config.boot` +> +> > 1. The config loader script writes log entries to +> > `/var/log/vyatta-config-loader.log` +> +> 09. Runs `telinit q` to tell the init system to reload `/etc/inittab` +> 10. Finally it runs the post-config script +> `/config/scripts/vyos-postconfig-bootup.script` + + + +[debian jessie]: https://www.debian.org/releases/jessie/ +[frr]: https://frrouting.org/ +[gnu zebra]: https://www.gnu.org/software/zebra/ +[pcap filter expressions]: http://www.tcpdump.org/manpages/pcap-filter.7.html +[quagga]: https://www.quagga.net/ +[systemd]: https://freedesktop.org/wiki/Software/systemd/ +[tshark]: https://www.wireshark.org/docs/man-pages/tshark.html +[vyatta-cfg]: https://github.com/vyos/vyatta-cfg |
