diff options
Diffstat (limited to 'docs')
446 files changed, 64759 insertions, 14 deletions
diff --git a/docs/Makefile b/docs/Makefile index cb6226af..b0068b1a 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -12,22 +12,43 @@ AUTOHOST = 0.0.0.0 AUTOPORT = 8000 AUTOOPTS = --watch . +SWAP = python3 ../scripts/swap_sources.py + # Put it first so that "make" without argument is like "make help". help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -.PHONY: help Makefile +.PHONY: help Makefile swap restore html dirhtml pdf livehtml defaultvalue -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) +swap: + $(SWAP) --swap -livehtml: - sphinx-autobuild --host $(AUTOHOST) --port $(AUTOPORT) $(AUTOOPTS) \ - "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) +restore: + $(SWAP) --restore + +html: swap + @trap '$(SWAP) --restore' EXIT; \ + $(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +dirhtml: swap + @trap '$(SWAP) --restore' EXIT; \ + $(SPHINXBUILD) -M dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) +pdf: swap + @trap '$(SWAP) --restore' EXIT; \ + $(SPHINXBUILD) -M latexpdf "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +livehtml: swap + @trap '$(SWAP) --restore' EXIT; \ + sphinx-autobuild --host $(AUTOHOST) --port $(AUTOPORT) \ + --ignore '$(BUILDDIR)/**' \ + --ignore '**/md-*' \ + "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) defaultvalue: export VYOS_DEFAULT=True -defaultvalue: - @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file +defaultvalue: html + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_ext/vyos.py b/docs/_ext/vyos.py index c1a96cd9..ac5b8159 100644 --- a/docs/_ext/vyos.py +++ b/docs/_ext/vyos.py @@ -364,8 +364,18 @@ class CmdInclude(SphinxDirective): line = re.sub('{{\s?var' + str(i) + '\s?}}',value,line) new_include_lines.append(line) - self.state._renderer.nested_render_text(''.join(new_include_lines), self.lineno) - return [] + if hasattr(self.state, '_renderer'): + self.state._renderer.nested_render_text(''.join(new_include_lines), self.lineno) + return [] + from docutils.statemachine import ViewList + from docutils import nodes + content = ''.join(new_include_lines) + vl = ViewList() + for i, line in enumerate(content.splitlines(keepends=False)): + vl.append(line, include_file[1], i) + node = nodes.Element() + self.state.nested_parse(vl, self.content_offset, node, match_titles=True) + return node.children class CfgcmdlistDirective(Directive): 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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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/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.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/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.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.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.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.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.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.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.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.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.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.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.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.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.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-eip-01.webp b/docs/_static/images/cloud-aws-eip-01.webp Binary files differnew file mode 100644 index 00000000..a78758fd --- /dev/null +++ b/docs/_static/images/cloud-aws-eip-01.webp diff --git a/docs/_static/images/cloud-aws-eip-02.webp b/docs/_static/images/cloud-aws-eip-02.webp Binary files differnew file mode 100644 index 00000000..39c5c7b7 --- /dev/null +++ b/docs/_static/images/cloud-aws-eip-02.webp diff --git a/docs/_static/images/cloud-aws-eni-01.webp b/docs/_static/images/cloud-aws-eni-01.webp Binary files differnew file mode 100644 index 00000000..51212929 --- /dev/null +++ b/docs/_static/images/cloud-aws-eni-01.webp diff --git a/docs/_static/images/cloud-aws-eni-02.webp b/docs/_static/images/cloud-aws-eni-02.webp Binary files differnew file mode 100644 index 00000000..139313f6 --- /dev/null +++ b/docs/_static/images/cloud-aws-eni-02.webp diff --git a/docs/_static/images/cloud-aws-ha-architecture.webp b/docs/_static/images/cloud-aws-ha-architecture.webp Binary files differnew file mode 100644 index 00000000..3021a6e0 --- /dev/null +++ b/docs/_static/images/cloud-aws-ha-architecture.webp diff --git a/docs/_static/images/cloud-aws-igw-01.webp b/docs/_static/images/cloud-aws-igw-01.webp Binary files differnew file mode 100644 index 00000000..21a90f32 --- /dev/null +++ b/docs/_static/images/cloud-aws-igw-01.webp diff --git a/docs/_static/images/cloud-aws-igw-02.webp b/docs/_static/images/cloud-aws-igw-02.webp Binary files differnew file mode 100644 index 00000000..7f43c4be --- /dev/null +++ b/docs/_static/images/cloud-aws-igw-02.webp diff --git a/docs/_static/images/cloud-aws-keypair-01.webp b/docs/_static/images/cloud-aws-keypair-01.webp Binary files differnew file mode 100644 index 00000000..fdeff52c --- /dev/null +++ b/docs/_static/images/cloud-aws-keypair-01.webp diff --git a/docs/_static/images/cloud-aws-keypair-02.webp b/docs/_static/images/cloud-aws-keypair-02.webp Binary files differnew file mode 100644 index 00000000..89fac0f8 --- /dev/null +++ b/docs/_static/images/cloud-aws-keypair-02.webp diff --git a/docs/_static/images/cloud-aws-keypair-03.webp b/docs/_static/images/cloud-aws-keypair-03.webp Binary files differnew file mode 100644 index 00000000..c71c105c --- /dev/null +++ b/docs/_static/images/cloud-aws-keypair-03.webp diff --git a/docs/_static/images/cloud-aws-keypair-04.webp b/docs/_static/images/cloud-aws-keypair-04.webp Binary files differnew file mode 100644 index 00000000..bcacb96e --- /dev/null +++ b/docs/_static/images/cloud-aws-keypair-04.webp diff --git a/docs/_static/images/cloud-aws-route-01.webp b/docs/_static/images/cloud-aws-route-01.webp Binary files differnew file mode 100644 index 00000000..5adda05a --- /dev/null +++ b/docs/_static/images/cloud-aws-route-01.webp diff --git a/docs/_static/images/cloud-aws-route-02.webp b/docs/_static/images/cloud-aws-route-02.webp Binary files differnew file mode 100644 index 00000000..7e670263 --- /dev/null +++ b/docs/_static/images/cloud-aws-route-02.webp diff --git a/docs/_static/images/cloud-aws-route-03.webp b/docs/_static/images/cloud-aws-route-03.webp Binary files differnew file mode 100644 index 00000000..4b643b0d --- /dev/null +++ b/docs/_static/images/cloud-aws-route-03.webp diff --git a/docs/_static/images/cloud-aws-route-04.webp b/docs/_static/images/cloud-aws-route-04.webp Binary files differnew file mode 100644 index 00000000..1b67de77 --- /dev/null +++ b/docs/_static/images/cloud-aws-route-04.webp diff --git a/docs/_static/images/cloud-aws-sg-01.webp b/docs/_static/images/cloud-aws-sg-01.webp Binary files differnew file mode 100644 index 00000000..9cf13f7b --- /dev/null +++ b/docs/_static/images/cloud-aws-sg-01.webp diff --git a/docs/_static/images/cloud-aws-sg-02.webp b/docs/_static/images/cloud-aws-sg-02.webp Binary files differnew file mode 100644 index 00000000..5b00ed91 --- /dev/null +++ b/docs/_static/images/cloud-aws-sg-02.webp diff --git a/docs/_static/images/cloud-aws-sg-03.webp b/docs/_static/images/cloud-aws-sg-03.webp Binary files differnew file mode 100644 index 00000000..9cc462d6 --- /dev/null +++ b/docs/_static/images/cloud-aws-sg-03.webp diff --git a/docs/_static/images/cloud-aws-sg-04.webp b/docs/_static/images/cloud-aws-sg-04.webp Binary files differnew file mode 100644 index 00000000..5577d2e6 --- /dev/null +++ b/docs/_static/images/cloud-aws-sg-04.webp diff --git a/docs/_static/images/cloud-aws-sg-05.webp b/docs/_static/images/cloud-aws-sg-05.webp Binary files differnew file mode 100644 index 00000000..6bc4e12d --- /dev/null +++ b/docs/_static/images/cloud-aws-sg-05.webp diff --git a/docs/_static/images/cloud-aws-subnet-01.webp b/docs/_static/images/cloud-aws-subnet-01.webp Binary files differnew file mode 100644 index 00000000..ab3ded81 --- /dev/null +++ b/docs/_static/images/cloud-aws-subnet-01.webp diff --git a/docs/_static/images/cloud-aws-subnet-02.webp b/docs/_static/images/cloud-aws-subnet-02.webp Binary files differnew file mode 100644 index 00000000..8d28906f --- /dev/null +++ b/docs/_static/images/cloud-aws-subnet-02.webp diff --git a/docs/_static/images/cloud-aws-subnet-03.webp b/docs/_static/images/cloud-aws-subnet-03.webp Binary files differnew file mode 100644 index 00000000..0f1f14c9 --- /dev/null +++ b/docs/_static/images/cloud-aws-subnet-03.webp diff --git a/docs/_static/images/cloud-aws-to-azure.webp b/docs/_static/images/cloud-aws-to-azure.webp Binary files differnew file mode 100644 index 00000000..535dfac9 --- /dev/null +++ b/docs/_static/images/cloud-aws-to-azure.webp diff --git a/docs/_static/images/cloud-aws-vpc-01.webp b/docs/_static/images/cloud-aws-vpc-01.webp Binary files differnew file mode 100644 index 00000000..2b1ad120 --- /dev/null +++ b/docs/_static/images/cloud-aws-vpc-01.webp diff --git a/docs/_static/images/cloud-aws-vpc-02.webp b/docs/_static/images/cloud-aws-vpc-02.webp Binary files differnew file mode 100644 index 00000000..78bd25e9 --- /dev/null +++ b/docs/_static/images/cloud-aws-vpc-02.webp diff --git a/docs/_static/images/cloud-aws-vpc-03.webp b/docs/_static/images/cloud-aws-vpc-03.webp Binary files differnew file mode 100644 index 00000000..101a1924 --- /dev/null +++ b/docs/_static/images/cloud-aws-vpc-03.webp diff --git a/docs/_static/images/cloud-aws-vyos-01.webp b/docs/_static/images/cloud-aws-vyos-01.webp Binary files differnew file mode 100644 index 00000000..4f594b16 --- /dev/null +++ b/docs/_static/images/cloud-aws-vyos-01.webp diff --git a/docs/_static/images/cloud-aws-vyos-02.webp b/docs/_static/images/cloud-aws-vyos-02.webp Binary files differnew file mode 100644 index 00000000..70e37e49 --- /dev/null +++ b/docs/_static/images/cloud-aws-vyos-02.webp diff --git a/docs/_static/images/cloud-aws-vyos-03.webp b/docs/_static/images/cloud-aws-vyos-03.webp Binary files differnew file mode 100644 index 00000000..f526c28a --- /dev/null +++ b/docs/_static/images/cloud-aws-vyos-03.webp diff --git a/docs/_static/images/cloud-aws-vyos-04.webp b/docs/_static/images/cloud-aws-vyos-04.webp Binary files differnew file mode 100644 index 00000000..a18e5aee --- /dev/null +++ b/docs/_static/images/cloud-aws-vyos-04.webp diff --git a/docs/_static/images/cloud-aws-vyos-05.webp b/docs/_static/images/cloud-aws-vyos-05.webp Binary files differnew file mode 100644 index 00000000..f7699fe3 --- /dev/null +++ b/docs/_static/images/cloud-aws-vyos-05.webp diff --git a/docs/_static/images/cloud-aws-vyos-06.webp b/docs/_static/images/cloud-aws-vyos-06.webp Binary files differnew file mode 100644 index 00000000..06e771d6 --- /dev/null +++ b/docs/_static/images/cloud-aws-vyos-06.webp diff --git a/docs/_static/images/cloud-aws-vyos-07.webp b/docs/_static/images/cloud-aws-vyos-07.webp Binary files differnew file mode 100644 index 00000000..6b5efedc --- /dev/null +++ b/docs/_static/images/cloud-aws-vyos-07.webp diff --git a/docs/_static/images/cloud-aws-vyos-08.webp b/docs/_static/images/cloud-aws-vyos-08.webp Binary files differnew file mode 100644 index 00000000..3b6aa12b --- /dev/null +++ b/docs/_static/images/cloud-aws-vyos-08.webp diff --git a/docs/_static/images/cloud-aws-vyos-09.webp b/docs/_static/images/cloud-aws-vyos-09.webp Binary files differnew file mode 100644 index 00000000..06e771d6 --- /dev/null +++ b/docs/_static/images/cloud-aws-vyos-09.webp diff --git a/docs/_static/images/cloud-aws-vyos-10.webp b/docs/_static/images/cloud-aws-vyos-10.webp Binary files differnew file mode 100644 index 00000000..772d8e80 --- /dev/null +++ b/docs/_static/images/cloud-aws-vyos-10.webp diff --git a/docs/_static/images/cloud-aws-vyos-11.webp b/docs/_static/images/cloud-aws-vyos-11.webp Binary files differnew file mode 100644 index 00000000..8893e3bd --- /dev/null +++ b/docs/_static/images/cloud-aws-vyos-11.webp diff --git a/docs/_static/images/cloud-azure-ha-architecture.webp b/docs/_static/images/cloud-azure-ha-architecture.webp Binary files differnew file mode 100644 index 00000000..20e3e6dc --- /dev/null +++ b/docs/_static/images/cloud-azure-ha-architecture.webp diff --git a/docs/_static/images/cloud-azure-nic-01.webp b/docs/_static/images/cloud-azure-nic-01.webp Binary files differnew file mode 100644 index 00000000..37c22a86 --- /dev/null +++ b/docs/_static/images/cloud-azure-nic-01.webp diff --git a/docs/_static/images/cloud-azure-nic-02.webp b/docs/_static/images/cloud-azure-nic-02.webp Binary files differnew file mode 100644 index 00000000..5a348732 --- /dev/null +++ b/docs/_static/images/cloud-azure-nic-02.webp diff --git a/docs/_static/images/cloud-azure-nic-03.webp b/docs/_static/images/cloud-azure-nic-03.webp Binary files differnew file mode 100644 index 00000000..9002fba3 --- /dev/null +++ b/docs/_static/images/cloud-azure-nic-03.webp diff --git a/docs/_static/images/cloud-azure-nic-04.webp b/docs/_static/images/cloud-azure-nic-04.webp Binary files differnew file mode 100644 index 00000000..c24b8cda --- /dev/null +++ b/docs/_static/images/cloud-azure-nic-04.webp diff --git a/docs/_static/images/cloud-azure-pub-ip-01.webp b/docs/_static/images/cloud-azure-pub-ip-01.webp Binary files differnew file mode 100644 index 00000000..648e97cc --- /dev/null +++ b/docs/_static/images/cloud-azure-pub-ip-01.webp diff --git a/docs/_static/images/cloud-azure-pub-ip-02.webp b/docs/_static/images/cloud-azure-pub-ip-02.webp Binary files differnew file mode 100644 index 00000000..b79eb2d8 --- /dev/null +++ b/docs/_static/images/cloud-azure-pub-ip-02.webp diff --git a/docs/_static/images/cloud-azure-pub-ip-03.webp b/docs/_static/images/cloud-azure-pub-ip-03.webp Binary files differnew file mode 100644 index 00000000..e6ec5fa8 --- /dev/null +++ b/docs/_static/images/cloud-azure-pub-ip-03.webp diff --git a/docs/_static/images/cloud-azure-rg-01.webp b/docs/_static/images/cloud-azure-rg-01.webp Binary files differnew file mode 100644 index 00000000..194b66ae --- /dev/null +++ b/docs/_static/images/cloud-azure-rg-01.webp diff --git a/docs/_static/images/cloud-azure-rg-02.webp b/docs/_static/images/cloud-azure-rg-02.webp Binary files differnew file mode 100644 index 00000000..6b1bcea5 --- /dev/null +++ b/docs/_static/images/cloud-azure-rg-02.webp diff --git a/docs/_static/images/cloud-azure-route-01.webp b/docs/_static/images/cloud-azure-route-01.webp Binary files differnew file mode 100644 index 00000000..44036f0d --- /dev/null +++ b/docs/_static/images/cloud-azure-route-01.webp diff --git a/docs/_static/images/cloud-azure-route-02.webp b/docs/_static/images/cloud-azure-route-02.webp Binary files differnew file mode 100644 index 00000000..41159484 --- /dev/null +++ b/docs/_static/images/cloud-azure-route-02.webp diff --git a/docs/_static/images/cloud-azure-route-03.webp b/docs/_static/images/cloud-azure-route-03.webp Binary files differnew file mode 100644 index 00000000..d316c94f --- /dev/null +++ b/docs/_static/images/cloud-azure-route-03.webp diff --git a/docs/_static/images/cloud-azure-route-04.webp b/docs/_static/images/cloud-azure-route-04.webp Binary files differnew file mode 100644 index 00000000..edfcb232 --- /dev/null +++ b/docs/_static/images/cloud-azure-route-04.webp diff --git a/docs/_static/images/cloud-azure-route-05.webp b/docs/_static/images/cloud-azure-route-05.webp Binary files differnew file mode 100644 index 00000000..ead3e73e --- /dev/null +++ b/docs/_static/images/cloud-azure-route-05.webp diff --git a/docs/_static/images/cloud-azure-sg-01.webp b/docs/_static/images/cloud-azure-sg-01.webp Binary files differnew file mode 100644 index 00000000..d7c38a99 --- /dev/null +++ b/docs/_static/images/cloud-azure-sg-01.webp diff --git a/docs/_static/images/cloud-azure-sg-02.webp b/docs/_static/images/cloud-azure-sg-02.webp Binary files differnew file mode 100644 index 00000000..fd2ddc34 --- /dev/null +++ b/docs/_static/images/cloud-azure-sg-02.webp diff --git a/docs/_static/images/cloud-azure-sg-03.webp b/docs/_static/images/cloud-azure-sg-03.webp Binary files differnew file mode 100644 index 00000000..fa4a2b8f --- /dev/null +++ b/docs/_static/images/cloud-azure-sg-03.webp diff --git a/docs/_static/images/cloud-azure-sg-04.webp b/docs/_static/images/cloud-azure-sg-04.webp Binary files differnew file mode 100644 index 00000000..13078e17 --- /dev/null +++ b/docs/_static/images/cloud-azure-sg-04.webp diff --git a/docs/_static/images/cloud-azure-vm-01.webp b/docs/_static/images/cloud-azure-vm-01.webp Binary files differnew file mode 100644 index 00000000..a305a263 --- /dev/null +++ b/docs/_static/images/cloud-azure-vm-01.webp diff --git a/docs/_static/images/cloud-azure-vm-02.webp b/docs/_static/images/cloud-azure-vm-02.webp Binary files differnew file mode 100644 index 00000000..3a629165 --- /dev/null +++ b/docs/_static/images/cloud-azure-vm-02.webp diff --git a/docs/_static/images/cloud-azure-vm-03.webp b/docs/_static/images/cloud-azure-vm-03.webp Binary files differnew file mode 100644 index 00000000..e1f1b98d --- /dev/null +++ b/docs/_static/images/cloud-azure-vm-03.webp diff --git a/docs/_static/images/cloud-azure-vm-04.webp b/docs/_static/images/cloud-azure-vm-04.webp Binary files differnew file mode 100644 index 00000000..c28a10b5 --- /dev/null +++ b/docs/_static/images/cloud-azure-vm-04.webp diff --git a/docs/_static/images/cloud-azure-vm-05.webp b/docs/_static/images/cloud-azure-vm-05.webp Binary files differnew file mode 100644 index 00000000..1cfb2d56 --- /dev/null +++ b/docs/_static/images/cloud-azure-vm-05.webp diff --git a/docs/_static/images/cloud-azure-vm-06.webp b/docs/_static/images/cloud-azure-vm-06.webp Binary files differnew file mode 100644 index 00000000..ce71b375 --- /dev/null +++ b/docs/_static/images/cloud-azure-vm-06.webp diff --git a/docs/_static/images/cloud-azure-vm-07.webp b/docs/_static/images/cloud-azure-vm-07.webp Binary files differnew file mode 100644 index 00000000..d1ff8585 --- /dev/null +++ b/docs/_static/images/cloud-azure-vm-07.webp diff --git a/docs/_static/images/cloud-azure-vm-08.webp b/docs/_static/images/cloud-azure-vm-08.webp Binary files differnew file mode 100644 index 00000000..93b290fa --- /dev/null +++ b/docs/_static/images/cloud-azure-vm-08.webp diff --git a/docs/_static/images/cloud-azure-vm-09.webp b/docs/_static/images/cloud-azure-vm-09.webp Binary files differnew file mode 100644 index 00000000..1a9ec0da --- /dev/null +++ b/docs/_static/images/cloud-azure-vm-09.webp diff --git a/docs/_static/images/cloud-azure-vm-10.webp b/docs/_static/images/cloud-azure-vm-10.webp Binary files differnew file mode 100644 index 00000000..feec6515 --- /dev/null +++ b/docs/_static/images/cloud-azure-vm-10.webp diff --git a/docs/_static/images/cloud-azure-vm-11.webp b/docs/_static/images/cloud-azure-vm-11.webp Binary files differnew file mode 100644 index 00000000..15c8149f --- /dev/null +++ b/docs/_static/images/cloud-azure-vm-11.webp diff --git a/docs/_static/images/cloud-azure-vm-12.webp b/docs/_static/images/cloud-azure-vm-12.webp Binary files differnew file mode 100644 index 00000000..f549f3e7 --- /dev/null +++ b/docs/_static/images/cloud-azure-vm-12.webp diff --git a/docs/_static/images/cloud-azure-vm-13.webp b/docs/_static/images/cloud-azure-vm-13.webp Binary files differnew file mode 100644 index 00000000..2d6964bf --- /dev/null +++ b/docs/_static/images/cloud-azure-vm-13.webp diff --git a/docs/_static/images/cloud-azure-vnet-01.webp b/docs/_static/images/cloud-azure-vnet-01.webp Binary files differnew file mode 100644 index 00000000..0b24d59c --- /dev/null +++ b/docs/_static/images/cloud-azure-vnet-01.webp diff --git a/docs/_static/images/cloud-azure-vnet-02.webp b/docs/_static/images/cloud-azure-vnet-02.webp Binary files differnew file mode 100644 index 00000000..033ac5a2 --- /dev/null +++ b/docs/_static/images/cloud-azure-vnet-02.webp diff --git a/docs/_static/images/cloud-azure-vnet-03.webp b/docs/_static/images/cloud-azure-vnet-03.webp Binary files differnew file mode 100644 index 00000000..7fbdd484 --- /dev/null +++ b/docs/_static/images/cloud-azure-vnet-03.webp diff --git a/docs/_static/images/cloud-azure-vnet-04.webp b/docs/_static/images/cloud-azure-vnet-04.webp Binary files differnew file mode 100644 index 00000000..49fe70d5 --- /dev/null +++ b/docs/_static/images/cloud-azure-vnet-04.webp diff --git a/docs/_static/images/cloud-azure-vnet-05.webp b/docs/_static/images/cloud-azure-vnet-05.webp Binary files differnew file mode 100644 index 00000000..2ac0bcd7 --- /dev/null +++ b/docs/_static/images/cloud-azure-vnet-05.webp diff --git a/docs/_static/images/cloud-azure-vnet-06.webp b/docs/_static/images/cloud-azure-vnet-06.webp Binary files differnew file mode 100644 index 00000000..0da36ab0 --- /dev/null +++ b/docs/_static/images/cloud-azure-vnet-06.webp 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.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-market-01.webp b/docs/_static/images/cloud-gcp-market-01.webp Binary files differnew file mode 100644 index 00000000..ffe56746 --- /dev/null +++ b/docs/_static/images/cloud-gcp-market-01.webp diff --git a/docs/_static/images/cloud-gcp-market-02.webp b/docs/_static/images/cloud-gcp-market-02.webp Binary files differnew file mode 100644 index 00000000..78aa7192 --- /dev/null +++ b/docs/_static/images/cloud-gcp-market-02.webp diff --git a/docs/_static/images/cloud-gcp-market-03.webp b/docs/_static/images/cloud-gcp-market-03.webp Binary files differnew file mode 100644 index 00000000..617970a9 --- /dev/null +++ b/docs/_static/images/cloud-gcp-market-03.webp diff --git a/docs/_static/images/cloud-gcp-market-04.webp b/docs/_static/images/cloud-gcp-market-04.webp Binary files differnew file mode 100644 index 00000000..f6518aaa --- /dev/null +++ b/docs/_static/images/cloud-gcp-market-04.webp diff --git a/docs/_static/images/cloud-gcp-market-05.webp b/docs/_static/images/cloud-gcp-market-05.webp Binary files differnew file mode 100644 index 00000000..20089558 --- /dev/null +++ b/docs/_static/images/cloud-gcp-market-05.webp diff --git a/docs/_static/images/cloud-gcp-proj.webp b/docs/_static/images/cloud-gcp-proj.webp Binary files differnew file mode 100644 index 00000000..c7842b72 --- /dev/null +++ b/docs/_static/images/cloud-gcp-proj.webp diff --git a/docs/_static/images/cloud-gcp-svc.webp b/docs/_static/images/cloud-gcp-svc.webp Binary files differnew file mode 100644 index 00000000..8f19d73a --- /dev/null +++ b/docs/_static/images/cloud-gcp-svc.webp diff --git a/docs/_static/images/cloud-gcp-vm-01.webp b/docs/_static/images/cloud-gcp-vm-01.webp Binary files differnew file mode 100644 index 00000000..be27a325 --- /dev/null +++ b/docs/_static/images/cloud-gcp-vm-01.webp diff --git a/docs/_static/images/cloud-gcp-vm-02.webp b/docs/_static/images/cloud-gcp-vm-02.webp Binary files differnew file mode 100644 index 00000000..c72dcb51 --- /dev/null +++ b/docs/_static/images/cloud-gcp-vm-02.webp diff --git a/docs/_static/images/cloud-gcp-vm-03.webp b/docs/_static/images/cloud-gcp-vm-03.webp Binary files differnew file mode 100644 index 00000000..0e30aff7 --- /dev/null +++ b/docs/_static/images/cloud-gcp-vm-03.webp diff --git a/docs/_static/images/cloud-gcp-vm-04.webp b/docs/_static/images/cloud-gcp-vm-04.webp Binary files differnew file mode 100644 index 00000000..0dc2cb41 --- /dev/null +++ b/docs/_static/images/cloud-gcp-vm-04.webp diff --git a/docs/_static/images/cloud-gcp-vm-06.webp b/docs/_static/images/cloud-gcp-vm-06.webp Binary files differnew file mode 100644 index 00000000..36a33528 --- /dev/null +++ b/docs/_static/images/cloud-gcp-vm-06.webp diff --git a/docs/_static/images/cloud-gcp-vm-07.webp b/docs/_static/images/cloud-gcp-vm-07.webp Binary files differnew file mode 100644 index 00000000..5ba96ee3 --- /dev/null +++ b/docs/_static/images/cloud-gcp-vm-07.webp diff --git a/docs/_static/images/cloud-gcp-vm-08.webp b/docs/_static/images/cloud-gcp-vm-08.webp Binary files differnew file mode 100644 index 00000000..21524ec8 --- /dev/null +++ b/docs/_static/images/cloud-gcp-vm-08.webp diff --git a/docs/_static/images/cloud-gcp-vm-09.webp b/docs/_static/images/cloud-gcp-vm-09.webp Binary files differnew file mode 100644 index 00000000..1cfb2d56 --- /dev/null +++ b/docs/_static/images/cloud-gcp-vm-09.webp diff --git a/docs/_static/images/cloud-gcp-vpc-01.webp b/docs/_static/images/cloud-gcp-vpc-01.webp Binary files differnew file mode 100644 index 00000000..194fa272 --- /dev/null +++ b/docs/_static/images/cloud-gcp-vpc-01.webp diff --git a/docs/_static/images/cloud-gcp-vpc-02.webp b/docs/_static/images/cloud-gcp-vpc-02.webp Binary files differnew file mode 100644 index 00000000..02267cca --- /dev/null +++ b/docs/_static/images/cloud-gcp-vpc-02.webp diff --git a/docs/_static/images/cloud-gcp-vpc-03.webp b/docs/_static/images/cloud-gcp-vpc-03.webp Binary files differnew file mode 100644 index 00000000..f738729b --- /dev/null +++ b/docs/_static/images/cloud-gcp-vpc-03.webp diff --git a/docs/_static/images/cloud-gcp-vpc-04.webp b/docs/_static/images/cloud-gcp-vpc-04.webp Binary files differnew file mode 100644 index 00000000..6cd6f63e --- /dev/null +++ b/docs/_static/images/cloud-gcp-vpc-04.webp diff --git a/docs/_static/images/cloud-gcp-vpc-05.webp b/docs/_static/images/cloud-gcp-vpc-05.webp Binary files differnew file mode 100644 index 00000000..a8dafebb --- /dev/null +++ b/docs/_static/images/cloud-gcp-vpc-05.webp diff --git a/docs/_static/images/cloud-gcp-vpc-06.webp b/docs/_static/images/cloud-gcp-vpc-06.webp Binary files differnew file mode 100644 index 00000000..72fe8bbb --- /dev/null +++ b/docs/_static/images/cloud-gcp-vpc-06.webp diff --git a/docs/_static/images/cloud-gcp-vpc-07.webp b/docs/_static/images/cloud-gcp-vpc-07.webp Binary files differnew file mode 100644 index 00000000..2225f55e --- /dev/null +++ b/docs/_static/images/cloud-gcp-vpc-07.webp 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/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.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-packet-flow.webp b/docs/_static/images/firewall-bridge-packet-flow.webp Binary files differnew file mode 100644 index 00000000..908eaee3 --- /dev/null +++ b/docs/_static/images/firewall-bridge-packet-flow.webp 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.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.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.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-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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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/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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.webp b/docs/_static/images/password-recovery-01.webp Binary files differnew file mode 100644 index 00000000..26427ecb --- /dev/null +++ b/docs/_static/images/password-recovery-01.webp 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.webp b/docs/_static/images/permanent_install.webp Binary files differnew file mode 100644 index 00000000..6ab06b0a --- /dev/null +++ b/docs/_static/images/permanent_install.webp 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/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.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.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.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.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.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.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.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.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.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/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.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.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.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.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.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.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/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.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.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.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.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.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.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.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.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.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.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.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.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.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-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.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.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.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.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.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.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.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..9e18a829 --- /dev/null +++ b/docs/_swap.txt @@ -0,0 +1,210 @@ +# 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. +# +# Default: every imported md-*.md page is listed below so MD is served +# by default. To revert a specific page back to RST, remove its line +# (or comment it out). + +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 +cli +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 +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..446d0f64 --- /dev/null +++ b/docs/automation/md-cloud-init.md @@ -0,0 +1,376 @@ +lastproofread +2021-07-12 + +# 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](https://cloudinit.readthedocs.io/en/latest/topics/examples.html#writing-out-arbitrary-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 `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 `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](https://cloudinit.readthedocs.io/en/latest/topics/network-config.html) 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](https://github.com/vyos/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](https://docs.vyos.io/en/equuleus/automation/cloud-init.html?highlight=cloud-init#vyos-cloud-init). +- Cloud-init [network-config-docs](https://cloudinit.readthedocs.io/en/latest/topics/network-config.html). +- Proxmox [Cloud-init-Support](https://pve.proxmox.com/pve-docs/pve-admin-guide.html#qm_cloud_init). diff --git a/docs/automation/md-command-scripting.md b/docs/automation/md-command-scripting.md new file mode 100644 index 00000000..5c2d8f19 --- /dev/null +++ b/docs/automation/md-command-scripting.md @@ -0,0 +1,219 @@ +lastproofread +2023-01-16 + +# 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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Custom scripts are not executed with root privileges +(Use sudo inside if this is necessary). + +</div> + +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. +``` + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +For configuration/upgrade management issues, modification of this +script should be the last option. Always try to find solutions based on CLI +commands first. + +</div> diff --git a/docs/automation/md-index.md b/docs/automation/md-index.md new file mode 100644 index 00000000..bf456f0d --- /dev/null +++ b/docs/automation/md-index.md @@ -0,0 +1,14 @@ +# VyOS Automation + +<div class="toctree" maxdepth="2"> + +vyos-api +vyos-ansible +terraform/index +vyos-napalm +vyos-netmiko +vyos-salt +command-scripting +cloud-init + +</div> diff --git a/docs/automation/md-vyos-ansible.md b/docs/automation/md-vyos-ansible.md new file mode 100644 index 00000000..ba348ca1 --- /dev/null +++ b/docs/automation/md-vyos-ansible.md @@ -0,0 +1,86 @@ +lastproofread +2023-01-16 + +# 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..7618e262 --- /dev/null +++ b/docs/automation/md-vyos-api.md @@ -0,0 +1,380 @@ +lastproofread +2023-01-16 + +# VyOS API + +For configuration and enabling the API see `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..ca3fd97c --- /dev/null +++ b/docs/automation/md-vyos-napalm.md @@ -0,0 +1,137 @@ +lastproofread +2023-01-16 + +# Napalm + +VyOS supports some [napalm](https://napalm.readthedocs.io/en/latest/base.html) 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] +``` diff --git a/docs/automation/md-vyos-netmiko.md b/docs/automation/md-vyos-netmiko.md new file mode 100644 index 00000000..84622a0d --- /dev/null +++ b/docs/automation/md-vyos-netmiko.md @@ -0,0 +1,67 @@ +lastproofread +2023-01-16 + +# Netmiko + +VyOS supports configuration via [netmiko](https://github.com/ktbyers/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] +``` diff --git a/docs/automation/md-vyos-salt.md b/docs/automation/md-vyos-salt.md new file mode 100644 index 00000000..8b770a8f --- /dev/null +++ b/docs/automation/md-vyos-salt.md @@ -0,0 +1,204 @@ +lastproofread +2023-01-16 + +<div id="vyos-salt"> + +</div> + +# Salt + +VyOS supports op-mode and configuration via [salt](https://docs.saltproject.io/en/latest/contents.html). + +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](https://docs.saltproject.io/en/latest/ref/modules/all/salt.modules.netmiko_mod.html#module-salt.modules.netmiko_mod) 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# +/ # +``` diff --git a/docs/automation/terraform/md-index.md b/docs/automation/terraform/md-index.md new file mode 100644 index 00000000..9d02b913 --- /dev/null +++ b/docs/automation/terraform/md-index.md @@ -0,0 +1,11 @@ +# VyOS Terraform + +<div class="toctree" maxdepth="1" caption="Content"> + +terraformvyos +terraformAWS +terraformAZ +terraformvSphere +terraformGoogle + +</div> diff --git a/docs/automation/terraform/md-terraformAWS.md b/docs/automation/terraform/md-terraformAWS.md new file mode 100644 index 00000000..7485b3eb --- /dev/null +++ b/docs/automation/terraform/md-terraformAWS.md @@ -0,0 +1,493 @@ +lastproofread +2024-01-11 + +# 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. + +<img src="/_static/images/aws.webp" class="align-center" style="width:50.0%" alt="Network Topology Diagram" /> + +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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/create-key-pairs.html) and download your .pem key + +<img src="/_static/images/keypairs.webp" class="align-center" style="width:50.0%" alt="Network Topology Diagram" /> + +3 Create a security [group](https://docs.aws.amazon.com/cli/latest/userguide/cli-services-ec2-sg.html) for the new VyOS instance and open all traffic + +<img src="/_static/images/sg.webp" class="align-center" style="width:50.0%" alt="Network Topology Diagram" /> + +<img src="/_static/images/traffic.webp" class="align-center" style="width:50.0%" alt="Network Topology Diagram" /> + +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](#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](https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/AWS_terraform_ansible_single_vyos_instance-main) diff --git a/docs/automation/terraform/md-terraformAZ.md b/docs/automation/terraform/md-terraformAZ.md new file mode 100644 index 00000000..e4ed9de9 --- /dev/null +++ b/docs/automation/terraform/md-terraformAZ.md @@ -0,0 +1,466 @@ +lastproofread +2024-03-03 + +# 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](#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" + type = string + sensitive = true +} + +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: "{{ vault_vyos_ssh_pass }}" +``` + +## Sourse files for Azure from GIT + +All files about the article can be found [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..8b137891 --- /dev/null +++ b/docs/automation/terraform/md-terraformGoogle.md @@ -0,0 +1 @@ + diff --git a/docs/automation/terraform/md-terraformvSphere.md b/docs/automation/terraform/md-terraformvSphere.md new file mode 100644 index 00000000..2e5d3927 --- /dev/null +++ b/docs/automation/terraform/md-terraformvSphere.md @@ -0,0 +1,372 @@ +lastproofread +2024-03-03 + +# 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](#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 commands 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](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..78606cba --- /dev/null +++ b/docs/automation/terraform/md-terraformvyos.md @@ -0,0 +1,31 @@ +lastproofread +2024-03-03 + +# 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](https://developer.hashicorp.com/terraform/intro). + +Need to [install](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli) 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 +``` diff --git a/docs/conf.py b/docs/conf.py index 7d933306..bbc74ea8 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")) @@ -83,7 +84,23 @@ 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', +] + +# MyST-Parser configuration +myst_enable_extensions = ["colon_fence", "deflist", "fieldlist", "substitution"] +myst_fence_as_directive = ["cfgcmd", "opcmd", "cmdincludemd"] + +# Incremental RST→MyST swap: extend exclude_patterns with the RST paths that +# swap_sources.py just hid behind their md-prefixed counterparts. +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' @@ -193,5 +210,32 @@ texinfo_documents = [ ] +def _prefer_webp(app): + """Prepend WebP to supported image types for HTML builders so MyST pages + can use webp without falling back to PDF/PNG fallbacks.""" + 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. + + Skips md-*.md staging files (pre-swap originals that are not public). + """ + if exception is not None: + return + src = pathlib.Path(app.srcdir) + out = pathlib.Path(app.outdir) + for path in src.rglob("*.md"): + if path.name.startswith("md-"): + continue + 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..179f7885 --- /dev/null +++ b/docs/configexamples/autotest/DHCPRelay_through_GRE/md-DHCPRelay_through_GRE.md @@ -0,0 +1,89 @@ +# DHCP Relay through 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 <span class="title-ref">transport</span> VyOS represent a large +Network. + + + +## Configuration + +First, we configure the transport network and the Tunnel interface. + +Transport: + +<div class="literalinclude" language="none"> + +<span id="include">include</span>/transport.conf + +</div> + +DHCP-Server + +<div class="literalinclude" language="none" lines="1-8"> + +<span id="include">include</span>/dhcp-server.conf + +</div> + +DHCP-Relay + +<div class="literalinclude" language="none" lines="1-8"> + +<span id="include">include</span>/dhcp-relay.conf + +</div> + +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 + +<div class="literalinclude" language="none" lines="9-13"> + +<span id="include">include</span>/dhcp-server.conf + +</div> + +DHCP-Relay + +<div class="literalinclude" language="none" lines="9-10"> + +<span id="include">include</span>/dhcp-relay.conf + +</div> + +## 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..c090c16e --- /dev/null +++ b/docs/configexamples/autotest/L3VPN_EVPN/md-L3VPN_EVPN.md @@ -0,0 +1,245 @@ +# 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. + +<div class="literalinclude" language="none" lines="1-6"> + +<span id="include">include</span>/PE1.conf + +</div> + +## Topology + +We use the following network topology in this example: + + + +## 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 + +<div class="literalinclude" language="none" lines="8-38"> + +<span id="include">include</span>/PE1.conf + +</div> + +PE2 + +<div class="literalinclude" language="none" lines="8-38"> + +<span id="include">include</span>/PE2.conf + +</div> + +PE3 + +<div class="literalinclude" language="none" lines="8-38"> + +<span id="include">include</span>/PE3.conf + +</div> + +## 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 + +<div class="literalinclude" language="none" lines="40-96"> + +<span id="include">include</span>/PE1.conf + +</div> + +PE2 + +<div class="literalinclude" language="none" lines="40-89"> + +<span id="include">include</span>/PE2.conf + +</div> + +PE3 + +<div class="literalinclude" language="none" lines="40-89"> + +<span id="include">include</span>/PE3.conf + +</div> + +## 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..7e662cfd --- /dev/null +++ b/docs/configexamples/autotest/OpenVPN_with_LDAP/md-OpenVPN_with_LDAP.md @@ -0,0 +1,226 @@ +# 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 + + + +## 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 `here <configuration/pki/index:pki>` for more information. + +Add the LDAP plugin configuration file <span class="title-ref">/config/auth/ldap-auth.config</span>\ +Check all possible settings [here](https://github.com/threerings/openvpn-auth-ldap/blob/master/auth-ldap.conf) + +<div class="literalinclude" language="none"> + +<span id="include">include</span>/ldap-auth.config + +</div> + +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 '<REDACTED>' +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 '<REDACTED>' +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 '<REDACTED>' +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. + +<div class="literalinclude" language="none"> + +<span id="include">include</span>/ovpn-server.conf + +</div> + +## 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----- +...REDACTED... +-----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..ea0ca8e3 --- /dev/null +++ b/docs/configexamples/autotest/Wireguard/md-Wireguard.md @@ -0,0 +1,108 @@ +# 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. + + + +## Configuration + +Set the local subnet on eth2 and the public ip address eth1 on each site. + +Central + +<div class="literalinclude" language="none" lines="1-2"> + +<span id="include">include</span>/central.conf + +</div> + +Branch + +<div class="literalinclude" language="none" lines="1-2"> + +<span id="include">include</span>/branch.conf + +</div> + +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 + +<div class="literalinclude" language="none" lines="4-12"> + +<span id="include">include</span>/central.conf + +</div> + +Branch + +<div class="literalinclude" language="none" lines="4-12"> + +<span id="include">include</span>/branch.conf + +</div> + +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 + +<div class="literalinclude" language="none" lines="14"> + +<span id="include">include</span>/central.conf + +</div> + +Branch + +<div class="literalinclude" language="none" lines="14"> + +<span id="include">include</span>/branch.conf + +</div> + +## 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..8c8eaf78 --- /dev/null +++ b/docs/configexamples/autotest/tunnelbroker/md-tunnelbroker.md @@ -0,0 +1,195 @@ +# 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 + + + +### Configuration + +First, we configure the `vyos-wan` interface to get a DHCP address. + +<div class="literalinclude" language="none"> + +<span id="include">include</span>/vyos-wan.conf + +</div> + +Now we are able to setup the tunnel interface. + +<div class="literalinclude" language="none" lines="1-5"> + +<span id="include">include</span>/vyos-wan_tun0.conf + +</div> + +Setup the ipv6 default route to the tunnel interface + +<div class="literalinclude" language="none" lines="7"> + +<span id="include">include</span>/vyos-wan_tun0.conf + +</div> + +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: + +<div class="literalinclude" language="none" lines="13"> + +<span id="include">include</span>/vyos-wan_tun0.conf + +</div> + +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: + +<div class="literalinclude" language="none" lines="9-11"> + +<span id="include">include</span>/vyos-wan_tun0.conf + +</div> + +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. + +<div class="literalinclude" language="none"> + +<span id="include">include</span>/client.conf + +</div> + +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 <span class="title-ref">Routed /48</span> 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 `firewall`. The usage is identical, except for +instead of <span class="title-ref">set firewall name NAME</span>, you would use <span class="title-ref">set firewall ipv6-name +NAME</span>. + +Similarly, to attach the firewall, you would use <span class="title-ref">set interfaces ethernet eth0 +firewall in ipv6-name</span> or <span class="title-ref">et firewall zone LOCAL from WAN firewall ipv6-name</span>. diff --git a/docs/configexamples/md-azure-vpn-bgp.md b/docs/configexamples/md-azure-vpn-bgp.md new file mode 100644 index 00000000..d6ac6552 --- /dev/null +++ b/docs/configexamples/md-azure-vpn-bgp.md @@ -0,0 +1,162 @@ +lastproofread +2021-06-28 + +# 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 +`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 + +<table style="width:86%;"> +<colgroup> +<col style="width: 55%" /> +<col style="width: 30%" /> +</colgroup> +<tbody> +<tr> +<td>WAN Interface</td> +<td>eth0</td> +</tr> +<tr> +<td>On-premises address space</td> +<td>10.10.0.0/16</td> +</tr> +<tr> +<td>Azure address space</td> +<td><blockquote> +<p>10.0.0.0/16</p> +</blockquote></td> +</tr> +<tr> +<td>Vyos public IP</td> +<td>198.51.100.3</td> +</tr> +<tr> +<td>Vyos private IP</td> +<td>10.10.0.5</td> +</tr> +<tr> +<td>Azure VNet Gateway public IP</td> +<td><blockquote> +<p>203.0.113.2</p> +</blockquote></td> +</tr> +<tr> +<td>Azure VNet Gateway BGP IP</td> +<td><blockquote> +<p>10.0.0.4</p> +</blockquote></td> +</tr> +<tr> +<td>Pre-shared key</td> +<td>ch00s3-4-s3cur3-psk</td> +</tr> +<tr> +<td>Vyos ASN</td> +<td>64499</td> +</tr> +<tr> +<td>Azure ASN</td> +<td>65540</td> +</tr> +</tbody> +</table> + +## 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 203.0.113.2 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 203.0.113.2 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..e1b69fc3 --- /dev/null +++ b/docs/configexamples/md-azure-vpn-dual-bgp.md @@ -0,0 +1,192 @@ +lastproofread +2021-06-28 + +# 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 + +<table style="width:86%;"> +<colgroup> +<col style="width: 55%" /> +<col style="width: 30%" /> +</colgroup> +<tbody> +<tr> +<td>WAN Interface</td> +<td>eth0</td> +</tr> +<tr> +<td>On-premises address space</td> +<td>10.10.0.0/16</td> +</tr> +<tr> +<td>Azure address space</td> +<td><blockquote> +<p>10.0.0.0/16</p> +</blockquote></td> +</tr> +<tr> +<td>Vyos public IP</td> +<td>198.51.100.3</td> +</tr> +<tr> +<td>Vyos private IP</td> +<td>10.10.0.5</td> +</tr> +<tr> +<td>Azure VNet Gateway 1 public IP</td> +<td><blockquote> +<p>203.0.113.2</p> +</blockquote></td> +</tr> +<tr> +<td>Azure VNet Gateway 2 public IP</td> +<td><blockquote> +<p>203.0.113.3</p> +</blockquote></td> +</tr> +<tr> +<td>Azure VNet Gateway BGP IP</td> +<td><blockquote> +<p>10.0.0.4,10.0.0.5</p> +</blockquote></td> +</tr> +<tr> +<td>Pre-shared key</td> +<td>ch00s3-4-s3cur3-psk</td> +</tr> +<tr> +<td>Vyos ASN</td> +<td>64499</td> +</tr> +<tr> +<td>Azure ASN</td> +<td>65540</td> +</tr> +</tbody> +</table> + +## 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..89a0da8b --- /dev/null +++ b/docs/configexamples/md-bgp-ipv6-unnumbered.md @@ -0,0 +1,170 @@ +lastproofread +2021-06-28 + +# BGP IPv6 unnumbered with extended nexthop + +General information can be found in the `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..2849a66c --- /dev/null +++ b/docs/configexamples/md-firewall.md @@ -0,0 +1,13 @@ +lastproofread +2024-06-14 + +# Firewall Examples + +This section contains examples of firewall configurations for various deployments. + +<div class="toctree" maxdepth="2"> + +fwall-and-vrf +zone-policy + +</div> diff --git a/docs/configexamples/md-fwall-and-vrf.md b/docs/configexamples/md-fwall-and-vrf.md new file mode 100644 index 00000000..c7320902 --- /dev/null +++ b/docs/configexamples/md-fwall-and-vrf.md @@ -0,0 +1,118 @@ +# 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: + +<img src="/_static/images/firewall-and-vrf-blueprints.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +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..1a4589dd --- /dev/null +++ b/docs/configexamples/md-ha.md @@ -0,0 +1,572 @@ +lastproofread +2021-06-28 + +# 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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +## 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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +### 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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +We explicitly exclude the primary upstream network so that BGP or +OSPF traffic doesn't accidentally get NAT'ed. + +</div> + +``` 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' +``` + +### 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 a different /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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Router id's must be unique. + +</div> + +**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..ec0a5077 --- /dev/null +++ b/docs/configexamples/md-index.md @@ -0,0 +1,54 @@ +# Configuration Blueprints + +This chapter contains various configuration examples: + +<div class="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 + +</div> + +# 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 + +<div class="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 + +</div> 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..62eec937 --- /dev/null +++ b/docs/configexamples/md-inter-vrf-routing-vrf-lite.md @@ -0,0 +1,910 @@ +# 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 `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 + +<img src="/_static/images/inter-vrf-routing-vrf-lite.webp" class="align-center" style="width:70.0%" alt="Network Topology Diagram" /> + +### IP Schema + +<table style="width:83%;"> +<colgroup> +<col style="width: 15%" /> +<col style="width: 18%" /> +<col style="width: 23%" /> +<col style="width: 26%" /> +</colgroup> +<tbody> +<tr> +<td>Device-A</td> +<td><blockquote> +<p>Device-B</p> +</blockquote></td> +<td><blockquote> +<p>IPv4 Network</p> +</blockquote></td> +<td><blockquote> +<p>IPv6 Network</p> +</blockquote></td> +</tr> +<tr> +<td><blockquote> +<p>Core</p> +</blockquote></td> +<td><blockquote> +<p>LAN1</p> +</blockquote></td> +<td><blockquote> +<p>10.1.1.0/30</p> +</blockquote></td> +<td><blockquote> +<p>2001:db8::/127</p> +</blockquote></td> +</tr> +<tr> +<td><blockquote> +<p>Core</p> +</blockquote></td> +<td><blockquote> +<p>LAN2</p> +</blockquote></td> +<td>172.16.2.0/30</td> +<td><blockquote> +<p>2001:db8::2/127</p> +</blockquote></td> +</tr> +<tr> +<td><blockquote> +<p>Core</p> +</blockquote></td> +<td>Management</td> +<td>192.168.3.0/30</td> +<td><blockquote> +<p>2001:db8::4/127</p> +</blockquote></td> +</tr> +<tr> +<td><blockquote> +<p>Core</p> +</blockquote></td> +<td><blockquote> +<p>ISP</p> +</blockquote></td> +<td><blockquote> +<p>10.2.2.0/30</p> +</blockquote></td> +<td><blockquote> +<p>2001:db8::6/127</p> +</blockquote></td> +</tr> +</tbody> +</table> + +### RD & RT Schema + +<table style="width:51%;"> +<colgroup> +<col style="width: 18%" /> +<col style="width: 16%" /> +<col style="width: 16%" /> +</colgroup> +<tbody> +<tr> +<td><blockquote> +<p>VRF</p> +</blockquote></td> +<td><blockquote> +<p>RD</p> +</blockquote></td> +<td><blockquote> +<p>RT</p> +</blockquote></td> +</tr> +<tr> +<td><blockquote> +<p>LAN1</p> +</blockquote></td> +<td><blockquote> +<p>64496:1</p> +</blockquote></td> +<td><blockquote> +<p>64496:1</p> +</blockquote></td> +</tr> +<tr> +<td><blockquote> +<p>LAN2</p> +</blockquote></td> +<td><blockquote> +<p>64496:2</p> +</blockquote></td> +<td><blockquote> +<p>64496:2</p> +</blockquote></td> +</tr> +<tr> +<td>Management</td> +<td>64496:50</td> +<td>64496:50</td> +</tr> +<tr> +<td><blockquote> +<p>Internet</p> +</blockquote></td> +<td>64496:100</td> +<td>64496:100</td> +</tr> +</tbody> +</table> + +## Configurations + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +### 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 +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +- 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::1 +``` + +- 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..7410a43f --- /dev/null +++ b/docs/configexamples/md-ipsec-cisco-policy-based.md @@ -0,0 +1,423 @@ +lastproofread +2025-06-26 + +# 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 + +<img src="/_static/images/cisco-vpn-ipsec.webp" class="align-center" alt="Network Topology Diagram" /> + +## Prerequirements + +**VyOS:** + +<table style="width:38%;"> +<colgroup> +<col style="width: 13%" /> +<col style="width: 23%" /> +</colgroup> +<tbody> +<tr> +<td>WAN IP</td> +<td><blockquote> +<p>10.0.1.2/30</p> +</blockquote></td> +</tr> +<tr> +<td>LAN1 IP</td> +<td>192.168.0.1/24</td> +</tr> +<tr> +<td>LAN2 IP</td> +<td>192.168.1.1/24</td> +</tr> +</tbody> +</table> + +**Cisco:** + +<table style="width:39%;"> +<colgroup> +<col style="width: 13%" /> +<col style="width: 25%" /> +</colgroup> +<tbody> +<tr> +<td>WAN IP</td> +<td>10.0.2.2/30</td> +</tr> +<tr> +<td>LAN1 IP</td> +<td>192.168.10.1/24</td> +</tr> +<tr> +<td>LAN2 IP</td> +<td>192.168.11.1/24</td> +</tr> +</tbody> +</table> + +**IKE parameters:** + +<table style="width:42%;"> +<colgroup> +<col style="width: 27%" /> +<col style="width: 13%" /> +</colgroup> +<tbody> +<tr> +<td>Encryption</td> +<td>AES-256</td> +</tr> +<tr> +<td>HASH</td> +<td>SHA-1</td> +</tr> +<tr> +<td>Diff-Helman Group</td> +<td>14</td> +</tr> +<tr> +<td>Life-Time</td> +<td>28800</td> +</tr> +<tr> +<td>IKE Version</td> +<td>2</td> +</tr> +</tbody> +</table> + +**IPsec parameters:** + +<table style="width:32%;"> +<colgroup> +<col style="width: 18%" /> +<col style="width: 13%" /> +</colgroup> +<tbody> +<tr> +<td>Encryption</td> +<td>AES-256</td> +</tr> +<tr> +<td>HASH</td> +<td>SHA-256</td> +</tr> +<tr> +<td>Life-Time</td> +<td>3600</td> +</tr> +<tr> +<td>PFS</td> +<td>disable</td> +</tr> +</tbody> +</table> + +**Traffic Selectors** +192.168.0.0/24 \<==\> 192.168.10.0/24 + +192.168.1.0/24 \<==\> 192.168.11.0/24 + +**Hosts configuration** + +<table style="width:33%;"> +<colgroup> +<col style="width: 12%" /> +<col style="width: 20%" /> +</colgroup> +<tbody> +<tr> +<td>PC1 IP</td> +<td>192.168.0.2</td> +</tr> +<tr> +<td>PC2 IP</td> +<td>192.168.1.2</td> +</tr> +<tr> +<td>PC3 IP</td> +<td>192.168.10.2</td> +</tr> +<tr> +<td>PC4 IP</td> +<td>192.168.11.2</td> +</tr> +</tbody> +</table> + +## Configuration + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Pfs is disabled in Cisco by default. + +</div> + +### 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..181a9d56 --- /dev/null +++ b/docs/configexamples/md-ipsec-cisco-route-based.md @@ -0,0 +1,469 @@ +lastproofread +2025-06-26 + +# 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 + +<img src="/_static/images/cisco-vpn-ipsec.webp" class="align-center" alt="Network Topology Diagram" /> + +## Prerequirements + +**VyOS:** + +<table style="width:38%;"> +<colgroup> +<col style="width: 13%" /> +<col style="width: 23%" /> +</colgroup> +<tbody> +<tr> +<td>WAN IP</td> +<td><blockquote> +<p>10.0.1.2/30</p> +</blockquote></td> +</tr> +<tr> +<td>LAN1 IP</td> +<td>192.168.0.1/24</td> +</tr> +<tr> +<td>LAN2 IP</td> +<td>192.168.1.1/24</td> +</tr> +</tbody> +</table> + +**Cisco:** + +<table style="width:39%;"> +<colgroup> +<col style="width: 13%" /> +<col style="width: 25%" /> +</colgroup> +<tbody> +<tr> +<td>WAN IP</td> +<td>10.0.2.2/30</td> +</tr> +<tr> +<td>LAN1 IP</td> +<td>192.168.10.1/24</td> +</tr> +<tr> +<td>LAN2 IP</td> +<td>192.168.11.1/24</td> +</tr> +</tbody> +</table> + +**IKE parameters:** + +<table style="width:42%;"> +<colgroup> +<col style="width: 27%" /> +<col style="width: 13%" /> +</colgroup> +<tbody> +<tr> +<td>Encryption</td> +<td>AES-128</td> +</tr> +<tr> +<td>HASH</td> +<td>SHA-1</td> +</tr> +<tr> +<td>Diff-Helman Group</td> +<td>14</td> +</tr> +<tr> +<td>Life-Time</td> +<td>28800</td> +</tr> +<tr> +<td>IKE Version</td> +<td>1</td> +</tr> +</tbody> +</table> + +**IPsec parameters:** + +<table style="width:32%;"> +<colgroup> +<col style="width: 18%" /> +<col style="width: 13%" /> +</colgroup> +<tbody> +<tr> +<td>Encryption</td> +<td>AES-256</td> +</tr> +<tr> +<td>HASH</td> +<td>SHA-256</td> +</tr> +<tr> +<td>Life-Time</td> +<td>3600</td> +</tr> +<tr> +<td>PFS</td> +<td>disable</td> +</tr> +</tbody> +</table> + +**Hosts configuration** + +<table style="width:33%;"> +<colgroup> +<col style="width: 12%" /> +<col style="width: 20%" /> +</colgroup> +<tbody> +<tr> +<td>PC1 IP</td> +<td>192.168.0.2</td> +</tr> +<tr> +<td>PC2 IP</td> +<td>192.168.1.2</td> +</tr> +<tr> +<td>PC3 IP</td> +<td>192.168.10.2</td> +</tr> +<tr> +<td>PC4 IP</td> +<td>192.168.11.2</td> +</tr> +</tbody> +</table> + +## Configuration + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Pfs is disabled in Cisco by default. + +</div> + +### 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..191d59f9 --- /dev/null +++ b/docs/configexamples/md-ipsec-pa-route-based.md @@ -0,0 +1,462 @@ +lastproofread +2025-06-26 + +# 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 + +<img src="/_static/images/ipsec-vyos-pa.webp" class="align-center" alt="Network Topology Diagram" /> + +## Prerequirements + +**VyOS:** + +<table style="width:38%;"> +<colgroup> +<col style="width: 13%" /> +<col style="width: 23%" /> +</colgroup> +<tbody> +<tr> +<td>WAN IP</td> +<td><blockquote> +<p>10.0.1.2/30</p> +</blockquote></td> +</tr> +<tr> +<td>LAN1 IP</td> +<td>192.168.0.1/24</td> +</tr> +<tr> +<td>LAN2 IP</td> +<td>192.168.1.1/24</td> +</tr> +</tbody> +</table> + +**Palo Alto:** + +<table style="width:39%;"> +<colgroup> +<col style="width: 13%" /> +<col style="width: 25%" /> +</colgroup> +<tbody> +<tr> +<td>WAN IP</td> +<td>10.0.2.2/30</td> +</tr> +<tr> +<td>LAN1 IP</td> +<td>192.168.10.1/24</td> +</tr> +<tr> +<td>LAN2 IP</td> +<td>192.168.11.1/24</td> +</tr> +</tbody> +</table> + +**IKE parameters:** + +<table style="width:42%;"> +<colgroup> +<col style="width: 27%" /> +<col style="width: 13%" /> +</colgroup> +<tbody> +<tr> +<td>Encryption</td> +<td>AES-128</td> +</tr> +<tr> +<td>HASH</td> +<td>SHA-1</td> +</tr> +<tr> +<td>Diff-Helman Group</td> +<td>14</td> +</tr> +<tr> +<td>Life-Time</td> +<td>28800</td> +</tr> +<tr> +<td>IKE Version</td> +<td>1</td> +</tr> +</tbody> +</table> + +**IPsec parameters:** + +<table style="width:32%;"> +<colgroup> +<col style="width: 18%" /> +<col style="width: 13%" /> +</colgroup> +<tbody> +<tr> +<td>Encryption</td> +<td>AES-256</td> +</tr> +<tr> +<td>HASH</td> +<td>SHA-256</td> +</tr> +<tr> +<td>Life-Time</td> +<td>3600</td> +</tr> +<tr> +<td>PFS</td> +<td>disable</td> +</tr> +</tbody> +</table> + +**Hosts configuration** + +<table style="width:33%;"> +<colgroup> +<col style="width: 12%" /> +<col style="width: 20%" /> +</colgroup> +<tbody> +<tr> +<td>PC1 IP</td> +<td>192.168.0.2</td> +</tr> +<tr> +<td>PC2 IP</td> +<td>192.168.1.2</td> +</tr> +<tr> +<td>PC3 IP</td> +<td>192.168.10.2</td> +</tr> +<tr> +<td>PC4 IP</td> +<td>192.168.11.2</td> +</tr> +</tbody> +</table> + +## 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 PA authentication local-id '10.0.1.2' +set vpn ipsec site-to-site peer PA authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer PA authentication remote-id '10.0.2.2' +set vpn ipsec site-to-site peer PA connection-type 'initiate' +set vpn ipsec site-to-site peer PA default-esp-group 'ESP-GROUP' +set vpn ipsec site-to-site peer PA ike-group 'IKE-GROUP' +set vpn ipsec site-to-site peer PA local-address '10.0.1.2' +set vpn ipsec site-to-site peer PA remote-address '10.0.2.2' +set vpn ipsec site-to-site peer PA vti bind 'vti1' +``` + +### Palo Alto + +GUI Configuration: +Network -\> Network Profiles -\> IKE Crypto + +<img src="/_static/images/PA-IKE-group.webp" class="align-center" alt="image" /> + +Network -\> Network Profiles -\> IKE Gateways + +<img src="/_static/images/PA-IKE-GW-1.webp" class="align-center" alt="image" /> + +<img src="/_static/images/PA-IKE-GW-2.webp" class="align-center" alt="image" /> + +Network -\> Network Profiles -\> IPSec Crypto + +<img src="/_static/images/PA-ESP-group.webp" class="align-center" alt="image" /> + +Network -\> Interfaces + +<img src="/_static/images/PA-tunnel-1.webp" class="align-center" alt="image" /> + +<img src="/_static/images/PA-tunnel-2.webp" class="align-center" alt="image" /> + +<img src="/_static/images/PA-tunnel-3.webp" class="align-center" alt="image" /> + +Network -\> IPSec Tunnels + +<img src="/_static/images/PA-IPsec-tunnel.webp" class="align-center" alt="image" /> + +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 Palo Alto 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..02269386 --- /dev/null +++ b/docs/configexamples/md-l3vpn-hub-and-spoke.md @@ -0,0 +1,1135 @@ +# 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 `configuration/vrf/index:L3VPN VRFs` chapter. + +## Topology + +<img src="/_static/images/L3VPN_hub_and_spoke.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +## 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: + +<table style="width:95%;"> +<colgroup> +<col style="width: 13%" /> +<col style="width: 9%" /> +<col style="width: 15%" /> +<col style="width: 21%" /> +<col style="width: 17%" /> +<col style="width: 17%" /> +</colgroup> +<tbody> +<tr> +<td><blockquote> +<p>Node</p> +</blockquote></td> +<td><blockquote> +<p>Role</p> +</blockquote></td> +<td><blockquote> +<p>VRF</p> +</blockquote></td> +<td><blockquote> +<p>RD</p> +</blockquote></td> +<td><blockquote> +<p>RT import</p> +</blockquote></td> +<td><blockquote> +<p>RT export</p> +</blockquote></td> +</tr> +<tr> +<td>VyOS-PE2</td> +<td>Hub</td> +<td>BLUE_HUB</td> +<td>10.80.80.1:1011</td> +<td>65035:1011 +65035:1030</td> +<td>65035:1030</td> +</tr> +<tr> +<td>VyOS-PE1</td> +<td>Spoke</td> +<td>BLUE_SPOKE</td> +<td>10.50.50.1:1011</td> +<td>65035:1030</td> +<td>65035:1011</td> +</tr> +<tr> +<td>VyOS-PE3</td> +<td>Spoke</td> +<td>BLUE_SPOKE</td> +<td>10.60.60.1:1011</td> +<td>65035:1030</td> +<td>65035:1011</td> +</tr> +</tbody> +</table> + +## 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..125f5ab6 --- /dev/null +++ b/docs/configexamples/md-lac-lns.md @@ -0,0 +1,167 @@ +lastproofread +2024-02-21 + +# 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 + +<img src="/_static/images/lac-lns-diagram.webp" class="align-center" style="width:60.0%" alt="Network Topology Diagram" /> + +## 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 + +% stop_vyoslinter + +``` 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 +``` + +% start_vyoslinter + +:::{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. + +<img src="/_static/images/lac-lns-winclient.webp" class="align-center" style="width:100.0%" alt="Window PPPoE Client Configuration" /> + +### 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..79b096ce --- /dev/null +++ b/docs/configexamples/md-nmp.md @@ -0,0 +1,42 @@ +lastproofread +2023-03-26 + +# 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. + +% stop_vyoslinter + +``` 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' +``` + +% start_vyoslinter + +## Configuration 'NMP' + +Next, you should just follow the pictures: + +<img src="/_static/images/nmp1.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +<img src="/_static/images/nmp2.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +<img src="/_static/images/nmp3.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +<img src="/_static/images/nmp4.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +<img src="/_static/images/nmp5.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +<img src="/_static/images/nmp6.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +<img src="/_static/images/nmp7.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +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..8fe92b39 --- /dev/null +++ b/docs/configexamples/md-ospf-unnumbered.md @@ -0,0 +1,114 @@ +lastproofread +2021-06-29 + +# OSPF unnumbered with ECMP + +General information can be found in the `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..7d158031 --- /dev/null +++ b/docs/configexamples/md-pppoe-ipv6-basic.md @@ -0,0 +1,104 @@ +lastproofread +2021-06-29 + +# 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 + +<img src="/_static/images/pppoe-ipv6-pd-diagram.webp" class="align-center" style="width:60.0%" alt="Network Topology Diagram" /> + +## Configurations + +### PPPoE Setup + +``` none +set interfaces pppoe pppoe0 authentication password <YOUR PASSWORD> +set interfaces pppoe pppoe0 authentication username <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 `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..520200c5 --- /dev/null +++ b/docs/configexamples/md-qos.md @@ -0,0 +1,144 @@ +lastproofread +2023-02-18 + +# 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: + +<img src="/_static/images/qos1.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +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 ADDRESS30 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 + +<img src="/_static/images/qos2.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +Before the interface eth0 on router VyOS3 + +<img src="/_static/images/qos3.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +After the interface eth0 on router VyOS3 + +<img src="/_static/images/qos4.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +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 + +<img src="/_static/images/qos5.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +``` 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' +``` + +<img src="/_static/images/qos6.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +- 172.17.1.2/24 CS0 + +<img src="/_static/images/qos7.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +- 172.17.1.2/24 CS0 - \> CS4 + +<img src="/_static/images/qos8.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +- 172.17.1.2/24 CS4 - \> CS5 + +<img src="/_static/images/qos9.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +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. + +<img src="/_static/images/qos10.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +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..707d4f4b --- /dev/null +++ b/docs/configexamples/md-segment-routing-isis.md @@ -0,0 +1,273 @@ +lastproofread +2023-04-10 + +# 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 `EVE-NG (Emulated Virtual +Environment NG)`. + +<figure> +<img src="/_static/images/vyos-sr-isis.webp" alt="ISIS-SR network" /> +<figcaption>ISIS-SR example network</figcaption> +</figure> + +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..4e146838 --- /dev/null +++ b/docs/configexamples/md-wan-load-balancing.md @@ -0,0 +1,164 @@ +lastproofread +2021-06-29 + +<div id="wan-load-balancing"> + +</div> + +# WAN Load Balancer examples + +% stop_vyoslinter + +## Example 1: Distributing load evenly + +The setup used in this example is shown in the following diagram: + +<img src="/_static/images/Wan_load_balancing1.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +### 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. + +### 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. + +### 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. + +### 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: + +<img src="/_static/images/Wan_load_balancing_exclude1.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +### 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 +``` + +% start_vyoslinter diff --git a/docs/configexamples/md-zone-policy.md b/docs/configexamples/md-zone-policy.md new file mode 100644 index 00000000..afa8c940 --- /dev/null +++ b/docs/configexamples/md-zone-policy.md @@ -0,0 +1,416 @@ +lastproofread +2024-06-14 + +# Zone-Policy example + +<div class="note"> + +<div class="title"> + +Note + +</div> + +In `T2199` the syntax of the zone configuration was changed. +The zone configuration moved from `zone-policy zone <name>` to `firewall zone <name>`. + +</div> + +## 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. + +<img src="/_static/images/zone-policy-diagram.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +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..1cd322f9 --- /dev/null +++ b/docs/configuration/container/md-index.md @@ -0,0 +1,512 @@ +lastproofread +2022-06-10 + +# Container + +The VyOS container implementation is based on <span class="title-ref">Podman\<https://podman.io/\></span> as +a daemonless container engine. + +## Configuration + +<div class="cfgcmd"> + +set container name \<name\> image + +Sets the image name in the hub registry + +``` 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 + +``` none +set container name mysql-server image quay.io/mysql:8.0 +``` + +</div> + +<div class="cfgcmd"> + +set container name \<name\> entrypoint \<entrypoint\> + +Override the default entrypoint from the image for a container. + +</div> + +<div class="cfgcmd"> + +set container name \<name\> command \<command\> + +Override the default command from the image for a container. + +</div> + +<div class="cfgcmd"> + +set container name \<name\> arguments \<arguments\> + +Set the command arguments for a container. + +</div> + +<div class="cfgcmd"> + +set container name \<name\> host-name \<hostname\> + +Set the host name for a container. + +</div> + +<div class="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. + +</div> + +<div class="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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +**allow-host-networks** cannot be used with **network** + +</div> + +</div> + +<div class="cfgcmd"> + +set container name \<name\> network \<networkname\> + +Attaches user-defined network to a container. +Only one network must be specified and must already exist. + +</div> + +<div class="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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The first IP in the container network is reserved by the +engine and cannot be used + +</div> + +</div> + +<div class="cfgcmd"> + +set container name \<name\> description \<text\> + +Set a container description + +</div> + +<div class="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. + +``` 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' +``` + +</div> + +<div class="cfgcmd"> + +set container name \<name\> port \<portname\> source \<portnumber\> + +</div> + +<div class="cfgcmd"> + +set container name \<name\> port \<portname\> destination \<portnumber\> + +</div> + +<div class="cfgcmd"> + +set container name \<name\> port \<portname\> protocol \<tcp | udp\> + +Publish a port for the container. + +``` 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 +``` + +</div> + +<div class="cfgcmd"> + +set container name \<name\> volume \<volumename\> source \<path\> + +</div> + +<div class="cfgcmd"> + +set container name \<name\> volume \<volumename\> destination \<path\> + +Mount a volume into the container + +``` none +set container name coredns volume 'corefile' source /config/coredns/Corefile +set container name coredns volume 'corefile' destination /etc/Corefile +``` + +</div> + +<div class="cfgcmd"> + +set container name \<name\> volume \<volumename\> mode \<ro | rw\> + +Volume is either mounted as rw (read-write - default) or ro (read-only) + +</div> + +<div class="cfgcmd"> + +set container name \<name\> uid \<number\> + +</div> + +<div class="cfgcmd"> + +set container name \<name\> gid \<number\> + +Set the User ID or Group ID of the container + +</div> + +<div class="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 + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set container name \<name\> memory \<MB\> + +Constrain the memory available to the container. + +Default is 512 MB. Use 0 MB for unlimited memory. + +</div> + +<div class="cfgcmd"> + +set container name \<name\> device \<devicename\> source \<path\> + +</div> + +<div class="cfgcmd"> + +set container name \<name\> device \<devicename\> destination \<path\> + +Add a host device to the container. + +</div> + +<div class="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 + +</div> + +<div class="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) + +</div> + +<div class="cfgcmd"> + +set container name \<name\> label \<label\> value \<value\> + +Add metadata label for this container. + +</div> + +<div class="cfgcmd"> + +set container name \<name\> disable + +Disable a container. + +</div> + +### Container Networks + +<div class="cfgcmd"> + +set container network \<name\> + +Creates a named container network + +</div> + +<div class="cfgcmd"> + +set container network \<name\> description + +A brief description what this network is all about. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set container network \<name\> vrf \<name\> + +Bind container network to a given VRF instance. + +</div> + +### Container Registry + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set container registry \<name\> disable + +Disable a given container registry + +</div> + +<div class="cfgcmd"> + +set container registry \<name\> authentication username + +</div> + +<div class="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. + +</div> + +## Operation Commands + +<div class="opcmd"> + +add container image \<containername\> + +Pull a new image for container + +</div> + +<div class="opcmd"> + +show container + +Show the list of all active containers. + +</div> + +<div class="opcmd"> + +show container image + +Show the local container images. + +</div> + +<div class="opcmd"> + +show container log \<containername\> + +Show logs from a given container + +</div> + +<div class="opcmd"> + +show container network + +Show a list available container networks + +</div> + +<div class="opcmd"> + +restart container \<containername\> + +Restart a given container + +</div> + +<div class="opcmd"> + +update container image \<containername\> + +Update container image + +</div> + +<div class="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 <span class="title-ref">force</span> option to pass down to +the container image to also remove those images. + +</div> + +## 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..fad81412 --- /dev/null +++ b/docs/configuration/firewall/md-bridge.md @@ -0,0 +1,683 @@ +lastproofread +2023-11-08 + +# Bridge Firewall Configuration + +<div class="note"> + +<div class="title"> + +Note + +</div> + +**Documentation under development** + +</div> + +## 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: + +<div class="cfgcmd"> + +set firewall bridge ... + +</div> + +From main structure defined in `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> +<img src="/_static/images/firewall-bridge-packet-flow.webp" /> +</figure> + +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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +**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**. + +</div> + +## 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. + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> action +\[accept | continue | drop | jump | queue | return\] + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +jump-target \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> rule \<1-999999\> +jump-target \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +queue \<0-65535\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +queue-options bypass + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +queue-options fanout + +</div> + +<div class="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. + +</div> + +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**. + +<div class="cfgcmd"> + +set firewall bridge forward filter default-action +\[accept | drop\] + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +**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**. + +</div> + +### Firewall Logs + +Logging can be enable for every single firewall rule. If enabled, other +log options can be defined. + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> log + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter default-log + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> default-log + +Use this command to enable the logging of the default action on +the specified chain. + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +log-options level \[emerg | alert | crit | err | warn | notice +| info | debug\] + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +log-options group \<0-65535\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +log-options snapshot-length \<0-9000\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +log-options queue-threshold \<0-65535\> + +</div> + +<div class="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. + +</div> + +### Firewall Description + +For reference, a description can be defined for every defined custom chain. + +<div class="cfgcmd"> + +set firewall bridge name \<name\> description \<text\> + +Provide a rule-set description to a custom firewall chain. + +</div> + +### 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. + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> disable + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> rule \<1-999999\> disable + +Command for disabling a rule but keep it in the configuration. + +</div> + +### Matching criteria + +There are a lot of matching criteria against which the packet can be tested. + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +destination mac-address \<mac-address\> + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> rule \<1-999999\> +destination mac-address \<mac-address\> + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +source mac-address \<mac-address\> + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> rule \<1-999999\> +source mac-address \<mac-address\> + +Match criteria based on source and/or destination mac-address. + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +inbound-interface name \<iface\> + +</div> + +<div class="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` + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +inbound-interface group \<iface_group\> + +</div> + +<div class="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` + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +outbound-interface name \<iface\> + +</div> + +<div class="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` + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +outbound-interface group \<iface_group\> + +</div> + +<div class="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` + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +vlan id \<0-4096\> + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> rule \<1-999999\> +vlan id \<0-4096\> + +Match based on vlan ID. Range is also supported. + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +vlan priority \<0-7\> + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> rule \<1-999999\> +vlan priority \<0-7\> + +Match based on vlan priority(pcp). Range is also supported. + +</div> + +## 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: + +<div class="opcmd"> + +show firewall + +</div> + +<div class="opcmd"> + +show firewall summary + +</div> + +<div class="opcmd"> + +show firewall statistics + +</div> + +And, to print only bridge firewall information: + +<div class="opcmd"> + +show firewall bridge + +</div> + +<div class="opcmd"> + +show firewall bridge forward filter + +</div> + +<div class="opcmd"> + +show firewall bridge forward filter rule \<rule\> + +</div> + +<div class="opcmd"> + +show firewall bridge name \<name\> + +</div> + +<div class="opcmd"> + +show firewall bridge name \<name\> rule \<rule\> + +</div> + +### Show Firewall log + +<div class="opcmd"> + +show log firewall + +</div> + +<div class="opcmd"> + +show log firewall bridge + +</div> + +<div class="opcmd"> + +show log firewall bridge forward + +</div> + +<div class="opcmd"> + +show log firewall bridge forward filter + +</div> + +<div class="opcmd"> + +show log firewall bridge name \<name\> + +</div> + +<div class="opcmd"> + +show log firewall bridge forward filter rule \<rule\> + +</div> + +<div class="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. + +</div> + +### 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..e423eb59 --- /dev/null +++ b/docs/configuration/firewall/md-flowtables.md @@ -0,0 +1,229 @@ +lastproofread +2024-06-20 + +# Flowtables Firewall Configuration + +<div class="note"> + +<div class="title"> + +Note + +</div> + +**Documentation under development** + +</div> + +## Overview + +In this section there's useful information of all firewall configuration that +can be done regarding flowtables. + +<div class="cfgcmd"> + +set firewall flowtables ... + +</div> + +From main structure defined in +`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> +<img src="/_static/images/firewall-flowtable-packet-flow.webp" /> +</figure> + +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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +**Flowtable Reference:** +<https://docs.kernel.org/networking/nf_flowtable.html> + +</div> + +## 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: + +<div class="cfgcmd"> + +set firewall flowtable \<flow_table_name\> interface \<iface\> + +Define interfaces to be used in the flowtable. + +</div> + +<div class="cfgcmd"> + +set firewall flowtable \<flow_table_name\> description \<text\> + +</div> + +Provide a description to the flow table. + +<div class="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. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +**Hardware offload:** should be supported by the NICs used. + +</div> + +Creating rules for using flow tables: + +<div class="cfgcmd"> + +set firewall \[ipv4 | ipv6\] forward filter rule \<1-999999\> +action offload + +Create firewall rule in forward chain, and set action to `offload`. + +</div> + +<div class="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`. + +</div> + +## 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..dc860894 --- /dev/null +++ b/docs/configuration/firewall/md-global-options.md @@ -0,0 +1,236 @@ +lastproofread +2023-12-26 + +# 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: + +<div class="cfgcmd"> + +set firewall global-options ... + +</div> + +## Configuration + +<div class="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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +**firewall global-options all-ping** affects only to LOCAL +and it always behaves in the most restrictive way + +</div> + +``` 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. + +``` 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. + +</div> + +<div class="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` + +</div> + +<div class="cfgcmd"> + +set firewall global-options ip-src-route \[enable | disable\] + +</div> + +<div class="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` + +</div> + +<div class="cfgcmd"> + +set firewall global-options receive-redirects \[enable | disable\] + +</div> + +<div class="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` + +</div> + +<div class="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` + +</div> + +<div class="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` + +</div> + +<div class="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` + +</div> + +<div class="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` + +</div> + +<div class="cfgcmd"> + +set firewall global-options twa-hazards-protection +\[enable | disable\] + +Enable or Disable VyOS to be `1337` conform. +The following system parameter will be altered: + +- `net.ipv4.tcp_rfc1337` + +</div> + +<div class="cfgcmd"> + +set firewall global-options state-policy established action +\[accept | drop | reject\] + +</div> + +<div class="cfgcmd"> + +set firewall global-options state-policy established log + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall global-options state-policy invalid action +\[accept | drop | reject\] + +</div> + +<div class="cfgcmd"> + +set firewall global-options state-policy invalid log + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall global-options state-policy related action +\[accept | drop | reject\] + +</div> + +<div class="cfgcmd"> + +set firewall global-options state-policy related log + +</div> + +<div class="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. + +</div> diff --git a/docs/configuration/firewall/md-groups.md b/docs/configuration/firewall/md-groups.md new file mode 100644 index 00000000..926b503d --- /dev/null +++ b/docs/configuration/firewall/md-groups.md @@ -0,0 +1,561 @@ +lastproofread +2023-11-08 + +# 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. + +<div class="cfgcmd"> + +set firewall group address-group \<name\> address \[address | +address range\] + +</div> + +<div class="cfgcmd"> + +set firewall group ipv6-address-group \<name\> address \<address\> + +Define a IPv4 or a IPv6 address group + +``` 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 +``` + +</div> + +<div class="cfgcmd"> + +set firewall group address-group \<name\> description \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall group ipv6-address-group \<name\> description \<text\> + +Provide a IPv4 or IPv6 address group description + +</div> + +### 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. + +<div class="cfgcmd"> + +set firewall group network-group \<name\> network \<CIDR\> + +</div> + +<div class="cfgcmd"> + +set firewall group ipv6-network-group \<name\> network \<CIDR\> + +Define a IPv4 or IPv6 Network group. + +``` 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 +``` + +</div> + +<div class="cfgcmd"> + +set firewall group network-group \<name\> description \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall group ipv6-network-group \<name\> description \<text\> + +Provide an IPv4 or IPv6 network group description. + +</div> + +### Interface Groups + +An **interface group** represents a collection of interfaces. + +<div class="cfgcmd"> + +set firewall group interface-group \<name\> interface \<text\> + +Define an interface group. Wildcard are accepted too. + +</div> + +``` none +set firewall group interface-group LAN interface bond1001 +set firewall group interface-group LAN interface eth3* +``` + +<div class="cfgcmd"> + +set firewall group interface-group \<name\> description \<text\> + +Provide an interface group description + +</div> + +### 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 +<span class="title-ref">-</span>. + +<div class="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 + +``` 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 +``` + +</div> + +<div class="cfgcmd"> + +set firewall group port-group \<name\> description \<text\> + +Provide a port group description. + +</div> + +### MAC Groups + +A **mac group** represents a collection of mac addresses. + +<div class="cfgcmd"> + +set firewall group mac-group \<name\> mac-address \<mac-address\> + +Define a mac group. + +</div> + +``` 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 +``` + +<div class="cfgcmd"> + +set firewall group mac-group \<name\> description \<text\> + +Provide a mac group description. + +</div> + +### Domain Groups + +A **domain group** represents a collection of domains. + +<div class="cfgcmd"> + +set firewall group domain-group \<name\> address \<domain\> + +Define a domain group. + +</div> + +``` none +set firewall group domain-group DOM address example.com +``` + +<div class="cfgcmd"> + +set firewall group domain-group \<name\> description \<text\> + +Provide a domain group description. + +</div> + +### 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: + +<div class="cfgcmd"> + +set firewall group dynamic-group address-group \<name\> + +</div> + +<div class="cfgcmd"> + +set firewall group dynamic-group ipv6-address-group \<name\> + +</div> + +Add description to firewall groups: + +<div class="cfgcmd"> + +set firewall group dynamic-group address-group \<name\> +description \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall group dynamic-group ipv6-address-group \<name\> +description \<text\> + +</div> + +#### 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: + +<div class="cfgcmd"> + +set firewall ipv4 \[forward | input | output\] filter rule +\<1-999999\> add-address-to-group destination-address address-group \<name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> add-address-to-group +destination-address address-group \<name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 \[forward | input | output\] filter rule +\<1-999999\> add-address-to-group destination-address address-group \<name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> add-address-to-group +destination-address address-group \<name\> + +</div> + +- Add source IP address of the connection to a dynamic address group: + +<div class="cfgcmd"> + +set firewall ipv4 \[forward | input | output\] filter rule +\<1-999999\> add-address-to-group source-address address-group \<name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> add-address-to-group +source-address address-group \<name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 \[forward | input | output\] filter rule +\<1-999999\> add-address-to-group source-address address-group \<name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> add-address-to-group +source-address address-group \<name\> + +</div> + +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. + +<div class="cfgcmd"> + +set firewall ipv4 \[forward | input | output\] filter rule +\<1-999999\> add-address-to-group \[destination-address | source-address\] +timeout \<timeout\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> add-address-to-group +\[destination-address | source-address\] timeout \<timeout\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 \[forward | input | output\] filter rule +\<1-999999\> add-address-to-group \[destination-address | source-address\] +timeout \<timeout\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> add-address-to-group +\[destination-address | source-address\] timeout \<timeout\> + +</div> + +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 + +<div class="opcmd"> + +show firewall group + +</div> + +<div class="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). + +</div> + +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..a7511536 --- /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> +<img src="/_static/images/firewall-gral-packet-flow.webp" /> +</figure> + +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] source...`. + +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: + +<div class="toctree" maxdepth="1" includehidden=""> + +global-options +groups +bridge +ipv4 +ipv6 +flowtables + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +**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) + +</div> + +## Zone-based firewall + +<div class="toctree" maxdepth="1" includehidden=""> + +zone + +</div> + +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 +`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> +<img src="/_static/images/firewall-zonebased.webp" /> +</figure> diff --git a/docs/configuration/firewall/md-ipv4.md b/docs/configuration/firewall/md-ipv4.md new file mode 100644 index 00000000..7ac0ff49 --- /dev/null +++ b/docs/configuration/firewall/md-ipv4.md @@ -0,0 +1,2657 @@ +lastproofread +2023-11-08 + +# 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: + +<div class="cfgcmd"> + +set firewall ipv4 ... + +</div> + +From main structure defined in +`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> +<img src="/_static/images/firewall-fwd-packet-flow.webp" /> +</figure> + +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> +<img src="/_static/images/firewall-input-packet-flow.webp" /> +</figure> + +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 ...` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +**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** + +</div> + +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. + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> action +\[accept | continue | drop | jump | queue | reject | return | synproxy\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> action +\[accept | continue | drop | jump | queue | reject | return | synproxy\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> action +\[accept | continue | drop | jump | queue | reject | return\] + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +jump-target \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +jump-target \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +jump-target \<text\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +queue \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +queue \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +queue \<0-65535\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +queue-options bypass + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +queue-options bypass + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +queue-options bypass + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +queue-options fanout + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +queue-options fanout + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +queue-options fanout + +</div> + +<div class="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. + +</div> + +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**. + +<div class="cfgcmd"> + +set firewall ipv4 forward filter default-action +\[accept | drop\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter default-action +\[accept | drop\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter default-action +\[accept | drop\] + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +**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**. + +</div> + +### Firewall Logs + +Logging can be enable for every single firewall rule. If enabled, other +log options can be defined. + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> log + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> log + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> log + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter default-log + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter default-log + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter default-log + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> default-log + +Use this command to enable the logging of the default action on +the specified chain. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +log-options level \[emerg | alert | crit | err | warn | notice +| info | debug\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +log-options level \[emerg | alert | crit | err | warn | notice +| info | debug\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +log-options level \[emerg | alert | crit | err | warn | notice +| info | debug\] + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +log-options group \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +log-options group \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +log-options group \<0-65535\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +log-options snapshot-length \<0-9000\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +log-options snapshot-length \<0-9000\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +log-options snapshot-length \<0-9000\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +log-options queue-threshold \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +log-options queue-threshold \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +log-options queue-threshold \<0-65535\> + +</div> + +<div class="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. + +</div> + +### Firewall Description + +For reference, a description can be defined for every single rule, and for +every defined custom chain. + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> description \<text\> + +Provide a rule-set description to a custom firewall chain. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +description \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +description \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +description \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> description \<text\> + +Provide a description for each rule. + +</div> + +### 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. + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> disable + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> disable + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> disable + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> disable + +Command for disabling a rule but keep it in the configuration. + +</div> + +### Matching criteria + +There are a lot of matching criteria against which the packet can be tested. + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +connection-status nat \[destination | source\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +connection-status nat \[destination | source\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +connection-status nat \[destination | source\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +connection-status nat \[destination | source\] + +Match criteria based on nat connection status. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +connection-mark \<1-2147483647\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +connection-mark \<1-2147483647\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +connection-mark \<1-2147483647\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +connection-mark \<1-2147483647\> + +Match criteria based on connection mark. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +source address \[address | addressrange | CIDR\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +source address \[address | addressrange | CIDR\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +source address \[address | addressrange | CIDR\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +source address \[address | addressrange | CIDR\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +destination address \[address | addressrange | CIDR\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +destination address \[address | addressrange | CIDR\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +destination address \[address | addressrange | CIDR\] + +</div> + +<div class="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. + +``` 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 name FOO rule 51 source address !203.0.113.0/24 +``` + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +source address-mask \[address\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +source address-mask \[address\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +source address-mask \[address\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +source address-mask \[address\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +destination address-mask \[address\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +destination address-mask \[address\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +destination address-mask \[address\] + +</div> + +<div class="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. + +``` 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 +``` + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +source fqdn \<fqdn\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +source fqdn \<fqdn\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +source fqdn \<fqdn\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +source fqdn \<fqdn\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +destination fqdn \<fqdn\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +destination fqdn \<fqdn\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +destination fqdn \<fqdn\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +source geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +source geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +source geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +source geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +destination geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +destination geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +destination geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +destination geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +source geoip inverse-match + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +source geoip inverse-match + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +source geoip inverse-match + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +source geoip inverse-match + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +destination geoip inverse-match + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +destination geoip inverse-match + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +destination geoip inverse-match + +</div> + +<div class="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. + +</div> + +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. + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +source mac-address \<mac-address\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +source mac-address \<mac-address\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +source mac-address \<mac-address\> + +</div> + +<div class="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. + +``` 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 +``` + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +source port \[1-65535 | portname | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +source port \[1-65535 | portname | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +source port \[1-65535 | portname | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +source port \[1-65535 | portname | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +destination port \[1-65535 | portname | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +destination port \[1-65535 | portname | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +destination port \[1-65535 | portname | start-end\] + +</div> + +<div class="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`. + +``` 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: + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +source group address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +source group address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +source group address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +source group address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +destination group address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +destination group address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +destination group address-group \<name | !name\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +source group dynamic-address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +source group dynamic-address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +source group dynamic-address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +source group dynamic-address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +destination group dynamic-address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +destination group dynamic-address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +destination group dynamic-address-group \<name | !name\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +source group network-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +source group network-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +source group network-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +source group network-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +destination group network-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +destination group network-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +destination group network-group \<name | !name\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +source group port-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +source group port-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +source group port-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +source group port-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +destination group port-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +destination group port-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +destination group port-group \<name | !name\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +source group domain-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +source group domain-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +source group domain-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +source group domain-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +destination group domain-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +destination group domain-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +destination group domain-group \<name | !name\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +source group mac-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +source group mac-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +source group mac-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +source group mac-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +destination group mac-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +destination group mac-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +destination group mac-group \<name | !name\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +dscp \[0-63 | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +dscp \[0-63 | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +dscp \[0-63 | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +dscp \[0-63 | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +dscp-exclude \[0-63 | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +dscp-exclude \[0-63 | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +dscp-exclude \[0-63 | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +dscp-exclude \[0-63 | start-end\] + +Match based on dscp value. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +fragment \[match-frag | match-non-frag\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +fragment \[match-frag | match-non-frag\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +fragment \[match-frag | match-non-frag\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +fragment \[match-frag | match-non-frag\] + +Match based on fragment criteria. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +icmp \[code | type\] \<0-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +icmp \[code | type\] \<0-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +icmp \[code | type\] \<0-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +icmp \[code | type\] \<0-255\> + +Match based on icmp code and type. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +icmp type-name \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +icmp type-name \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +icmp type-name \<text\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +inbound-interface name \<iface\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +inbound-interface name \<iface\> + +</div> + +<div class="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` + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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` + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +inbound-interface group \<iface_group\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +inbound-interface group \<iface_group\> + +</div> + +<div class="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` + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +outbound-interface name \<iface\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +outbound-interface name \<iface\> + +</div> + +<div class="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` + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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` + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +outbound-interface group \<iface_group\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +outbound-interface group \<iface_group\> + +</div> + +<div class="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` + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +ipsec \[match-ipsec | match-none\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +ipsec \[match-ipsec | match-none\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +ipsec \[match-ipsec | match-none\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +ipsec \[match-ipsec | match-none\] + +Match based on ipsec criteria. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +limit burst \<0-4294967295\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +limit burst \<0-4294967295\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +limit burst \<0-4294967295\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +limit rate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +limit rate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +limit rate \<text\> + +</div> + +<div class="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** + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +packet-length \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +packet-length \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +packet-length \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +packet-length \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +packet-length-exclude \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +packet-length-exclude \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +packet-length-exclude \<text\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +packet-type \[broadcast | host | multicast | other\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +packet-type \[broadcast | host | multicast | other\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +packet-type \[broadcast | host | multicast | other\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +packet-type \[broadcast | host | multicast | other\] + +Match based on packet type criteria. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +protocol \[\<text\> | \<0-255\> | all | tcp_udp\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +protocol \[\<text\> | \<0-255\> | all | tcp_udp\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +protocol \[\<text\> | \<0-255\> | all | tcp_udp\] + +</div> + +<div class="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. + +``` none +set firewall ipv4 forward fitler rule 10 protocol tcp_udp +set firewall ipv4 forward fitler rule 11 protocol !tcp_udp +``` + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +recent time \[second | minute | hour\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +recent time \[second | minute | hour\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +recent time \[second | minute | hour\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +recent time \[second | minute | hour\] + +Match bases on recently seen sources. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +tcp flags \[not\] \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +tcp flags \[not\] \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +tcp flags \[not\] \<text\> + +</div> + +<div class="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. + +``` 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' +``` + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +state \[established | invalid | new | related\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +state \[established | invalid | new | related\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +state \[established | invalid | new | related\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +state \[established | invalid | new | related\] + +Match against the state of a packet. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +time startdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +time startdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +time startdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +time startdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +time starttime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +time starttime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +time starttime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +time starttime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +time stopdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +time stopdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +time stopdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +time stopdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +time stoptime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +time stoptime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +time stoptime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +time stoptime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +time weekdays \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +time weekdays \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +time weekdays \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +time weekdays \<text\> + +Time to match the defined rule. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +ttl \<eq | gt | lt\> \<0-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +ttl \<eq | gt | lt\> \<0-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +ttl \<eq | gt | lt\> \<0-255\> + +</div> + +<div class="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'. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +recent time \<second | minute | hour\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +recent time \<second | minute | hour\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +recent time \<second | minute | hour\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +conntrack-helper \<module\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +conntrack-helper \<module\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +conntrack-helper \<module\> + +</div> + +<div class="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 <span class="title-ref">\<module\></span>. + +``` 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 +``` + +</div> + +## Synproxy + +Synproxy connections + +<div class="cfgcmd"> + +set firewall ipv4 \[input | forward\] filter rule \<1-999999\> +action synproxy + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 \[input | forward\] filter rule \<1-999999\> +protocol tcp + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 \[input | forward\] filter rule \<1-999999\> +synproxy tcp mss \<501-65535\> + +Set TCP-MSS (maximum segment size) for the connection + +</div> + +<div class="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 + +</div> + +### 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 + +<div class="opcmd"> + +show firewall + +This will show you a basic firewall overview, for all ruleset, and not +only for ipv4 + +``` 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:~$ +``` + +</div> + +<div class="opcmd"> + +show firewall summary + +This will show you a summary of rule-sets and groups + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show firewall ipv4 \[forward | input | output\] filter + +</div> + +<div class="opcmd"> + +show firewall ipv4 name \<name\> + +This command will give an overview of a single rule-set. + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show firewall ipv4 \[forward | input | output\] +filter rule \<1-999999\> + +</div> + +<div class="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. + +</div> + +``` 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:~$ +``` + +<div class="opcmd"> + +show firewall statistics + +This will show you a statistic of all rule-sets since the last boot. + +</div> + +### Show Firewall log + +<div class="opcmd"> + +show log firewall + +</div> + +<div class="opcmd"> + +show log firewall ipv4 + +</div> + +<div class="opcmd"> + +show log firewall ipv4 \[forward | input | output | name\] + +</div> + +<div class="opcmd"> + +show log firewall ipv4 \[forward | input | output\] filter + +</div> + +<div class="opcmd"> + +show log firewall ipv4 name \<name\> + +</div> + +<div class="opcmd"> + +show log firewall ipv4 \[forward | input | output\] filter rule \<rule\> + +</div> + +<div class="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. + +</div> + +### 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 + +<div class="opcmd"> + +update geoip + +Command used to update GeoIP database and firewall sets. + +</div> diff --git a/docs/configuration/firewall/md-ipv6.md b/docs/configuration/firewall/md-ipv6.md new file mode 100644 index 00000000..a6c2aabf --- /dev/null +++ b/docs/configuration/firewall/md-ipv6.md @@ -0,0 +1,2638 @@ +lastproofread +2023-11-08 + +# 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: + +<div class="cfgcmd"> + +set firewall ipv6 ... + +</div> + +From main structure defined in +`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> +<img src="/_static/images/firewall-fwd-packet-flow.webp" /> +</figure> + +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> +<img src="/_static/images/firewall-input-packet-flow.webp" /> +</figure> + +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 ...` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +**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** + +</div> + +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. + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> action +\[accept | continue | drop | jump | queue | reject | return | synproxy\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> action +\[accept | continue | drop | jump | queue | reject | return | synproxy\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> action +\[accept | continue | drop | jump | queue | reject | return\] + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +jump-target \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +jump-target \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +jump-target \<text\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +queue \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +queue \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +queue \<0-65535\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +queue-options bypass + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +queue-options bypass + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +queue-options bypass + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +queue-options fanout + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +queue-options fanout + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +queue-options fanout + +</div> + +<div class="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. + +</div> + +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**. + +<div class="cfgcmd"> + +set firewall ipv6 forward filter default-action +\[accept | drop\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter default-action +\[accept | drop\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter default-action +\[accept | drop\] + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +**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**. + +</div> + +### Firewall Logs + +Logging can be enable for every single firewall rule. If enabled, other +log options can be defined. + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> log + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> log + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> log + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter default-log + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter default-log + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter default-log + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> default-log + +Use this command to enable the logging of the default action on +the specified chain. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +log-options level \[emerg | alert | crit | err | warn | notice +| info | debug\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +log-options level \[emerg | alert | crit | err | warn | notice +| info | debug\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +log-options level \[emerg | alert | crit | err | warn | notice +| info | debug\] + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +log-options group \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +log-options group \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +log-options group \<0-65535\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +log-options snapshot-length \<0-9000\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +log-options snapshot-length \<0-9000\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +log-options snapshot-length \<0-9000\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +log-options queue-threshold \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +log-options queue-threshold \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +log-options queue-threshold \<0-65535\> + +</div> + +<div class="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. + +</div> + +### Firewall Description + +For reference, a description can be defined for every single rule, and for +every defined custom chain. + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> description \<text\> + +Provide a rule-set description to a custom firewall chain. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +description \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +description \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +description \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> description \<text\> + +Provide a description for each rule. + +</div> + +### 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. + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> disable + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> disable + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> disable + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> disable + +Command for disabling a rule but keep it in the configuration. + +</div> + +### Matching criteria + +There are a lot of matching criteria against which the packet can be tested. + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +connection-status nat \[destination | source\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +connection-status nat \[destination | source\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +connection-status nat \[destination | source\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +connection-status nat \[destination | source\] + +Match criteria based on nat connection status. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +connection-mark \<1-2147483647\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +connection-mark \<1-2147483647\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +connection-mark \<1-2147483647\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +connection-mark \<1-2147483647\> + +Match criteria based on connection mark. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +source address \[address | addressrange | CIDR\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +source address \[address | addressrange | CIDR\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +source address \[address | addressrange | CIDR\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +source address \[address | addressrange | CIDR\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +destination address \[address | addressrange | CIDR\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +destination address \[address | addressrange | CIDR\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +destination address \[address | addressrange | CIDR\] + +</div> + +<div class="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. + +``` none +set firewall ipv6 name FOO rule 100 source address 2001:db8::202 +``` + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +source address-mask \[address\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +source address-mask \[address\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +source address-mask \[address\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +source address-mask \[address\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +destination address-mask \[address\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +destination address-mask \[address\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +destination address-mask \[address\] + +</div> + +<div class="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. + +``` 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 +``` + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +source fqdn \<fqdn\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +source fqdn \<fqdn\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +source fqdn \<fqdn\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +source fqdn \<fqdn\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +destination fqdn \<fqdn\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +destination fqdn \<fqdn\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +destination fqdn \<fqdn\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +source geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +source geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +source geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +source geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +destination geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +destination geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +destination geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +destination geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +source geoip inverse-match + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +source geoip inverse-match + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +source geoip inverse-match + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +source geoip inverse-match + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +destination geoip inverse-match + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +destination geoip inverse-match + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +destination geoip inverse-match + +</div> + +<div class="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. + +</div> + +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. + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +source mac-address \<mac-address\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +source mac-address \<mac-address\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +source mac-address \<mac-address\> + +</div> + +<div class="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. + +``` 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 +``` + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +source port \[1-65535 | portname | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +source port \[1-65535 | portname | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +source port \[1-65535 | portname | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +source port \[1-65535 | portname | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +destination port \[1-65535 | portname | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +destination port \[1-65535 | portname | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +destination port \[1-65535 | portname | start-end\] + +</div> + +<div class="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`. + +``` 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: + +``` none +set firewall ipv6 forward filter rule 10 source port '!22,https,3333-3338' +``` + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +source group address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +source group address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +source group address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +source group address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +destination group address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +destination group address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +destination group address-group \<name | !name\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +source group dynamic-address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +source group dynamic-address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +source group dynamic-address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +source group dynamic-address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +destination group dynamic-address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +destination group dynamic-address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +destination group dynamic-address-group \<name | !name\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +source group network-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +source group network-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +source group network-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +source group network-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +destination group network-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +destination group network-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +destination group network-group \<name | !name\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +source group port-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +source group port-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +source group port-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +source group port-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +destination group port-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +destination group port-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +destination group port-group \<name | !name\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +source group domain-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +source group domain-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +source group domain-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +source group domain-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +destination group domain-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +destination group domain-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +destination group domain-group \<name | !name\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +source group mac-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +source group mac-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +source group mac-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +source group mac-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +destination group mac-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +destination group mac-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +destination group mac-group \<name | !name\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +dscp \[0-63 | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +dscp \[0-63 | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +dscp \[0-63 | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +dscp \[0-63 | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +dscp-exclude \[0-63 | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +dscp-exclude \[0-63 | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +dscp-exclude \[0-63 | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +dscp-exclude \[0-63 | start-end\] + +Match based on dscp value. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +fragment \[match-frag | match-non-frag\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +fragment \[match-frag | match-non-frag\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +fragment \[match-frag | match-non-frag\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +fragment \[match-frag | match-non-frag\] + +Match based on fragment criteria. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +icmpv6 \[code | type\] \<0-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +icmpv6 \[code | type\] \<0-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +icmpv6 \[code | type\] \<0-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +icmpv6 \[code | type\] \<0-255\> + +Match based on icmp|icmpv6 code and type. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +icmpv6 type-name \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +icmpv6 type-name \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +icmpv6 type-name \<text\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +inbound-interface name \<iface\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +inbound-interface name \<iface\> + +</div> + +<div class="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` + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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` + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +inbound-interface group \<iface_group\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +inbound-interface group \<iface_group\> + +</div> + +<div class="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` + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +outbound-interface name \<iface\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +outbound-interface name \<iface\> + +</div> + +<div class="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` + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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` + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +outbound-interface group \<iface_group\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +outbound-interface group \<iface_group\> + +</div> + +<div class="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` + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +ipsec \[match-ipsec | match-none\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +ipsec \[match-ipsec | match-none\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +ipsec \[match-ipsec | match-none\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +ipsec \[match-ipsec | match-none\] + +Match based on ipsec criteria. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +limit burst \<0-4294967295\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +limit burst \<0-4294967295\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +limit burst \<0-4294967295\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +limit rate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +limit rate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +limit rate \<text\> + +</div> + +<div class="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** + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +packet-length \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +packet-length \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +packet-length \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +packet-length \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +packet-length-exclude \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +packet-length-exclude \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +packet-length-exclude \<text\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +packet-type \[broadcast | host | multicast | other\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +packet-type \[broadcast | host | multicast | other\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +packet-type \[broadcast | host | multicast | other\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +packet-type \[broadcast | host | multicast | other\] + +Match based on packet type criteria. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +protocol \[\<text\> | \<0-255\> | all | tcp_udp\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +protocol \[\<text\> | \<0-255\> | all | tcp_udp\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +protocol \[\<text\> | \<0-255\> | all | tcp_udp\] + +</div> + +<div class="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. + +``` none +set firewall ipv6 input filter rule 10 protocol tcp +``` + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +recent time \[second | minute | hour\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +recent time \[second | minute | hour\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +recent time \[second | minute | hour\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +recent time \[second | minute | hour\] + +Match bases on recently seen sources. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +tcp flags \[not\] \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +tcp flags \[not\] \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +tcp flags \[not\] \<text\> + +</div> + +<div class="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. + +``` 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' +``` + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +state \[established | invalid | new | related\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +state \[established | invalid | new | related\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +state \[established | invalid | new | related\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +state \[established | invalid | new | related\] + +Match against the state of a packet. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +time startdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +time startdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +time startdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +time startdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +time starttime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +time starttime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +time starttime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +time starttime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +time stopdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +time stopdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +time stopdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +time stopdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +time stoptime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +time stoptime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +time stoptime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +time stoptime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +time weekdays \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +time weekdays \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +time weekdays \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +time weekdays \<text\> + +Time to match the defined rule. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +hop-limit \<eq | gt | lt\> \<0-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +hop-limit \<eq | gt | lt\> \<0-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +hop-limit \<eq | gt | lt\> \<0-255\> + +</div> + +<div class="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'. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +recent time \<second | minute | hour\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +recent time \<second | minute | hour\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +recent time \<second | minute | hour\> + +</div> + +<div class="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. + +</div> + +## Synproxy + +Synproxy connections + +<div class="cfgcmd"> + +set firewall ipv6 \[input | forward\] filter rule \<1-999999\> +action synproxy + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 \[input | forward\] filter rule \<1-999999\> +protocol tcp + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 \[input | forward\] filter rule \<1-999999\> +synproxy tcp mss \<501-65535\> + +Set TCP-MSS (maximum segment size) for the connection + +</div> + +<div class="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 + +</div> + +### 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 + +<div class="opcmd"> + +show firewall + +This will show you a basic firewall overview + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show firewall summary + +This will show you a summary of rule-sets and groups + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show firewall ipv6 \[forward | input | output\] filter + +</div> + +<div class="opcmd"> + +show firewall ipv6 ipv6-name \<name\> + +This command will give an overview of a single rule-set. + +``` 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:~$ +``` + +</div> + +<div class="opcmd"> + +show firewall ipv6 \[forward | input | output\] +filter rule \<1-999999\> + +</div> + +<div class="opcmd"> + +show firewall ipv6 name \<name\> rule \<1-999999\> + +</div> + +<div class="opcmd"> + +show firewall ipv6 ipv6-name \<name\> rule \<1-999999\> + +This command will give an overview of a rule in a single rule-set + +</div> + +<div class="opcmd"> + +show firewall group \<name\> + +Overview of defined groups. You see the type, the members, and where the +group is used. + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show firewall statistics + +This will show you a statistic of all rule-sets since the last boot. + +</div> + +### Show Firewall log + +<div class="opcmd"> + +show log firewall + +</div> + +<div class="opcmd"> + +show log firewall ipv6 + +</div> + +<div class="opcmd"> + +show log firewall ipv6 \[forward | input | output | name\] + +</div> + +<div class="opcmd"> + +show log firewall ipv6 \[forward | input | output\] filter + +</div> + +<div class="opcmd"> + +show log firewall ipv6 name \<name\> + +</div> + +<div class="opcmd"> + +show log firewall ipv6 \[forward | input | output\] filter rule \<rule\> + +</div> + +<div class="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. + +</div> + +### 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 + +<div class="opcmd"> + +update geoip + +Command used to update GeoIP database and firewall sets. + +</div> diff --git a/docs/configuration/firewall/md-zone.md b/docs/configuration/firewall/md-zone.md new file mode 100644 index 00000000..6eb27b6c --- /dev/null +++ b/docs/configuration/firewall/md-zone.md @@ -0,0 +1,209 @@ +lastproofread +2023-11-01 + +# Zone Based Firewall + +## Overview + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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 +`legacy firewall configuration </configuration/firewall/general-legacy>` +chapter. + +</div> + +In this section there's useful information of all firewall configuration that +is needed for zone-based firewall. +Configuration commands covered in this section: + +<div class="cfgcmd"> + +set firewall zone ... + +</div> + +From main structure defined in +`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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +In `T2199` the syntax of the zone configuration was changed. +The zone configuration moved from `zone-policy zone <name>` to `firewall zone <name>`. + +</div> + +## 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 `examples-zone-policy`. + +### Define a Zone + +To define a zone setup either one with interfaces or a local zone. + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set firewall zone \<name\> default-action \[drop | reject\] + +Change the default-action with this setting. + +</div> + +<div class="cfgcmd"> + +set firewall zone \<name\> description + +Set a meaningful description. + +</div> + +### 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\* + +<div class="cfgcmd"> + +set firewall zone \<Destination Zone\> from \<Source Zone\> +firewall name \<rule-set\> + +</div> + +<div class="cfgcmd"> + +set firewall zone \<name\> from \<name\> firewall name +\<rule-set\> + +</div> + +<div class="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. + +``` none +set firewall zone DMZ from LAN firewall name LANv4-to-DMZv4 +set firewall zone LAN from DMZ firewall name DMZv4-to-LANv4 +``` + +</div> + +## Operation-mode + +<div class="opcmd"> + +show firewall zone-policy + +This will show you a basic summary of zones configuration. + +``` 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:~$ +``` + +</div> + +<div class="opcmd"> + +show firewall zone-policy zone \<zone\> + +This will show you a basic summary of a particular zone. + +``` 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:~$ +``` + +</div> diff --git a/docs/configuration/highavailability/md-index.md b/docs/configuration/highavailability/md-index.md new file mode 100644 index 00000000..6d66603e --- /dev/null +++ b/docs/configuration/highavailability/md-index.md @@ -0,0 +1,525 @@ +lastproofread +2021-06-30 + +# 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 + } +} +``` + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +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. + +</div> + +## 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 +``` + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +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 <span class="title-ref">inbound-interface</span>. + +</div> + +## 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. + +<div class="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. + +</div> + +## 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. + +<div class="cfgcmd"> + +set high-availability vrrp global-parameters garp interval +\<0.000-1000\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set high-availability vrrp global-parameters garp master-delay \<1-255\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set high-availability vrrp global-parameters garp master-refresh +\<1-600\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set high-availability vrrp global-parameters garp +master-refresh-repeat \<1-600\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set high-availability vrrp global-parameters garp master-repeat +\<1-600\> + +</div> + +<div class="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. + +</div> + +## Version + +<div class="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. + +</div> + +## 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 `command-scripting` section. + +## Virtual-server + +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..837b61c5 --- /dev/null +++ b/docs/configuration/interfaces/md-bonding.md @@ -0,0 +1,731 @@ +lastproofread +2021-06-30 + +# 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 + +<div class="cmdinclude" var0="bonding" var1="bond0"> + +/\_include/interface-common-with-dhcp.txt + +</div> + +### Member Interfaces + +<div class="cfgcmd"> + +set interfaces bonding \<interface\> member interface \<member\> + +Enslave <span class="title-ref">\<member\></span> interface to bond <span class="title-ref">\<interface\></span>. + +</div> + +### Bond options + +<div class="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 `hash-policy` option, documented below. + + <div class="note"> + + <div class="title"> + + Note + + </div> + + 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. + + </div> + +- `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 `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 `hash-policy` + option, described below. + + This mode provides load balancing and fault tolerance. + +</div> + +<div class="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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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 + + ``` 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: + + ``` 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 + + ``` 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. + +</div> + +<div class="cfgcmd"> + +set interfaces bonding \<interface\> primary \<interface\> + +An <span class="title-ref">\<interface\></span> 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. + +</div> + +<div class="cfgcmd"> + +set interfaces bonding \<interface\> arp-monitor interval \<time\> + +Specifies the ARP link monitoring <span class="title-ref">\<time\></span> 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 +`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. + +</div> + +<div class="cfgcmd"> + +set interfaces bonding \<interface\> arp-monitor target \<address\> + +Specifies the IP addresses to use as ARP monitoring peers when +`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. + +</div> + +### VLAN + +<div class="cmdinclude" var0="bonding" var1="bond0"> + +/\_include/interface-vlan-8021q.txt + +</div> + +### Port Mirror (SPAN) + +<div class="cmdinclude" var0="bondinging" var1="bond1" var2="eth3"> + +../../\_include/interface-mirror.txt + +</div> + +#### 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 `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. + +<div class="cfgcmd"> + +set interfaces bonding \<interface\> evpn es-id \<\<1-16777215|10-byte ID\> + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cmdinclude" var0="bonding" var1="bond0"> + +/\_include/interface-evpn-uplink.txt + +</div> + +## 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 +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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 `show interfaces ethernet +eth0 physical | grep -i driver` + +</div> + +### 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> +<img src="/_static/images/vyos_arista_bond_lacp.webp" alt="VyOS Arista EOS setup" /> +</figure> + +**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 +> ! +> ``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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! + +</div> + +## Operation + +<div class="opcmd"> + +show interfaces bonding + +Show brief interface information. + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show interfaces bonding \<interface\> + +Show detailed information on given <span class="title-ref">\<interface\></span> + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show interfaces bonding \<interface\> detail + +Show detailed information about the underlaying physical links on given +bond <span class="title-ref">\<interface\></span>. + +``` 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 +``` + +</div> diff --git a/docs/configuration/interfaces/md-bridge.md b/docs/configuration/interfaces/md-bridge.md new file mode 100644 index 00000000..732ea8e9 --- /dev/null +++ b/docs/configuration/interfaces/md-bridge.md @@ -0,0 +1,405 @@ +lastproofread +2021-06-30 + +# 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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Spanning Tree Protocol is not enabled by default in VyOS. +`stp` can be easily enabled if needed. + +</div> + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="bridge" var1="br0"> + +/\_include/interface-common-with-dhcp.txt + +</div> + +### Member Interfaces + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> member interface \<member\> + +Assign <span class="title-ref">\<member\></span> interface to bridge <span class="title-ref">\<interface\></span>. A completion +helper will help you with all allowed interfaces which can be +bridged. This includes `ethernet-interface`, +`bond-interface`, `l2tpv3-interface`, `openvpn`, +`vxlan-interface`, `wireless-interface`, +`tunnel-interface` and `geneve-interface`. + +</div> + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> member interface \<member\> +priority \<priority\> + +Configure individual bridge port <span class="title-ref">\<priority\></span>. + +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. + +</div> + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> member interface \<member\> +cost \<cost\> + +Path <span class="title-ref">\<cost\></span> 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. + +</div> + +### Bridge Options + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> aging \<time\> + +MAC address aging <span class="title-ref">\<time</span>\> in seconds (default: 300). + +</div> + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> max-age \<time\> + +Bridge maximum aging <span class="title-ref">\<time\></span> 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. + +</div> + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> igmp querier + +Enable IGMP and MLD querier. + +</div> + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> igmp snooping + +Enable IGMP and MLD snooping. + +</div> + +#### STP Parameter + +`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. + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> stp + +Enable spanning tree protocol. STP is disabled by default. + +</div> + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> forwarding-delay \<delay\> + +Spanning Tree Protocol forwarding <span class="title-ref">\<delay\></span> 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. + +</div> + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> hello-time \<interval\> + +Spanning Tree Protocol hello advertisement <span class="title-ref">\<interval\></span> 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. + +</div> + +### VLAN + +#### Enable VLAN-Aware Bridge + +<div class="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 + +</div> + +<div class="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`. + +</div> + +#### VLAN Options + +<div class="note"> + +<div class="title"> + +Note + +</div> + +It is not valid to use the <span class="title-ref">vif 1</span> 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 + +</div> + +<div class="cmdinclude" var0="bridge" var1="br0"> + +/\_include/interface-vlan-8021q.txt + +</div> + +<div class="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 <span class="title-ref">eth0</span> member port to be native VLAN 2 + +``` none +set interfaces bridge br1 member interface eth0 native-vlan 2 +``` + +</div> + +<div class="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 <span class="title-ref">eth0</span> member port to be allowed VLAN 4 + +``` none +set interfaces bridge br1 member interface eth0 allowed-vlan 4 +``` + +Example: Set <span class="title-ref">eth0</span> member port to be allowed VLAN 6-8 + +``` none +set interfaces bridge br1 member interface eth0 allowed-vlan 6-8 +``` + +</div> + +### Port Mirror (SPAN) + +<div class="cmdinclude" var0="bridge" var1="br1" var2="eth3"> + +../../\_include/interface-mirror.txt + +</div> + +## Examples + +### Create a basic bridge + +Creating a bridge interface is very simple. In this example, we will +have: + +- A bridge named <span class="title-ref">br100</span> +- Member interfaces <span class="title-ref">eth1</span> and VLAN 10 on interface <span class="title-ref">eth2</span> +- 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 <span class="title-ref">br100</span> +- The member interface <span class="title-ref">eth1</span> is a trunk that allows VLAN 10 to pass +- VLAN 10 on member interface <span class="title-ref">eth2</span> (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 + +<div class="opcmd"> + +show bridge + +The <span class="title-ref">show bridge</span> operational command can be used to display +configured bridges: + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show bridge \<name\> fdb + +Show bridge <span class="title-ref">\<name\></span> fdb displays the current forwarding table: + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show bridge \<name\> mdb + +Show bridge <span class="title-ref">\<name\></span> mdb displays the current multicast group membership +table.The table is populated by IGMP and MLD snooping in the bridge driver +automatically. + +``` 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 +``` + +</div> + +> Show bridge Media Access Control (MAC) address table +> +> ``` 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..ec79579e --- /dev/null +++ b/docs/configuration/interfaces/md-dummy.md @@ -0,0 +1,110 @@ +lastproofread +2023-01-20 + +# Dummy + +The dummy interface is really a little exotic, but rather useful nevertheless. +Dummy interfaces are much like the `loopback-interface` interface, except +you can have as many as you want. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Dummy interfaces can be used as interfaces that always stay up (in +the same fashion to loopbacks in Cisco IOS), or for testing purposes. + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +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. + +</div> + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="dummy" var1="dum0"> + +/\_include/interface-address.txt + +</div> + +<div class="cmdinclude" var0="dummy" var1="dum0"> + +/\_include/interface-description.txt + +</div> + +<div class="cmdinclude" var0="dummy" var1="dum0"> + +/\_include/interface-disable.txt + +</div> + +<div class="cmdinclude" var0="dummy" var1="dum0"> + +/\_include/interface-vrf.txt + +</div> + +## Operation + +<div class="opcmd"> + +show interfaces dummy + +Show brief interface information. + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show interfaces dummy \<interface\> + +Show detailed information on given <span class="title-ref">\<interface\></span> + +``` 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 +``` + +</div> diff --git a/docs/configuration/interfaces/md-ethernet.md b/docs/configuration/interfaces/md-ethernet.md new file mode 100644 index 00000000..4b0ee7f5 --- /dev/null +++ b/docs/configuration/interfaces/md-ethernet.md @@ -0,0 +1,357 @@ +lastproofread +2023-01-20 + +# Ethernet + +This will be the most widely used interface on a router carrying traffic to the +real world. + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="ethernet" var1="eth0"> + +/\_include/interface-common-with-dhcp.txt + +</div> + +### Ethernet options + +<div class="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 <span class="title-ref">auto</span>. + +</div> + +<div class="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 <span class="title-ref">auto</span>. + +</div> + +<div class="cfgcmd"> + +set interface ethernet \<interface\> ring-buffer rx \<value\> + +</div> + +<div class="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: <span class="title-ref">ethtool -g \<interface\></span> + +</div> + +#### Offloading + +<div class="cfgcmd"> + +set interfaces ethernet \<interface\> offload \<gro | gso | lro | rps | +sg | tso\> + +Enable different types of hardware offloading on the given NIC. + +`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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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/> + +</div> + +`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. + +`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. + +`RPS (Receive Packet Steering)` is logically a software implementation +of `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) + +<div class="note"> + +<div class="title"> + +Note + +</div> + +In order to use TSO/LRO with VMXNET3 adapters, the SG offloading +option must also be enabled. + +</div> + +</div> + +#### Authentication (EAPoL) + +<div class="cmdinclude" var0="ethernet" var1="eth0"> + +/\_include/interface-eapol.txt + +</div> + +#### EVPN Multihoming + +Uplink/Core tracking. + +<div class="cmdinclude" var0="ethernet" var1="eth0"> + +/\_include/interface-evpn-uplink.txt + +</div> + +### VLAN + +#### Regular VLANs (802.1q) + +<div class="cmdinclude" var0="ethernet" var1="eth0"> + +/\_include/interface-vlan-8021q.txt + +</div> + +#### QinQ (802.1ad) + +<div class="cmdinclude" var0="ethernet" var1="eth0"> + +/\_include/interface-vlan-8021ad.txt + +</div> + +### Port Mirror (SPAN) + +<div class="cmdinclude" var0="ethernet" var1="eth1" var2="eth3"> + +../../\_include/interface-mirror.txt + +</div> + +## Operation + +<div class="opcmd"> + +show interfaces ethernet + +Show brief interface information. + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show interfaces ethernet \<interface\> + +Show detailed information on given <span class="title-ref">\<interface\></span> + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show interfaces ethernet \<interface\> physical + +Show information about physical <span class="title-ref">\<interface\></span> + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show interfaces ethernet \<interface\> physical offload + +Show available offloading functions on given <span class="title-ref">\<interface\></span> + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show interfaces ethernet \<interface\> transceiver + +Show transceiver information from plugin modules, e.g SFP+, QSFP + +``` 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 +``` + +</div> diff --git a/docs/configuration/interfaces/md-geneve.md b/docs/configuration/interfaces/md-geneve.md new file mode 100644 index 00000000..8bb145df --- /dev/null +++ b/docs/configuration/interfaces/md-geneve.md @@ -0,0 +1,102 @@ +lastproofread +2023-01-20 + +# GENEVE + +`GENEVE (Generic Network Virtualization Encapsulation)` supports all of +the capabilities of `VXLAN (Virtual Extensible LAN)`, `NVGRE +(Network Virtualization using Generic Routing Encapsulation)`, and `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 + +<div class="cmdinclude" var0="geneve" var1="gnv0"> + +/\_include/interface-address.txt + +</div> + +<div class="cmdinclude" var0="geneve" var1="gnv0"> + +/\_include/interface-description.txt + +</div> + +<div class="cmdinclude" var0="geneve" var1="gnv0"> + +/\_include/interface-disable.txt + +</div> + +<div class="cmdinclude" var0="geneve" var1="gnv0"> + +/\_include/interface-mac.txt + +</div> + +<div class="cmdinclude" var0="geneve" var1="gnv0"> + +/\_include/interface-mtu.txt + +</div> + +<div class="cmdinclude" var0="geneve" var1="gnv0"> + +/\_include/interface-ip.txt + +</div> + +<div class="cmdinclude" var0="geneve" var1="gnv0"> + +/\_include/interface-ipv6.txt + +</div> + +### GENEVE options + +<div class="cfgcmd"> + +set interfaces geneve gnv0 remote \<address\> + +Configure GENEVE tunnel far end/remote tunnel endpoint. + +</div> + +<div class="cfgcmd"> + +set interfaces geneve gnv0 vni \<vni\> + +`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. + +</div> diff --git a/docs/configuration/interfaces/md-index.md b/docs/configuration/interfaces/md-index.md new file mode 100644 index 00000000..5d66b2d0 --- /dev/null +++ b/docs/configuration/interfaces/md-index.md @@ -0,0 +1,25 @@ +# Interfaces + +<div class="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 + +</div> diff --git a/docs/configuration/interfaces/md-l2tpv3.md b/docs/configuration/interfaces/md-l2tpv3.md new file mode 100644 index 00000000..84e190f5 --- /dev/null +++ b/docs/configuration/interfaces/md-l2tpv3.md @@ -0,0 +1,206 @@ +lastproofread +2023-01-20 + +# L2TPv3 + +Layer 2 Tunnelling Protocol Version 3 is an IETF standard related to L2TP that +can be used as an alternative protocol to `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 `3931`. + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="l2tpv3" var1="l2tpeth0"> + +/\_include/interface-common-without-dhcp.txt + +</div> + +### L2TPv3 options + +<div class="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 + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +## 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..1d8d6766 --- /dev/null +++ b/docs/configuration/interfaces/md-loopback.md @@ -0,0 +1,97 @@ +lastproofread +2023-01-20 + +# 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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +There can only be one loopback `lo` interface on the system. If +you need multiple interfaces, please use the `dummy-interface` +interface type. + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +A loopback interface is always up, thus it could be used for +management traffic or as source/destination for and `IGP (Interior +Gateway Protocol)` like `routing-bgp` so your internal BGP link is not +dependent on physical link states and multiple routes can be chosen to the +destination. A `dummy-interface` Interface should always be preferred +over a `loopback-interface` interface. + +</div> + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="loopback" var1="lo"> + +/\_include/interface-address.txt + +</div> + +<div class="cmdinclude" var0="loopback" var1="lo"> + +/\_include/interface-description.txt + +</div> + +## Operation + +<div class="opcmd"> + +show interfaces loopback + +Show brief interface information. + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show interfaces loopback lo + +Show detailed information on the given loopback interface <span class="title-ref">lo</span>. + +``` 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 +``` + +</div> diff --git a/docs/configuration/interfaces/md-macsec.md b/docs/configuration/interfaces/md-macsec.md new file mode 100644 index 00000000..17dfff1c --- /dev/null +++ b/docs/configuration/interfaces/md-macsec.md @@ -0,0 +1,332 @@ +lastproofread +2023-01-20 + +# 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 + +<div class="cmdinclude" var0="macsec" var1="macsec0"> + +/\_include/interface-common-with-dhcp.txt + +</div> + +### MACsec options + +<div class="cfgcmd"> + +set interfaces macsec \<interface\> security cipher \<gcm-aes-128|gcm-aes-256\> + +Select cipher suite used for cryptographic operations. This setting is +mandatory. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +#### Static Keys + +Static `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. + +<div class="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). + +</div> + +<div class="cfgcmd"> + +set interfaces macsec \<interface\> security static peer \<peer\> mac \<mac address\> + +Set the peer's MAC address + +</div> + +<div class="cfgcmd"> + +set interfaces macsec \<interface\> security static peer \<peer\> key \<key\> + +Set the peer's key used to receive (RX) traffic + +</div> + +<div class="cfgcmd"> + +set interfaces macsec \<interface\> security static peer \<peer\> disable + +Disable the peer configuration + +</div> + +#### Key Management + +`MKA (MACsec Key Agreement protocol)` is used to synchronize keys between +individual peers. + +<div class="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 `CAK (MACsec connectivity association key)` and +`CKN (MACsec connectivity association name)` pair. + +</div> + +<div class="cfgcmd"> + +set interfaces macsec \<interface\> security mka ckn \<key\> + +`CKN (MACsec connectivity association name)` key + +</div> + +<div class="cfgcmd"> + +set interfaces macsec \<interface\> security mka priority \<priority\> + +The peer with lower priority will become the key server and start +distributing SAKs. + +</div> + +#### Replay protection + +<div class="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 + +</div> + +## Operation + +<div class="opcmd"> + +run generate macsec mka cak \<gcm-aes-128|gcm-aes-256\> + +Generate `MKA (MACsec Key Agreement protocol)` CAK key 128 or 256 bits. + +``` none +vyos@vyos:~$ generate macsec mka cak gcm-aes-128 +20693b6e08bfa482703a563898c9e3ad +``` + +</div> + +<div class="opcmd"> + +run generate macsec mka ckn + +Generate `MKA (MACsec Key Agreement protocol)` CAK key. + +``` none +vyos@vyos:~$ generate macsec mka ckn +88737efef314ee319b2cbf30210a5f164957d884672c143aefdc0f5f6bc49eb2 +``` + +</div> + +<div class="opcmd"> + +show interfaces macsec + +List all MACsec interfaces. + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show interfaces macsec \<interface\> + +Show specific MACsec interface information + +``` 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 +``` + +</div> + +## 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..b9df5971 --- /dev/null +++ b/docs/configuration/interfaces/md-openvpn.md @@ -0,0 +1,924 @@ +lastproofread +2021-07-05 + +# 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 <span class="title-ref">set vpn</span> stanza, OpenVPN is configured as a network +interface using <span class="title-ref">set interfaces openvpn</span>. + +## Site-to-Site + +<figure> +<img src="/_static/images/openvpn_site2site_diagram.webp" /> +</figure> + +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 <span class="title-ref">local</span>, <span class="title-ref">in</span>, +and <span class="title-ref">out</span> 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 <span class="title-ref">show openvpn</span> 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 +`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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +``` 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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Clients are identified by the CN field of their x.509 certificates, +in this example the CN is `client0`: + +</div> + +``` 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. + +### 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 +``` + +#### 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 `issues_features`). + +If you are a hacker or want to try on your own we support passing raw OpenVPN +options to OpenVPN. + +<div class="cfgcmd"> + +set interfaces openvpn vtun10 openvpn-option 'persistent-key' + +</div> + +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. + +<div class="cfgcmd"> + +set interfaces openvpn vtun10 openvpn-option +'push \"keepalive 1 10\"' + +</div> + +Will add `push "keepalive 1 10"` to the generated OpenVPN config file. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +### 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 + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set interfaces openvpn \<interface\> server mfa totp digits \<1-65535\> + +Configure number of digits to use for totp hash (default: 6) + +</div> + +<div class="cfgcmd"> + +set interfaces openvpn \<interface\> server mfa totp drift \<1-65535\> + +Configure time drift in seconds (default: 0) + +</div> + +<div class="cfgcmd"> + +set interfaces openvpn \<interface\> server mfa totp slop \<1-65535\> + +Configure maximum allowed clock slop in seconds (default: 180) + +</div> + +<div class="cfgcmd"> + +set interfaces openvpn \<interface\> server mfa totp step \<1-65535\> + +Configure step value for totp in seconds (default: 30) + +</div> + +### 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: + +<div class="cfgcmd"> + +show interfaces openvpn \<interface\> user \<username\> mfa \<qrcode[|secret|](##SUBST##|secret|)uri\> + +</div> + +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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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> + +</div> + +### 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. + +<div class="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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Enable this feature causes an interface reset. + +</div> + +</div> + +### Troubleshooting + +VyOS provides some operational commands on OpenVPN. + +#### Check status + +The following commands let you check tunnel status. + +<div class="opcmd"> + +show openvpn client + +Use this command to check the tunnel status for OpenVPN client interfaces. + +</div> + +<div class="opcmd"> + +show openvpn server + +Use this command to check the tunnel status for OpenVPN server interfaces. + +</div> + +<div class="opcmd"> + +show openvpn site-to-site + +Use this command to check the tunnel status for OpenVPN site-to-site +interfaces. + +</div> + +#### Reset OpenVPN + +The following commands let you reset OpenVPN. + +<div class="opcmd"> + +reset openvpn client \<text\> + +Use this command to reset the specified OpenVPN client. + +</div> + +<div class="opcmd"> + +reset openvpn interface \<interface\> + +Use this command to reset the OpenVPN process on a specific interface. + +</div> diff --git a/docs/configuration/interfaces/md-pppoe.md b/docs/configuration/interfaces/md-pppoe.md new file mode 100644 index 00000000..f228aab2 --- /dev/null +++ b/docs/configuration/interfaces/md-pppoe.md @@ -0,0 +1,562 @@ +lastproofread +2022-07-27 + +# PPPoE + +`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 `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 `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. <span class="title-ref">eth0</span>, 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 + +<div class="cmdinclude" var0="pppoe" var1="pppoe0"> + +/\_include/interface-description.txt + +</div> + +<div class="cmdinclude" var0="pppoe" var1="pppoe0"> + +/\_include/interface-disable.txt + +</div> + +<div class="cmdinclude" var0="pppoe" var1="pppoe0"> + +/\_include/interface-mtu.txt + +</div> + +<div class="cmdinclude" var0="pppoe" var1="pppoe0"> + +/\_include/interface-vrf.txt + +</div> + +### PPPoE options + +<div class="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 <span class="title-ref">\<name\></span>. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> no-default-route + +Only request an address from the PPPoE server but do not install any default +route. + +Example: + +``` none +set interfaces pppoe pppoe0 no-default-route +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +This command got added in VyOS 1.4 and inverts the logic from the old +`default-route` CLI option. + +</div> + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> default-route-distance \<distance\> + +Set the distance for the default gateway sent by the PPPoE server. + +Example: + +``` none +set interfaces pppoe pppoe0 default-route-distance 220 +``` + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> mru \<mru\> + +Set the `MRU (Maximum Receive Unit)` to <span class="title-ref">mru</span>. PPPd will ask the peer to +send packets of no more than <span class="title-ref">mru</span> bytes. The value of <span class="title-ref">mru</span> 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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +When using the IPv6 protocol, MRU must be at least 1280 bytes. + +</div> + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> no-peer-dns + +Use this command to not install advertised DNS nameservers into the local +system. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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'. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +This command was introduced in VyOS 1.4 - it was previously called: +`set firewall options interface <name> adjust-mss <value>` + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting in +1452 bytes on a 1492 byte MTU. + +</div> + +Instead of a numerical MSS value <span class="title-ref">clamp-mss-to-pmtu</span> can be used to +automatically set the proper value. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> ip source-validation \<strict | loose | disable\> + +Enable policy for source validation by reversed path, as specified in +`3704`. Current recommended practice in `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 + +</div> + +#### IPv6 + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> ipv6 address autoconf + +Use this command to enable acquisition of IPv6 address using stateless +autoconfig (SLAAC). + +</div> + +<div class="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'. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +This command was introduced in VyOS 1.4 - it was previously called: +`set firewall options interface <name> adjust-mss <value>` + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +MSS value = MTU - 40 (IPv6 header) - 20 (TCP header), resulting in +1432 bytes on a 1492 byte MTU. + +</div> + +Instead of a numerical MSS value <span class="title-ref">clamp-mss-to-pmtu</span> can be used to +automatically set the proper value. + +</div> + +<div class="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. + +</div> + +<div class="cmdinclude" var0="pppoe" var1="pppoe0"> + +/\_include/interface-dhcpv6-prefix-delegation.txt + +</div> + +## Operation + +<div class="opcmd"> + +show interfaces pppoe \<interface\> + +Show detailed information on given <span class="title-ref">\<interface\></span> + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show interfaces pppoe \<interface\> queue + +Displays queue information for a PPPoE interface. + +``` 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 +``` + +</div> + +### Connect/Disconnect + +<div class="opcmd"> + +disconnect interface \<interface\> + +Test disconnecting given connection-oriented interface. <span class="title-ref">\<interface\></span> can be +`pppoe0` as the example. + +</div> + +<div class="opcmd"> + +connect interface \<interface\> + +Test connecting given connection-oriented interface. <span class="title-ref">\<interface\></span> can be +`pppoe0` as the example. + +</div> + +## 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 <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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Syntax has changed from VyOS 1.2 (crux) and it will be automatically +migrated during an upgrade. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +A default route is automatically installed once the interface is up. +To change this behavior use the `no-default-route` CLI option. + +</div> + +``` 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 `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..a58ccfc6 --- /dev/null +++ b/docs/configuration/interfaces/md-pseudo-ethernet.md @@ -0,0 +1,67 @@ +lastproofread +2023-01-26 + +# 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 + `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 + +<div class="cmdinclude" var0="pseudo-ethernet" var1="peth0"> + +/\_include/interface-common-with-dhcp.txt + +</div> + +### Pseudo Ethernet/MACVLAN options + +<div class="cfgcmd"> + +set interfaces pseudo-ethernet \<interface\> source-interface \<ethX\> + +Specifies the physical <span class="title-ref">\<ethX\></span> Ethernet interface associated with a Pseudo +Ethernet <span class="title-ref">\<interface\></span>. + +</div> + +### VLAN + +<div class="cmdinclude" var0="pseudo-ethernet" var1="peth0"> + +/\_include/interface-vlan-8021q.txt + +</div> diff --git a/docs/configuration/interfaces/md-sstp-client.md b/docs/configuration/interfaces/md-sstp-client.md new file mode 100644 index 00000000..d5c19d8f --- /dev/null +++ b/docs/configuration/interfaces/md-sstp-client.md @@ -0,0 +1,225 @@ +lastproofread +2022-12-11 + +# SSTP Client + +`SSTP (Secure Socket Tunneling Protocol)` is a form of `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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +VyOS also comes with a build in SSTP server, see `sstp`. + +</div> + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="sstpc" var1="sstpc0"> + +/\_include/interface-description.txt + +</div> + +<div class="cmdinclude" var0="sstpc" var1="sstpc0"> + +/\_include/interface-disable.txt + +</div> + +<div class="cmdinclude" var0="sstpc" var1="sstpc0"> + +/\_include/interface-mtu.txt + +</div> + +<div class="cmdinclude" var0="sstpc" var1="sstpc0"> + +/\_include/interface-vrf.txt + +</div> + +### SSTP Client Options + +<div class="cfgcmd"> + +set interfaces sstpc \<interface\> no-default-route + +Only request an address from the SSTP server but do not install any default +route. + +Example: + +``` none +set interfaces sstpc sstpc0 no-default-route +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +This command got added in VyOS 1.4 and inverts the logic from the old +`default-route` CLI option. + +</div> + +</div> + +<div class="cfgcmd"> + +set interfaces sstpc \<interface\> default-route-distance \<distance\> + +Set the distance for the default gateway sent by the SSTP server. + +Example: + +``` none +set interfaces sstpc sstpc0 default-route-distance 220 +``` + +</div> + +<div class="cfgcmd"> + +set interfaces sstpc \<interface\> no-peer-dns + +Use this command to not install advertised DNS nameservers into the local +system. + +</div> + +<div class="cfgcmd"> + +set interfaces sstpc \<interface\> server \<address\> + +SSTP remote server to connect to. Can be either an IP address or FQDN. + +</div> + +<div class="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'. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +This command was introduced in VyOS 1.4 - it was previously called: +`set firewall options interface <name> adjust-mss <value>` + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting in +1452 bytes on a 1492 byte MTU. + +</div> + +Instead of a numerical MSS value <span class="title-ref">clamp-mss-to-pmtu</span> can be used to +automatically set the proper value. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set interfaces sstpc \<interface\> ip source-validation \<strict | loose | disable\> + +Enable policy for source validation by reversed path, as specified in +`3704`. Current recommended practice in `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 + +</div> + +## Operation + +<div class="opcmd"> + +show interfaces sstpc \<interface\> + +Show detailed information on given <span class="title-ref">\<interface\></span> + +``` 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 +``` + +</div> + +### Connect/Disconnect + +<div class="opcmd"> + +disconnect interface \<interface\> + +Test disconnecting given connection-oriented interface. <span class="title-ref">\<interface\></span> can be +`sstpc0` as the example. + +</div> + +<div class="opcmd"> + +connect interface \<interface\> + +Test connecting given connection-oriented interface. <span class="title-ref">\<interface\></span> can be +`sstpc0` as the example. + +</div> diff --git a/docs/configuration/interfaces/md-tunnel.md b/docs/configuration/interfaces/md-tunnel.md new file mode 100644 index 00000000..53ba1a3e --- /dev/null +++ b/docs/configuration/interfaces/md-tunnel.md @@ -0,0 +1,283 @@ +lastproofread +2023-01-26 + +# 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 + +<div class="cmdinclude" var0="tunnel" var1="tun0"> + +/\_include/interface-address.txt + +</div> + +<div class="cmdinclude" var0="tunnel" var1="tun0"> + +/\_include/interface-common-without-mac.txt + +</div> + +## IPIP + +This is one of the simplest types of tunnels, as defined by `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](https://www.isc.org/othersoftware/)). + +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 +`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](https://tunnelbroker.net/). + +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 +`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 +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +There is also a GRE over IPv6 encapsulation available, it is +called: `ip6gre`. + +</div> diff --git a/docs/configuration/interfaces/md-virtual-ethernet.md b/docs/configuration/interfaces/md-virtual-ethernet.md new file mode 100644 index 00000000..2d3f4c63 --- /dev/null +++ b/docs/configuration/interfaces/md-virtual-ethernet.md @@ -0,0 +1,127 @@ +lastproofread +2022-11-25 + +# 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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +veth interfaces need to be created in pairs - it's called the peer name + +</div> + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="virtual-ethernet" var1="veth0"> + +/\_include/interface-address-with-dhcp.txt + +</div> + +<div class="cmdinclude" var0="virtual-ethernet" var1="veth0"> + +/\_include/interface-description.txt + +</div> + +### VLAN + +#### Regular VLANs (802.1q) + +<div class="cmdinclude" var0="virtual-ethernet" var1="veth0"> + +/\_include/interface-vlan-8021q.txt + +</div> + +#### QinQ (802.1ad) + +<div class="cmdinclude" var0="virtual-ethernet" var1="veth0"> + +/\_include/interface-vlan-8021ad.txt + +</div> + +<div class="cmdinclude" var0="virtual-ethernet" var1="veth0"> + +/\_include/interface-disable.txt + +</div> + +<div class="cmdinclude" var0="virtual-ethernet" var1="veth0"> + +/\_include/interface-vrf.txt + +</div> + +## Operation + +<div class="opcmd"> + +show interfaces virtual-ethernet + +Show brief interface information. + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show interfaces virtual-ethernet \<interface\> + +Show detailed information on given <span class="title-ref">\<interface\></span> + +``` 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 +``` + +</div> + +## 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..0d924f65 --- /dev/null +++ b/docs/configuration/interfaces/md-vti.md @@ -0,0 +1,46 @@ +# 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" +} +``` + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +When using site-to-site IPsec with VTI interfaces, +be sure to disable route autoinstall + +</div> + +``` 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..9a991c08 --- /dev/null +++ b/docs/configuration/interfaces/md-vxlan.md @@ -0,0 +1,396 @@ +lastproofread +2023-01-26 + +# VXLAN + +`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 `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 `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 + +<div class="cmdinclude" var0="vxlan" var1="vxlan0"> + +/\_include/interface-common-without-dhcp.txt + +</div> + +### VXLAN specific options + +<div class="cfgcmd"> + +set interfaces vxlan \<interface\> vni \<number\> + +Each VXLAN segment is identified through a 24-bit segment ID, termed the +`VNI (VXLAN Network Identifier (or VXLAN Segment ID))`, This allows +up to 16M VXLAN segments to coexist within the same administrative domain. + +</div> + +<div class="cfgcmd"> + +set interfaces vxlan \<interface\> port \<port\> + +Configure port number of remote VXLAN endpoint. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set interfaces vxlan \<interface\> gpe + +Enables the Generic Protocol extension (VXLAN-GPE). Currently, this is only +supported together with the external keyword. + +</div> + +<div class="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. + +</div> + +<div class="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 `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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The device can only receive packets with VNIs configured in +the VNI filtering table. + +</div> + +</div> + +#### Unicast + +<div class="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. + +</div> + +#### Multicast + +<div class="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. + +</div> + +<div class="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. + +</div> + +## 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 +`VNI (VXLAN Network Identifier (or VXLAN Segment ID))` is configured +against a container VXLAN interface which is referred to as a +`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. + +<div class="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. + +``` 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' +``` + +</div> + +### 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..4e2689f5 --- /dev/null +++ b/docs/configuration/interfaces/md-wireguard.md @@ -0,0 +1,480 @@ +lastproofread +2023-01-26 + +# 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> +<img src="/_static/images/wireguard_site2site_diagram.webp" /> +</figure> + +## 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 + +<div class="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. + +``` none +vyos@vyos:~$ generate pki wireguard key-pair +Private key: iJJyEARGK52Ls1GYRCcFvPuTj7WyWYDo//BknoDU0XY= +Public key: EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw= +``` + +</div> + +<div class="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`. + +``` 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=' +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If this command is invoked from configure mode with the `run` +prefix the key is automatically installed to the appropriate interface: + +``` 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= ++} +``` + +</div> + +</div> + +<div class="opcmd"> + +show interfaces wireguard \<interface\> public-key + +Retrieve public key portion from configured WIreGuard interface. + +``` none +vyos@vyos:~$ show interfaces wireguard wg01 public-key +EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw= +``` + +</div> + +#### Optional + +<div class="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. + +``` none +vyos@vyos:~$ generate pki wireguard preshared-key +Pre-shared key: OHH2EwZfMNK+1L6BXbYw3bKCtMrfjpR4mCAEeBlFnRs= +``` + +</div> + +<div class="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. + +``` 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= +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If this command is invoked from configure mode with the `run` +prefix the key is automatically installed to the appropriate interface: + +</div> + +</div> + +## 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 <span class="title-ref">to-wg02</span> is reachable at 192.0.2.1 + port 51820 +- The remote peer <span class="title-ref">to-wg02</span> 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 <span class="title-ref">wg01</span> + +``` 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 <span class="title-ref">wg01</span>. Multiple IPs or networks can be defined and +routed. The last check is allowed-ips which either prevents or allows the +traffic. + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +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](https://lists.zx2c4.com/pipermail/wireguard/2018-December/003704.html). + +</div> + +<div class="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 + +`generate pki wireguard key-pair`. + +``` none +set interfaces wireguard wg01 private-key 'iJJyEARGK52Ls1GYRCcFvPuTj7WyWYDo//BknoDU0XY=' +``` + +The command `show interfaces wireguard wg01 public-key` will then show the +public key, which needs to be shared with the peer. + +</div> + +<div class="cmdinclude" var0="wireguard" var1="wg01"> + +/\_include/interface-per-client-thread.txt + +</div> + +**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 + +<div class="opcmd"> + +show interfaces wireguard wg01 summary + +Show info about the Wireguard service. +It also shows the latest handshake. + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show interfaces wireguard + +Get a list of all wireguard interfaces + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show interfaces wireguard \<interface\> + +Show general information about specific WireGuard interface + +``` 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 +``` + +</div> + +## 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. + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +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. + +</div> + +<div class="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> +<img src="/_static/images/wireguard_qrcode.webp" alt="WireGuard Client QR code" /> +</figure> + +</div> diff --git a/docs/configuration/interfaces/md-wireless.md b/docs/configuration/interfaces/md-wireless.md new file mode 100644 index 00000000..4a09b78b --- /dev/null +++ b/docs/configuration/interfaces/md-wireless.md @@ -0,0 +1,823 @@ +lastproofread +2023-01-26 + +# WLAN/WIFI - Wireless LAN + +`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: + +- `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 + +<div class="cmdinclude" var0="wireless" var1="wlan0"> + +/\_include/interface-common-with-dhcp.txt + +</div> + +### Wireless options + +<div class="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 + +</div> + +<div class="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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +This option is mandatory in Access-Point mode. + +</div> + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> mgmt-frame-protection + +Management Frame Protection (MFP) according to IEEE 802.11w + +</div> + +<div class="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 + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> physical-device \<device\> + +Wireless hardware device used as underlay radio. + +This defaults to phy0. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> ssid \<ssid\> + +SSID to be used in IEEE 802.11 management frames + +</div> + +<div class="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 + +</div> + +<div class="cmdinclude" var0="wireless" var1="wlan0"> + +/\_include/interface-per-client-thread.txt + +</div> + +#### PPDU + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities require-ht + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities require-hvt + +</div> + +##### HT (High Throughput) capabilities (802.11n) + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht 40mhz-incapable + +Device is incapable of 40 MHz, do not advertise. This sets `[40-INTOLERANT]` + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht auto-powersave + +WMM-PS Unscheduled Automatic Power Save Delivery \[U-APSD\] + +</div> + +<div class="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 + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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! + +``` 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 +``` + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht +delayed-block-ack + +Enable HT-delayed Block Ack `[DELAYED-BA]` + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht dsss-cck-40 + +DSSS/CCK Mode in 40 MHz, this sets `[DSSS_CCK-40]` + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht greenfield + +This enables the greenfield option which sets the `[GF]` option + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht ldpc + +Enable LDPC coding capability + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht lsig-protection + +Enable L-SIG TXOP protection capability + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht max-amsdu +\<3839 | 7935\> + +Maximum A-MSDU length 3839 (default) or 7935 octets + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht +short-gi \<20 | 40\> + +Short GI capabilities for 20 and 40 MHz + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht +smps \<static | dynamic\> + +Spatial Multiplexing Power Save (SMPS) settings + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht stbc rx \<num\> + +Enable receiving PPDU using STBC (Space Time Block Coding) + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht stbc tx + +Enable sending PPDU using STBC (Space Time Block Coding) + +</div> + +##### VHT (Very High Throughput) capabilities (802.11ac) + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht antenna-count + +Number of antennas on this card + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht +antenna-pattern-fixed + +Set if antenna pattern does not change during the lifetime of an association + +</div> + +<div class="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 + +</div> + +<div class="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. + +</div> + +<div class="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 + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht ldpc + +Enable LDPC (Low Density Parity Check) coding capability + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht link-adaptation + +VHT link adaptation capabilities + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht +max-mpdu \<value\> + +Increase Maximum MPDU length to 7991 or 11454 octets (default 3895 octets) + +</div> + +<div class="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 + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht +short-gi \<80 | 160\> + +Short GI capabilities + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht stbc rx \<num\> + +Enable receiving PPDU using STBC (Space Time Block Coding) + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht stbc tx + +Enable sending PPDU using STBC (Space Time Block Coding) + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht tx-powersave + +Enable VHT TXOP Power Save Mode + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht vht-cf + +Station supports receiving VHT variant HT Control field + +</div> + +### 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 + +`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 `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) + +<div class="cmdinclude" var0="wireless" var1="wlan0"> + +/\_include/interface-vlan-8021q.txt + +</div> + +#### QinQ (802.1ad) + +<div class="cmdinclude" var0="wireless" var1="wlan0"> + +/\_include/interface-vlan-8021ad.txt + +</div> + +## Operation + +<div class="opcmd"> + +show interfaces wireless info + +</div> + +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 +``` + +<div class="opcmd"> + +show interfaces wireless detail + +</div> + +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 +``` + +<div class="opcmd"> + +show interfaces wireless \<wlanX\> + +</div> + +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 +``` + +<div class="opcmd"> + +show interfaces wireless \<wlanX\> brief + +</div> + +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 +``` + +<div class="opcmd"> + +show interfaces wireless \<wlanX\> queue + +</div> + +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 +``` + +<div class="opcmd"> + +show interfaces wireless \<wlanX\> scan + +</div> + +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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Scanning is not supported on all wireless drivers and wireless +hardware. Refer to your driver and wireless hardware documentation for +further details. + +</div> + +``` 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 `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 +(`bridge-interface`) on the system. + +### 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..2475e809 --- /dev/null +++ b/docs/configuration/interfaces/md-wwan.md @@ -0,0 +1,390 @@ +lastproofread +2023-01-27 + +# 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 <span class="title-ref">interfaces wwan</span> subsystem for configuration. + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-address-with-dhcp.txt + +</div> + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-description.txt + +</div> + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-disable.txt + +</div> + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-disable-link-detect.txt + +</div> + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-mtu.txt + +</div> + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-ip.txt + +</div> + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-ipv6.txt + +</div> + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-vrf.txt + +</div> + +**DHCP(v6)** + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-dhcp-options.txt + +</div> + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-dhcpv6-options.txt + +</div> + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-dhcpv6-prefix-delegation.txt + +</div> + +### WirelessModem (WWAN) options + +<div class="cfgcmd"> + +set interfaces wwan \<interface\> apn \<apn\> + +Every WWAN connection requires an `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. + +</div> + +## Operation + +<div class="opcmd"> + +show interfaces wwan \<interface\> + +Show detailed information on given <span class="title-ref">\<interface\></span> + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> summary + +Show detailed information summary on given <span class="title-ref">\<interface\></span> + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> capabilities + +Show WWAN module hardware capabilities. + +``` 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' +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> firmware + +Show WWAN module firmware. + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> imei + +Show WWAN module IMEI. + +``` none +vyos@vyos:~$ show interfaces wwan wwan0 imei +ESN: '0' +IMEI: '358xxxxxxxxxxxx' +MEID: 'unknown' +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> imsi + +Show WWAN module IMSI. + +``` none +vyos@vyos:~$ show interfaces wwan wwan0 imsi +IMSI: '262xxxxxxxxxxxx' +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> model + +Show WWAN module model. + +``` none +vyos@vyos:~$ show interfaces wwan wwan0 model +Model: 'MC7710' +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> msisdn + +Show WWAN module MSISDN. + +``` none +vyos@vyos:~$ show interfaces wwan wwan0 msisdn +MSISDN: '4917xxxxxxxx' +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> revision + +Show WWAN module hardware revision. + +``` none +vyos@vyos:~$ show interfaces wwan wwan0 revision +Revision: 'SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15' +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> signal + +Show WWAN module signal strength. + +``` 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' +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> sim + +Show WWAN module SIM card information. + +``` 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' +``` + +</div> + +## 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 `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 +`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 <span class="title-ref">qmi-firmware-update</span> 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..5526c11d --- /dev/null +++ b/docs/configuration/loadbalancing/md-index.md @@ -0,0 +1,8 @@ +# Load-balancing + +<div class="toctree" maxdepth="1" includehidden=""> + +wan +reverse-proxy + +</div> diff --git a/docs/configuration/loadbalancing/md-reverse-proxy.md b/docs/configuration/loadbalancing/md-reverse-proxy.md new file mode 100644 index 00000000..0e4ebe77 --- /dev/null +++ b/docs/configuration/loadbalancing/md-reverse-proxy.md @@ -0,0 +1,552 @@ +# Reverse-proxy + +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 + +<div class="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 + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy service \<name\> port +\<port\> + +Create service <span class="title-ref">\<name\></span> to listen on \<port\> + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy service \<name\> mode +\<tcp|http\> + +Configure service <span class="title-ref">\<name\></span> mode TCP or HTTP + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy service \<name\> backend +\<name\> + +Configure service <span class="title-ref">\<name\></span> to use the backend \<name\> + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy service \<name\> ssl +certificate \<name\> + +Set SSL certificate \<name\> for service \<name\> + +</div> + +<div class="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 + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy service \<name\> logging facility +\<facility\> level \<level\> + +Specify facility and level for logging. +For an explanation on `syslog_facilities` and `syslog_severity_level` +see tables in syslog configuration section. + +</div> + +#### 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. + +<div class="cfgcmd"> + +set load-balancing reverse-proxy service \<name\> rule \<rule\> +domain-name \<name\> + +Match domain name + +</div> + +<div class="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 + +</div> + +<div class="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 + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy service \<name\> rule \<rule\> +set backend \<name\> + +Assign a specific backend to a rule + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy service \<name\> rule \<rule\> +redirect-location \<url\> + +Redirect URL to a new location + +</div> + +### Backend + +<div class="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 + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy backend \<name\> mode +\<mode\> + +Configure backend <span class="title-ref">\<name\></span> mode TCP or HTTP + +</div> + +<div class="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 + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy backend \<name\> server +\<name\> port \<port\> + +Set the address of the backend port + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy backend \<name\> server +\<name\> check + +Active health check backend server + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy backend \<name\> server +\<name\> send-proxy + +Send a Proxy Protocol version 1 header (text format) + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy backend \<name\> server +\<name\> send-proxy-v2 + +Send a Proxy Protocol version 2 header (binary format) + +</div> + +<div class="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\> + +</div> + +<div class="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 + +</div> + +<div class="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 + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy backend \<name\> logging facility +\<facility\> level \<level\> + +Specify facility and level for logging. +For an explanation on `syslog_facilities` and `syslog_severity_level` +see tables in syslog configuration section. + +</div> + +### Global + +Global parameters + +<div class="cfgcmd"> + +set load-balancing reverse-proxy global-parameters max-connections +\<num\> + +Limit maximum number of connections + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy global-parameters ssl-bind-ciphers +\<ciphers\> + +Limit allowed cipher algorithms used during SSL/TLS handshake + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy global-parameters tls-version-min +\<version\> + +Specify the minimum required TLS version 1.2 or 1.3 + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy global-parameters logging +facility \<facility\> level \<level\> + +Specify facility and level for logging. +For an explanation on `syslog_facilities` and `syslog_severity_level` +see tables in syslog configuration section. + +</div> + +## Health checks + +### HTTP checks + +For web application providing information about their state HTTP health +checks can be used to determine their availability. + +<div class="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. + +</div> + +<div class="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 + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy backend \<name\> http-check +uri \<path\> + +Sets the endpoint to be used for health checks + +</div> + +<div class="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 <span class="title-ref">success</span> in the response body + +</div> + +### 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: + +<div class="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. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +## 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..f82c7e4b --- /dev/null +++ b/docs/configuration/loadbalancing/md-wan.md @@ -0,0 +1,320 @@ +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 +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +## 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. + +<img src="/_static/images/sticky-connections.webp" class="align-center" style="width:80.0%" alt="image" /> + +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 +``` + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +Flushing the session table will cause other connections to fall back from +flow-based to packet-based balancing until each flow is reestablished. + +</div> + +## 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 + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +Blocking call with no timeout. System will become unresponsive if script +does not return! + +</div> + +## 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..8371199f --- /dev/null +++ b/docs/configuration/md-index.md @@ -0,0 +1,22 @@ +# Configuration Guide + +The following structure respresent the cli structure. + +<div class="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 + +</div> diff --git a/docs/configuration/nat/md-index.md b/docs/configuration/nat/md-index.md new file mode 100644 index 00000000..ef73db30 --- /dev/null +++ b/docs/configuration/nat/md-index.md @@ -0,0 +1,9 @@ +# NAT + +<div class="toctree" maxdepth="1" includehidden=""> + +nat44 +nat64 +nat66 + +</div> diff --git a/docs/configuration/nat/md-nat44.md b/docs/configuration/nat/md-nat44.md new file mode 100644 index 00000000..627f84c1 --- /dev/null +++ b/docs/configuration/nat/md-nat44.md @@ -0,0 +1,844 @@ +# NAT44 + +`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 `IANA (Internet Assigned Numbers Authority)` for +private addressing (see `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 `CGN (Carrier-grade NAT)`, and uses +`1918` address space to number customer gateways, the risk of +address collision, and therefore routing failures, arises when the +customer network already uses an `1918` address space. + +This prompted some ISPs to develop a policy within the `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 `2860`). + +IETF published `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 `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 + +#### SNAT + +`SNAT (Source Network Address Translation)` is the most common +form of `NAT (Network Address Translation)` and is typically +referred to simply as NAT. To be more correct, what most people refer +to as `NAT (Network Address Translation)` is actually the process +of `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. + +#### DNAT + +`DNAT (Destination Network Address Translation)` changes the +destination address of packets passing through the router, while +`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 + +This is a common scenario where both `source-nat` and +`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 + +`NAT (Network Address Translation)` is configured entirely on a +series of so called <span class="title-ref">rules</span>. Rules are numbered and evaluated by the +underlying OS in numerical order! The rule numbers can be changes by +utilizing the `rename` and `copy` commands. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Changes to the NAT system only affect newly established +connections. Already established connections are not affected. + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +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. + +</div> + +Rules will be created for both `source-nat` and +`destination-nat`. + +For `bidirectional-nat` a rule for both `source-nat` and +`destination-nat` needs to be created. + +### 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 `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 `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 <span class="title-ref">all</span> 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. + + <div class="note"> + + <div class="title"> + + Note + + </div> + + If no destination is specified the rule will match on any + destination address and port. + + </div> + + 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 `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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The translation address must be set to one of the available +addresses on the configured <span class="title-ref">outbound-interface</span> or it must be set to +<span class="title-ref">masquerade</span> which will use the primary IP address of the +<span class="title-ref">outbound-interface</span> as its translation address. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +Example: + +- Define a discrete source IP address of 100.64.0.1 for SNAT rule 20 +- Use address <span class="title-ref">masquerade</span> (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 `destination-nat` rules the packets destination address will be +replaced by the specified address in the <span class="title-ref">translation address</span> 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 `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. + +<div class="cfgcmd"> + +set nat \[source | destination\] rule \<rule\> load-balance hash +\[source-address | destination-address | source-port | destination-port +| random\] + +</div> + +<div class="cfgcmd"> + +set nat \[source | destination\] rule \<rule\> load-balance backend +\<x.x.x.x\> weight \<1-100\> + +</div> + +## 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' +``` + +### 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/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 `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 `destination-nat` in rule 110 to the internal, + private host 192.0.2.40. We also need a `source-nat` rule 110 for + the reverse path of the traffic. The internal network 192.0.2.0/24 is + reachable via interface <span class="title-ref">eth0.10</span>. + +``` 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 + } + } + } +} +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If forwarding traffic to a different port than it is arriving +on, you may also configure the translation port using +<span class="title-ref">set nat destination rule \[n\] translation port</span>. + +</div> + +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 + } +} +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you have configured the <span class="title-ref">INSIDE-OUT</span> policy, you will need to add +additional rules to permit inbound NAT traffic. + +</div> + +### 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> +<img src="/_static/images/nat_before_vpn_topology.webp" alt="NAT before VPN Topology" /> +<figcaption aria-hidden="true">NAT before VPN Topology</figcaption> +</figure> + +#### 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..3cc9b34d --- /dev/null +++ b/docs/configuration/nat/md-nat64.md @@ -0,0 +1,68 @@ +# NAT64 + +`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 + +#### SNAT64 + +`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..619bbd49 --- /dev/null +++ b/docs/configuration/nat/md-nat66.md @@ -0,0 +1,221 @@ +# NAT66(NPTv6) + +`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 + +#### SNAT66 + +`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. + +#### DNAT66 + +The `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 `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 <span class="title-ref">fc01::/64</span> network to <span class="title-ref">fc00::/64</span> +- Output from <span class="title-ref">eth0</span> 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 `destination-nat66` rule, the destination address of +the packet isreplaced by the address calculated from the specified +address or prefix in the <span class="title-ref">translation address</span> command + +Example: + +- Convert the address prefix of a single <span class="title-ref">fc00::/64</span> network + to <span class="title-ref">fc01::/64</span> +- Input from <span class="title-ref">eth0</span> 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> +<img src="/_static/images/vyos_1_4_nat66_simple.webp" alt="VyOS NAT66 Simple Configure" /> +</figure> + +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> +<img src="/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.webp" alt="VyOS NAT66 DHCPv6 using a dummy interface" /> +</figure> + +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..15efb7a2 --- /dev/null +++ b/docs/configuration/pki/md-index.md @@ -0,0 +1,662 @@ +lastproofread +2024-01-05 + +# 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. + +`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. + +<div class="opcmd"> + +generate pki ca + +Create a new `CA (Certificate Authority)` and output the CAs public and +private key on the console. + +</div> + +<div class="opcmd"> + +generate pki ca install \<name\> + +Create a new `CA (Certificate Authority)` and output the CAs public and +private key on the console. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +`name` is used for the VyOS CLI command to identify this key. This +key `name` is then used in the CLI configuration to reference the key +instance. + +</div> + +</div> + +<div class="opcmd"> + +generate pki ca sign \<ca-name\> + +Create a new subordinate `CA (Certificate Authority)` and sign it using +the private key referenced by <span class="title-ref">ca-name</span>. + +</div> + +<div class="opcmd"> + +generate pki ca sign \<ca-name\> install \<name\> + +Create a new subordinate `CA (Certificate Authority)` and sign it using +the private key referenced by <span class="title-ref">name</span>. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +`name` is used for the VyOS CLI command to identify this key. This +key `name` is then used in the CLI configuration to reference the key +instance. + +</div> + +</div> + +### Certificates + +<div class="opcmd"> + +generate pki certificate + +Create a new public/private keypair and output the certificate on the console. + +</div> + +<div class="opcmd"> + +generate pki certificate install \<name\> + +Create a new public/private keypair and output the certificate on the console. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +`name` is used for the VyOS CLI command to identify this key. This +key `name` is then used in the CLI configuration to reference the key +instance. + +</div> + +</div> + +<div class="opcmd"> + +generate pki certificate self-signed + +Create a new self-signed certificate. The public/private is then shown on the +console. + +</div> + +<div class="opcmd"> + +generate pki certificate self-signed install \<name\> + +Create a new self-signed certificate. The public/private is then shown on the +console. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +`name` is used for the VyOS CLI command to identify this key. This +key `name` is then used in the CLI configuration to reference the key +instance. + +</div> + +</div> + +<div class="opcmd"> + +generate pki certificate sign \<ca-name\> + +Create a new public/private keypair which is signed by the CA referenced by +<span class="title-ref">ca-name</span>. The signed certificate is then output to the console. + +</div> + +<div class="opcmd"> + +generate pki certificate sign \<ca-name\> install \<name\> + +Create a new public/private keypair which is signed by the CA referenced by +<span class="title-ref">ca-name</span>. The signed certificate is then output to the console. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +`name` is used for the VyOS CLI command to identify this key. This +key `name` is then used in the CLI configuration to reference the key +instance. + +</div> + +</div> + +### Diffie-Hellman parameters + +<div class="opcmd"> + +generate pki dh + +Generate a new set of `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. + +</div> + +<div class="opcmd"> + +generate pki dh install \<name\> + +Generate a new set of `DH (Diffie-Hellman)` parameters. The key size +is requested by the CLI and defaults to 2048 bit. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +`name` is used for the VyOS CLI command to identify this key. This +key `name` is then used in the CLI configuration to reference the key +instance. + +</div> + +</div> + +### OpenVPN + +<div class="opcmd"> + +generate pki openvpn shared-secret + +Genearate a new OpenVPN shared secret. The generated secred is the output to +the console. + +</div> + +<div class="opcmd"> + +generate pki openvpn shared-secret install \<name\> + +Genearate a new OpenVPN shared secret. The generated secred is the output to +the console. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +`name` is used for the VyOS CLI command to identify this key. This +key `name` is then used in the CLI configuration to reference the key +instance. + +</div> + +</div> + +### WireGuard + +<div class="opcmd"> + +generate pki wireguard key-pair + +Generate a new WireGuard public/private key portion and output the result to +the console. + +</div> + +<div class="opcmd"> + +generate pki wireguard key-pair install \<interface\> + +Generate a new WireGuard public/private key portion and output the result to +the console. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +</div> + +<div class="opcmd"> + +generate pki wireguard pre-shared-key + +Generate a WireGuard pre-shared secret used for peers to communicate. + +</div> + +<div class="opcmd"> + +generate pki wireguard pre-shared-key install \<peer\> + +Generate a WireGuard pre-shared secret used for peers to communicate. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +</div> + +## Key usage (CLI) + +### CA (Certificate Authority) + +<div class="cfgcmd"> + +set pki ca \<name\> certificate + +Add the public CA certificate for the CA named <span class="title-ref">name</span> to the VyOS CLI. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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'` + +</div> + +</div> + +<div class="cfgcmd"> + +set pki ca \<name\> crl + +Certificate revocation list in PEM format. + +</div> + +<div class="cfgcmd"> + +set pki ca \<name\> description + +A human readable description what this CA is about. + +</div> + +<div class="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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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'` + +</div> + +</div> + +<div class="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. + +</div> + +### Server Certificate + +After we have imported the CA certificate(s) we can now import and add +certificates used by services on this router. + +<div class="cfgcmd"> + +set pki certificate \<name\> certificate + +Add public key portion for the certificate named <span class="title-ref">name</span> to the VyOS CLI. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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'` + +</div> + +</div> + +<div class="cfgcmd"> + +set pki certificate \<name\> description + +A human readable description what this certificate is about. + +</div> + +<div class="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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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'` + +</div> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set pki certificate \<name\> revoke + +If CA is present, this certificate will be included in generated CRLs + +</div> + +#### ACME + +The VyOS PKI subsystem can also be used to automatically retrieve Certificates +using the `ACME (Automatic Certificate Management Environment)` protocol. +VyOS 1.4.1 does not store the intermediate certificates from ACME. Which makes +this functionality limited. See `T7299`. + +<div class="cfgcmd"> + +set pki certificate \<name\> acme domain-name \<name\> + +Domain names to apply, multiple domain-names can be specified. + +This is a mandatory option + +</div> + +<div class="cfgcmd"> + +set pki certificate \<name\> acme email \<address\> + +Email used for registration and recovery contact. + +This is a mandatory option + +</div> + +<div class="cfgcmd"> + +set pki certificate \<name\> acme listen-address \<address\> + +The address the server listens to during http-01 challenge + +</div> + +<div class="cfgcmd"> + +set pki certificate \<name\> acme rsa-key-size \<2048 | 3072 | 4096\> + +Size of the RSA key. + +This options defaults to 2048 + +</div> + +<div class="cfgcmd"> + +set pki certificate \<name\> acme url \<url\> + +ACME Directory Resource URI. + +This defaults to <https://acme-v02.api.letsencrypt.org/directory> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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> + +</div> + +</div> + +## Operation + +VyOS operational mode commands are not only available for generating keys but +also to display them. + +<div class="opcmd"> + +show pki ca + +Show a list of installed `CA (Certificate Authority)` certificates. + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show pki ca \<name\> + +Show only information for specified Certificate Authority. + +</div> + +<div class="opcmd"> + +show pki certificate + +Show a list of installed certificates + +``` 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) +``` + +</div> + +<div class="opcmd"> + +show pki certificate \<name\> + +Show only information for specified certificate. + +</div> + +<div class="opcmd"> + +show pki crl + +Show a list of installed `CRLs (Certificate Revocation List)`. + +</div> + +<div class="opcmd"> + +renew certbot + +Manually trigger certificate renewal. This will be done twice a day. + +</div> diff --git a/docs/configuration/policy/md-access-list.md b/docs/configuration/policy/md-access-list.md new file mode 100644 index 00000000..4a1468b0 --- /dev/null +++ b/docs/configuration/policy/md-access-list.md @@ -0,0 +1,96 @@ +# 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 + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set policy access-list \<acl_number\> description \<text\> + +Set description for the access list. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set policy access-list \<acl_number\> rule \<1-65535\> +\<destination[|source\> \<any|](##SUBST##|source> <any|)host[|inverse-mask|](##SUBST##|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). + +</div> + +### IPv6 Access List + +Basic filtering could also be applied to IPv6 traffic. + +<div class="cfgcmd"> + +set policy access-list6 \<text\> + +This command creates the new IPv6 access list, identified by \<text\> + +</div> + +<div class="cfgcmd"> + +set policy access-list6 \<text\> description \<text\> + +Set description for the IPv6 access list. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set policy access-list6 \<text\> rule \<1-65535\> source +\<any[|exact-match|](##SUBST##|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 + +</div> 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..5fdebe29 --- /dev/null +++ b/docs/configuration/policy/md-as-path-list.md @@ -0,0 +1,48 @@ +# 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 + +<div class="cfgcmd"> + +set policy as-path-list \<text\> + +Create as-path-policy identified by name \<text\>. + +</div> + +<div class="cfgcmd"> + +set policy as-path-list \<text\> description \<text\> + +Set description for as-path-list policy. + +</div> + +<div class="cfgcmd"> + +set policy as-path-list \<text\> rule \<1-65535\> action \<permit|deny\> + +Set action to take on entries matching this rule. + +</div> + +<div class="cfgcmd"> + +set policy as-path-list \<text\> rule \<1-65535\> description \<text\> + +Set description for rule. + +</div> + +<div class="cfgcmd"> + +set policy as-path-list \<text\> rule \<1-65535\> regex \<text\> + +Regular expression to match against an AS path. For example "64501 64502". + +</div> diff --git a/docs/configuration/policy/md-community-list.md b/docs/configuration/policy/md-community-list.md new file mode 100644 index 00000000..943d59ca --- /dev/null +++ b/docs/configuration/policy/md-community-list.md @@ -0,0 +1,50 @@ +# BGP - Community List + +VyOS provides policies commands exclusively for BGP traffic filtering and +manipulation: **community-list** is one of them. + +## Configuration + +### policy community-list + +<div class="cfgcmd"> + +set policy community-list \<text\> + +Creat community-list policy identified by name \<text\>. + +</div> + +<div class="cfgcmd"> + +set policy community-list \<text\> description \<text\> + +Set description for community-list policy. + +</div> + +<div class="cfgcmd"> + +set policy community-list \<text\> rule \<1-65535\> action +\<permit|deny\> + +Set action to take on entries matching this rule. + +</div> + +<div class="cfgcmd"> + +set policy community-list \<text\> rule \<1-65535\> description \<text\> + +Set description for rule. + +</div> + +<div class="cfgcmd"> + +set policy community-list \<text\> rule \<1-65535\> regex +\<aa:nn[|local-AS|](##SUBST##|local-AS|)no-advertise[|no-export|](##SUBST##|no-export|)internet|additive\> + +Regular expression to match against a community-list. + +</div> diff --git a/docs/configuration/policy/md-examples.md b/docs/configuration/policy/md-examples.md new file mode 100644 index 00000000..9b2717cb --- /dev/null +++ b/docs/configuration/policy/md-examples.md @@ -0,0 +1,201 @@ +# 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> +<img src="/_static/images/pbr_example_1.webp" alt="PBR multiple uplinks" /> +<figcaption>Policy-Based Routing with multiple ISP uplinks +(source ./draw.io/pbr_example_1.drawio)</figcaption> +</figure> + +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.2.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 `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..d05315dd --- /dev/null +++ b/docs/configuration/policy/md-extcommunity-list.md @@ -0,0 +1,55 @@ +# 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 + +<div class="cfgcmd"> + +set policy extcommunity-list \<text\> + +Creat extcommunity-list policy identified by name \<text\>. + +</div> + +<div class="cfgcmd"> + +set policy extcommunity-list \<text\> description \<text\> + +Set description for extcommunity-list policy. + +</div> + +<div class="cfgcmd"> + +set policy extcommunity-list \<text\> rule \<1-65535\> action +\<permit|deny\> + +Set action to take on entries matching this rule. + +</div> + +<div class="cfgcmd"> + +set policy extcommunity-list \<text\> rule \<1-65535\> description +\<text\> + +Set description for rule. + +</div> + +<div class="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. + +</div> diff --git a/docs/configuration/policy/md-index.md b/docs/configuration/policy/md-index.md new file mode 100644 index 00000000..91e20aa7 --- /dev/null +++ b/docs/configuration/policy/md-index.md @@ -0,0 +1,46 @@ +:lastproofread:2021-07-12 + +# 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 + +<div class="toctree" maxdepth="1" includehidden=""> + +access-list +prefix-list +route +route-map +local-route +as-path-list +community-list +extcommunity-list +large-community-list + +</div> + +## Examples + +Examples of policies usage: + +<div class="toctree" maxdepth="1" includehidden=""> + +examples + +</div> 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..00888140 --- /dev/null +++ b/docs/configuration/policy/md-large-community-list.md @@ -0,0 +1,51 @@ +# 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 + +<div class="cfgcmd"> + +set policy large-community-list \<text\> + +Create large-community-list policy identified by name \<text\>. + +</div> + +<div class="cfgcmd"> + +set policy large-community-list \<text\> description \<text\> + +Set description for large-community-list policy. + +</div> + +<div class="cfgcmd"> + +set policy large-community-list \<text\> rule \<1-65535\> action +\<permit|deny\> + +Set action to take on entries matching this rule. + +</div> + +<div class="cfgcmd"> + +set policy large-community-list \<text\> rule \<1-65535\> description +\<text\> + +Set description for rule. + +</div> + +<div class="cfgcmd"> + +set policy large-community-list \<text\> rule \<1-65535\> regex +\<aa:nn:nn\> + +Regular expression to match against a large community list. + +</div> diff --git a/docs/configuration/policy/md-local-route.md b/docs/configuration/policy/md-local-route.md new file mode 100644 index 00000000..17afb7f8 --- /dev/null +++ b/docs/configuration/policy/md-local-route.md @@ -0,0 +1,73 @@ +# Local Route Policy + +Policies for local traffic are defined in this section. + +## Configuration + +### Local Route IPv4 + +<div class="cfgcmd"> + +set policy local-route rule \<1-32765\> set table \<1-200|main\> + +Set routing table to forward packet to. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set policy local-route rule \<1-32765\> inbound-interface \<interface\> + +Set inbound interface to match. + +</div> + +### Local Route IPv6 + +<div class="cfgcmd"> + +set policy local-route6 rule \<1-32765\> set table \<1-200|main\> + +Set routing table to forward packet to. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set policy local-route6 rule \<1-32765\> inbound-interface \<interface\> + +Set inbound interface to match. + +</div> diff --git a/docs/configuration/policy/md-prefix-list.md b/docs/configuration/policy/md-prefix-list.md new file mode 100644 index 00000000..d0490249 --- /dev/null +++ b/docs/configuration/policy/md-prefix-list.md @@ -0,0 +1,190 @@ +# 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 + +<div class="cfgcmd"> + +set policy prefix-list \<text\> + +This command creates the new prefix-list policy, identified by \<text\>. + +</div> + +<div class="cfgcmd"> + +set policy prefix-list \<text\> description \<text\> + +Set description for the prefix-list policy. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set policy prefix-list \<text\> rule \<1-65535\> description \<text\> + +Set description for rule in the prefix-list. + +</div> + +<div class="cfgcmd"> + +set policy prefix-list \<text\> rule \<1-65535\> prefix \<x.x.x.x/x\> + +Prefix to match against. + +</div> + +<div class="cfgcmd"> + +set policy prefix-list \<text\> rule \<1-65535\> ge \<0-32\> + +Netmask greater than length. + +</div> + +<div class="cfgcmd"> + +set policy prefix-list \<text\> rule \<1-65535\> le \<0-32\> + +Netmask less than length + +</div> + +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. + +<div class="cfgcmd"> + +set policy prefix-list PL4-EXAMPLE-NAME rule 10 action 'permit' + +</div> + +<div class="cfgcmd"> + +set policy prefix-list PL4-EXAMPLE-NAME rule 10 le '32' + +</div> + +<div class="cfgcmd"> + +set policy prefix-list PL4-EXAMPLE-NAME rule 10 prefix '192.0.2.0/24' + +</div> + +<div class="cfgcmd"> + +set policy prefix-list PL4-EXAMPLE-NAME rule 20 action 'permit' + +</div> + +<div class="cfgcmd"> + +set policy prefix-list PL4-EXAMPLE-NAME rule 20 le '32' + +</div> + +<div class="cfgcmd"> + +set policy prefix-list PL4-EXAMPLE-NAME rule 20 prefix '198.51.100.0/24' + +</div> + +<div class="cfgcmd"> + +set policy prefix-list PL4-EXAMPLE-NAME rule 30 action 'permit' + +</div> + +<div class="cfgcmd"> + +set policy prefix-list PL4-EXAMPLE-NAME rule 30 le '32' + +</div> + +<div class="cfgcmd"> + +set policy prefix-list PL4-EXAMPLE-NAME rule 30 prefix '203.0.113.0/24' + +</div> + +### IPv6 Prefix Lists + +<div class="cfgcmd"> + +set policy prefix-list6 \<text\> + +This command creates the new IPv6 prefix-list policy, identified by \<text\>. + +</div> + +<div class="cfgcmd"> + +set policy prefix-list6 \<text\> description \<text\> + +Set description for the IPv6 prefix-list policy. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set policy prefix-list6 \<text\> rule \<1-65535\> description \<text\> + +Set description for rule in IPv6 prefix-list. + +</div> + +<div class="cfgcmd"> + +set policy prefix-list6 \<text\> rule \<1-65535\> prefix +\<h:h:h:h:h:h:h:h/x\> + +IPv6 prefix. + +</div> + +<div class="cfgcmd"> + +set policy prefix-list6 \<text\> rule \<1-65535\> ge \<0-128\> + +Netmask greater than length. + +</div> + +<div class="cfgcmd"> + +set policy prefix-list6 \<text\> rule \<1-65535\> le \<0-128\> + +Netmask less than length + +</div> diff --git a/docs/configuration/policy/md-route-map.md b/docs/configuration/policy/md-route-map.md new file mode 100644 index 00000000..4c356e5d --- /dev/null +++ b/docs/configuration/policy/md-route-map.md @@ -0,0 +1,651 @@ +# 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 + +<div class="cfgcmd"> + +set policy route-map \<text\> + +This command creates a new route-map policy, identified by \<text\>. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> description \<text\> + +Set description for the route-map policy. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> action \<permit|deny\> + +Set action for the route-map policy. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> call \<text\> + +Call another route-map policy on match. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> continue \<1-65535\> + +Jump to a different rule in this route-map on a match. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> description \<text\> + +Set description for the rule in the route-map policy. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match as-path \<text\> + +BGP as-path list to match. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match community +community-list \<text\> + +BGP community-list to match. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match community +exact-match + +Set BGP community-list to exactly match. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match extcommunity +\<text\> + +BGP extended community to match. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match interface \<text\> + +First hop interface of a route to match. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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.. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match ip nexthop +type \<blackhole\> + +IP next-hop of route to match, based on type. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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.. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match large-community +large-community-list \<text\> + +Match BGP large communities. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match local-preference +\<0-4294967295\> + +Match local preference. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match metric \<1-65535\> + +Match route metric. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match origin +\<egp[|igp|](##SUBST##|igp|)incomplete\> + +Boarder Gateway Protocol (BGP) origin code to match. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match peer \<x.x.x.x\> + +Peer IP address to match. + +</div> + +<div class="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) + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match rpki +\<invalid[|notfound|](##SUBST##|notfound|)valid\> + +Match RPKI validation result. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match source-vrf \<text\> + +Source VRF to match. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match tag \<1-65535\> + +Route tag to match. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> on-match goto \<1-65535\> + +Exit policy on match: go to rule \<1-65535\> + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> on-match next + +Exit policy on match: go to next sequence number. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set aggregator \<as[|ip\> +\<1-4294967295|](##SUBST##|ip> +<1-4294967295|)x.x.x.x\> + +BGP aggregator attribute: AS number or IP address of an aggregation. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set atomic-aggregate + +BGP atomic aggregate attribute. + +</div> + +<div class="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 + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set community none + +Delete all BGP communities + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set community delete +\<text\> + +Delete BGP communities matching the community-list. + +</div> + +<div class="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>` + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set large-community none + +Delete all BGP large-communities + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set large-community delete +\<text\> + +Delete BGP communities matching the large-community-list. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set extcommunity bandwidth +\<1-25600[|cumulative|](##SUBST##|cumulative|)num-multipaths\> + +Set extcommunity bandwidth + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set extcommunity bandwidth-non-transitive + +The link bandwidth extended community is encoded as non-transitive + +</div> + +<div class="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>`. + +</div> + +<div class="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>`. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set extcommunity none + +Clear all BGP extcommunities. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set distance \<0-255\> + +Locally significant administrative distance. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set ip-next-hop +\<x.x.x.x\> + +Nexthop IP address. + +</div> + +<div class="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 + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set local-preference +\<0-4294967295\> + +Set BGP local preference attribute. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set metric +\<+/-metric[|0-4294967295|](##SUBST##|0-4294967295|)rtt[|+rtt|](##SUBST##|+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. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set metric-type +\<type-1|type-2\> + +Set OSPF external metric-type. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set origin +\<igp[|egp|](##SUBST##|egp|)incomplete\> + +Set BGP origin code. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set originator-id +\<x.x.x.x\> + +Set BGP originator ID attribute. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set table \<1-200\> + +Set prefixes to table. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set tag \<1-65535\> + +Set tag value for routing protocol. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set weight +\<0-4294967295\> + +Set BGP weight attribute + +</div> + +### 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..efd0eedf --- /dev/null +++ b/docs/configuration/policy/md-route.md @@ -0,0 +1,647 @@ +# 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. + +<div class="cfgcmd"> + +set policy route \<name\> description \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> description \<text\> + +Provide a rule-set description. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> default-log + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> default-log + +Option to log packets hitting default-action. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> description \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> description \<text\> + +Provide a description for each rule. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> log \<enable|disable\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> log \<enable|disable\> + +Option to enable or disable log matching rule. + +</div> + +### 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. + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> connection-mark \<1-2147483647\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> connection-mark \<1-2147483647\> + +Set match criteria based on connection mark. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> source address +\<match_criteria\> + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> destination address +\<match_criteria\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> source address +\<match_criteria\> + +</div> + +<div class="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: + +</div> + +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. + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> source group +\<address-group[|domain-group|](##SUBST##|domain-group|)mac-group[|network-group|](##SUBST##|network-group|)port-group\> \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> destination group +\<address-group[|domain-group|](##SUBST##|domain-group|)mac-group[|network-group|](##SUBST##|network-group|)port-group\> \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> source group +\<address-group[|domain-group|](##SUBST##|domain-group|)mac-group[|network-group|](##SUBST##|network-group|)port-group\> \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> destination group +\<address-group[|domain-group|](##SUBST##|domain-group|)mac-group[|network-group|](##SUBST##|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. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> destination port \<match_criteria\> + +</div> + +<div class="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' + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> disable + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> disable + +Option to disable rule. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> dscp \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> dscp \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> dscp-exclude \<text\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> fragment +\<match-grag|match-non-frag\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> icmp \<code | type\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> icmpv6 \<code | type\> + +Match based on icmp|icmpv6 code and type. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> icmp type-name \<text\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> ipsec +\<match-ipsec|match-none\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> limit burst \<0-4294967295\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> limit burst \<0-4294967295\> + +Set maximum number of packets to alow in excess of rate. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> limit rate \<text\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> protocol +\<text | 0-255 | tcp_udp | all \> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> packet-length \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> packet-length \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> packet-length-exclude \<text\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> packet-type \[broadcast | host +| multicast | other\] + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> packet-type \[broadcast | host +| multicast | other\] + +Match based on packet type criteria. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> recent time \<1-4294967295\> + +</div> + +<div class="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). + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> state +\<established | invalid | new | related\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> state +\<established | invalid | new | related\> + +Set match criteria based on session state. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> tcp flags \<text\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> time monthdays \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> time monthdays \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> time startdate \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> time startdate \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> time starttime \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> time starttime \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> time stopdate \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> time stopdate \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> time stoptime \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> time stoptime \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> time weekdays \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> time weekdays \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> time utc + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> time utc + +Time to match the defined rule. + +</div> + +<div class="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'. + +</div> + +<div class="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'. + +</div> + +### 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. + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> action drop + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> action drop + +Set rule action to drop. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> set connection-mark +\<1-2147483647\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> set connection-mark +\<1-2147483647\> + +Set a specific connection mark. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> set dscp \<0-63\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> set dscp \<0-63\> + +Set packet modifications: Packet Differentiated Services Codepoint (DSCP) + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> set mark \<1-2147483647\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> set mark \<1-2147483647\> + +Set a specific packet mark. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> set table \<main | 1-200\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> set table \<main | 1-200\> + +Set the routing table to forward packet with. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> set tcp-mss \<500-1460\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> set tcp-mss \<500-1460\> + +Set packet modifications: Explicitly set TCP Maximum segment size value. + +</div> diff --git a/docs/configuration/protocols/md-babel.md b/docs/configuration/protocols/md-babel.md new file mode 100644 index 00000000..8bca4a71 --- /dev/null +++ b/docs/configuration/protocols/md-babel.md @@ -0,0 +1,294 @@ +# 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 `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. + +<div class="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. + +</div> + +## Optional Configuration + +<div class="cfgcmd"> + +set protocols babel parameters diversity + +This command enables routing using radio frequency diversity. +This is highly recommended in networks with many wireless nodes. + +> <div class="note"> +> +> <div class="title"> +> +> Note +> +> </div> +> +> If you enable this, you will probably want to +> set diversity-factor and channel below. +> +> </div> + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +## Interfaces Configuration + +<div class="cfgcmd"> + +set protocols babel interface \<interface\> type \<auto[|wired|](##SUBST##|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. + +</div> + +<div class="cfgcmd"> + +set protocols babel interface \<interface\> split-horizon \<default[|disable|](##SUBST##|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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols babel interface \<interface\> channel \<1-254[|interfering|](##SUBST##|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. + +</div> + +## Redistribution Configuration + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols babel distribute-list \<ipv4[|ipv6\> access-list \<in|](##SUBST##|ipv6> access-list <in|)out\> \<number\> + +This command can be used to filter the Babel routes using access lists. +`in` and `out` this is the direction in which the access +lists are applied. + +</div> + +<div class="cfgcmd"> + +set protocols babel distribute-list \<ipv4[|ipv6\> interface \<interface\> access-list \<in|](##SUBST##|ipv6> interface <interface> access-list <in|)out\> \<number\> + +This command allows you apply access lists to a chosen interface to +filter the Babel routes. + +</div> + +<div class="cfgcmd"> + +set protocols babel distribute-list \<ipv4[|ipv6\> prefix-list \<in|](##SUBST##|ipv6> prefix-list <in|)out\> \<name\> + +This command can be used to filter the Babel routes using prefix lists. +`in` and `out` this is the direction in which the prefix +lists are applied. + +</div> + +<div class="cfgcmd"> + +set protocols babel distribute-list \<ipv4[|ipv6\> interface \<interface\> prefix-list \<in|](##SUBST##|ipv6> interface <interface> prefix-list <in|)out\> \<name\> + +This command allows you apply prefix lists to a chosen interface to +filter the Babel routes. + +</div> + +## 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..58582008 --- /dev/null +++ b/docs/configuration/protocols/md-bfd.md @@ -0,0 +1,259 @@ +lastproofread +2023-01-27 + +# BFD + +`BFD (Bidirectional Forwarding Detection)` is described and extended by +the following RFCs: `5880`, `5881` and `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 + +<div class="cfgcmd"> + +set protocols bfd peer \<address\> + +Set BFD peer IPv4 address or IPv6 address + +</div> + +<div class="cfgcmd"> + +set protocols bfd peer \<address\> echo-mode + +Enables the echo transmission mode + +</div> + +<div class="cfgcmd"> + +set protocols bfd peer \<address\> multihop + +Allow this BFD peer to not be directly connected + +</div> + +<div class="cfgcmd"> + +set protocols bfd peer \<address\> source +\[address \<address\> | interface \<interface\>\] + +Bind listener to specific interface/address, mandatory for IPv6 + +</div> + +<div class="cfgcmd"> + +set protocols bfd peer \<address\> interval echo-interval \<10-60000\> + +The minimal echo receive transmission interval that this system is +capable of handling + +</div> + +<div class="cfgcmd"> + +set protocols bfd peer \<address\> interval multiplier \<2-255\> + +Remote transmission interval will be multiplied by this value + +</div> + +<div class="cfgcmd"> + +set protocols bfd peer \<address\> interval +\[receive | transmit\] \<10-60000\> + +Interval in milliseconds + +</div> + +<div class="cfgcmd"> + +set protocols bfd peer \<address\> shutdown + +Disable a BFD peer + +</div> + +<div class="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. + +</div> + +### Enable BFD in BGP + +<div class="cfgcmd"> + +set protocols bgp neighbor \<neighbor\> bfd + +Enable BFD on a single BGP neighbor + +</div> + +<div class="cfgcmd"> + +set protocols bgp peer-group \<neighbor\> bfd + +Enable BFD on a BGP peer group + +</div> + +### Enable BFD in OSPF + +<div class="cfgcmd"> + +set protocols ospf interface \<interface\> bfd + +Enable BFD for OSPF on an interface + +</div> + +<div class="cfgcmd"> + +set protocols ospfv3 interface \<interface\> bfd + +Enable BFD for OSPFv3 on an interface + +</div> + +### Enable BFD in ISIS + +<div class="cfgcmd"> + +set protocols isis \<name\> interface \<interface\> bfd + +Enable BFD for ISIS on an interface + +</div> + +## Operational Commands + +<div class="opcmd"> + +show bfd peers + +Show all BFD peers + +``` 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 +``` + +</div> + +## 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 + +<div class="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. + +</div> + +<div class="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 indentify the peer when is multi-hop session +and the gateway address as BFD peer destination address. + +</div> + +<div class="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. + +</div> + +<div class="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 indentify the peer when is multi-hop session +and the gateway address as BFD peer destination address. + +</div> + +## Operational Commands + +<div class="opcmd"> + +show bfd static routes + +Showing BFD monitored static routes + +``` 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: +``` + +</div> diff --git a/docs/configuration/protocols/md-bgp.md b/docs/configuration/protocols/md-bgp.md new file mode 100644 index 00000000..b5a91b3f --- /dev/null +++ b/docs/configuration/protocols/md-bgp.md @@ -0,0 +1,1683 @@ +# BGP + +`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 `1771` and updated by `4271`. `2858` +adds multiprotocol support to BGP. + +VyOS makes use of `FRR (Free Range Routing)` and we would like to thank +them for their effort! + +## Basic Concepts + +### Autonomous Systems + +From `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 `AS (Autonomous System)` has an identifying number associated with it +called an `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 `6793`, and provide a pool of 4294967296 AS numbers. + +The `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. + +<div class="cfgcmd"> + +set protocols bgp system-as \<asn\> + +Set local `ASN (Autonomous System Number)` that this router represents. +This is a a mandatory option! + +</div> + +### 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. + +### 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. + +1. **Weight check** + + Prefer higher local weight routes to lower routes. + +2. **Local preference check** + + Prefer higher local preference routes to lower. + +3. **Local route check** + + Prefer local routes (statics, aggregates, redistributed) to received routes. + +4. **AS path length check** + + Prefer shortest hop-count AS_PATHs. + +5. **Origin check** + + Prefer the lowest origin type route. That is, prefer IGP origin routes to + EGP, to Incomplete routes. + +6. **MED check** + + Where routes with a MED were received from the same AS, prefer the route + with the lowest MED. + +7. **External check** + + Prefer the route received from an external, eBGP peer over routes received + from other types of peers. + +8. **IGP cost check** + + Prefer the route with the lower IGP cost. + +9. **Multi-path check** + + If multi-pathing is enabled, then check whether the routes not yet + distinguished in preference may be considered equal. If + `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 + `bgp bestpath compare-routerid` is configured. This check can + prevent some cases of oscillation. + +11. **Router-ID check** + + Prefer the route with the lowest <span class="title-ref">router-ID</span>. If the route has an + <span class="title-ref">ORIGINATOR_ID</span> attribute, through iBGP reflection, then that router ID is + used, otherwise the <span class="title-ref">router-ID</span> 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. + +### Capability Negotiation + +When adding IPv6 routing information exchange feature to BGP. There were some +proposals. `IETF (Internet Engineering Task Force)` +`IDR (Inter Domain Routing)` adopted a proposal called Multiprotocol +Extension for BGP. The specification is described in `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. `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 + +First of all you must configure BGP router with the `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. + +<div class="cfgcmd"> + +set protocols bgp system-as \<asn\> + +Set local autonomous system number that this router represents. This is a +mandatory option! + +</div> + +#### Peers Configuration + +##### Defining Peers + +<div class="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. + +</div> + +<div class="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 `protocols +bgp <asn>` command the connection will be denied. + +</div> + +<div class="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 `protocols +bgp <asn>` command the connection will be denied. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address|interface\> local-role +\<role\> \[strict\] + +BGP roles are defined in 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 `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 `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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address|interface\> description +\<text\> + +Set description of the peer or peer group. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> update-source +\<address|](##SUBST##|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. + +</div> + +##### Capability Negotiation + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address|interface\> capability +dynamic + +This command would allow the dynamic update of capabilities over an +established BGP session. + +</div> + +<div class="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. + +</div> + +<div class="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 `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. + +</div> + +<div class="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. + +</div> + +<div class="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 `disable-capability-negotiation` +command to disable the feature. + +</div> + +##### Peer Parameters + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|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. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|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. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|interface> address-family +<ipv4-unicast|)ipv6-unicast\> attribute-unchanged \<as-path[|med|](##SUBST##|med|)next-hop\> + +This command specifies attributes to be left unchanged for +advertisements sent to a peer or peer group. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|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. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|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. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|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. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Storage of route updates uses memory. If you enable soft +reconfiguration inbound for multiple neighbors, the amount of memory used +can become significant. + +</div> + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> +disable-send-community \<extended|](##SUBST##|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. + +</div> + +<div class="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 `ttl-security hops`. + +</div> + +<div class="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 `no-prepend` attribute is specified, then the supplied +local-as is not prepended to the received AS_PATH. + +If the `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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +This command is only allowed for eBGP peers. + +</div> + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address|interface\> ttl-security +hops \<number\> + +This command enforces Generalized TTL Security Mechanism (GTSM), +as specified in `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 `ebgp-multihop`. + +</div> + +##### 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. + +<div class="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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address|interface\> peer-group +\<name\> + +This command bind specific peer to peer group with a given name. + +</div> + +#### Network Advertisement Configuration + +<div class="cfgcmd"> + +set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> +network \<prefix\> + +This command is used for advertising IPv4 or IPv6 networks. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|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 `route-map` you can inject the +default route to given neighbor only if the conditions in the route map are +met. + +</div> + +#### Route Aggregation Configuration + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|interface> address-family +<ipv4-unicast|)ipv6-unicast\> unsuppress-map \<name\> + +This command applies route-map to selectively unsuppress prefixes +suppressed by summarisation. + +</div> + +#### Redistribution Configuration + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +#### General Configuration + +##### Common parameters + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols bgp address-family \<ipv4-unicast[|ipv6-unicast\> +maximum-paths \<ebgp|](##SUBST##|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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols bgp parameters log-neighbor-changes + +This command enable logging neighbor up/down changes and reset reason. + +</div> + +<div class="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 `no-client-to-client-reflection` command +to disable client-to-client reflection. + +</div> + +<div class="cfgcmd"> + +set protocols bgp parameters no-fast-external-failover + +Disable immediate session reset if peer's connected link goes down. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols bgp parameters ebgp-requires-policy + +This command changes the eBGP behavior of FRR. By default FRR enables +`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 `8212` functionality to operate. + +</div> + +<div class="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. + +</div> + +##### Administrative Distance + +<div class="cfgcmd"> + +set protocols bgp parameters distance global +\<external[|internal|](##SUBST##|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. + +</div> + +<div class="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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Routes with a distance of 255 are effectively disabled and not +installed into the kernel. + +</div> + +</div> + +##### Timers + +<div class="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. + +</div> + +<div class="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. + +</div> + +##### 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 `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. + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +#### Route Selection Configuration + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols bgp parameters bestpath as-path ignore + +Ignore AS_PATH length when selecting a route + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +#### 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 +> +> <div class="note"> +> +> <div class="title"> +> +> Note +> +> </div> +> +> The attributes `prefix-list` and `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. +> +> </div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|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 `export` and `import` +specify the direction in which the access list are applied. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|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 `export` and `import` +specify the direction in which the prefix list are applied. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|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 `export` and `import` +specify the direction in which the route map are applied. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|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 `export` and `import` +specify the direction in which the AS path access list are applied. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|interface> address-family +<ipv4-unicast|)ipv6-unicast\> capability orf \<receive|send\> + +This command enables the ORF capability (described in `5291`) on the +local router, and enables ORF capability advertisement to the specified BGP +peer. The `receive` keyword configures a router to advertise ORF +receive capabilities. The `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. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address|interface\> solo + +This command prevents from sending back prefixes learned from the neighbor. + +</div> + +#### 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 `4456` and updated +by `7606`. + +<div class="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. + +</div> + +<div class="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. + +</div> + +##### 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 +`5065` + +<div class="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). + +</div> + +<div class="cfgcmd"> + +set protocols bgp parameters confederation peers \<nsubasn\> + +This command sets other confederations \<nsubasn\> as members of autonomous +system specified by `confederation identifier <asn>`. + +</div> + +## Operational Mode Commands + +### Show + +<div class="opcmd"> + +show bgp \<ip|ipv6\> + +This command displays all entries in BGP routing table. + +</div> + +``` 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 +``` + +<div class="opcmd"> + +show bgp \<ip[|ipv6\> \<address|](##SUBST##|ipv6> <address|)prefix\> + +This command displays information about the particular entry in the BGP +routing table. + +</div> + +``` 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 +``` + +<div class="opcmd"> + +show bgp cidr-only + +This command displays routes with classless interdomain routing (CIDR). + +</div> + +<div class="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. + +</div> + +<div class="opcmd"> + +show bgp \<ipv4|ipv6\> community-list \<name\> + +This command displays routes that are permitted by the BGP +community list. + +</div> + +<div class="opcmd"> + +show bgp \<ipv4|ipv6\> dampening dampened-paths + +This command displays BGP dampened routes. + +</div> + +<div class="opcmd"> + +show bgp \<ipv4|ipv6\> dampening flap-statistics + +This command displays information about flapping BGP routes. + +</div> + +<div class="opcmd"> + +show bgp \<ipv4|ipv6\> filter-list \<name\> + +This command displays BGP routes allowed by the specified AS Path +access list. + +</div> + +<div class="opcmd"> + +show bgp \<ipv4|ipv6\> neighbors \<address\> advertised-routes + +This command displays BGP routes advertised to a neighbor. + +</div> + +<div class="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. + +</div> + +<div class="opcmd"> + +show bgp \<ipv4|ipv6\> neighbors \<address\> routes + +This command displays BGP received-routes that are accepted after filtering. + +</div> + +<div class="opcmd"> + +show bgp \<ipv4|ipv6\> neighbors \<address\> dampened-routes + +This command displays dampened routes received from BGP neighbor. + +</div> + +<div class="opcmd"> + +show bgp \<ipv4|ipv6\> regexp \<text\> + +This command displays information about BGP routes whose AS path +matches the specified regular expression. + +</div> + +<div class="opcmd"> + +show bgp \<ipv4|ipv6\> summary + +This command displays the status of all BGP connections. + +</div> + +``` 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 + +<div class="opcmd"> + +reset bgp \<ipv4[|ipv6\> \<address\> \[soft \[in|](##SUBST##|ipv6> <address> [soft [in|)out\]\] + +This command resets BGP connections to the specified neighbor IP address. +With argument `soft` this command initiates a soft reset. If +you do not specify the `in` or `out` options, both +inbound and outbound soft reconfiguration are triggered. + +</div> + +<div class="opcmd"> + +reset ip bgp all + +This command resets all BGP connections of given router. + +</div> + +<div class="opcmd"> + +reset bgp \<ipv4|ipv6\> external + +This command resets all external BGP peers of given router. + +</div> + +<div class="opcmd"> + +reset bgp \<ipv4[|ipv6\> peer-group \<name\> \[soft \[in|](##SUBST##|ipv6> peer-group <name> [soft [in|)out\]\] + +This command resets BGP connections to the specified peer group. +With argument `soft` this command initiates a soft reset. If +you do not specify the `in` or `out` options, both +inbound and outbound soft reconfiguration are triggered. + +</div> + +## 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..06ce402d --- /dev/null +++ b/docs/configuration/protocols/md-failover.md @@ -0,0 +1,131 @@ +# 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 + +<div class="cfgcmd"> + +set protocols failover route \<subnet\> next-hop \<address\> check +target \<target-address\> + +Configure next-hop <span class="title-ref">\<address\></span> and <span class="title-ref">\<target-address\></span> for an IPv4 static +route. Specify the target +IPv4 address for health checking. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols failover route \<subnet\> next-hop \<address\> check +type \<protocol\> + +Defines protocols for checking ARP, ICMP, TCP + +Default is `icmp`. + +</div> + +<div class="cfgcmd"> + +set protocols failover route \<subnet\> next-hop \<address\> check +policy \<policy\> + +Policy for checking targets + +</div> + +- `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`. + +<div class="cfgcmd"> + +set protocols failover route \<subnet\> next-hop \<address\> +interface \<interface\> + +Next-hop interface for the route + +</div> + +<div class="cfgcmd"> + +set protocols failover route \<subnet\> next-hop \<address\> +metric \<metric\> + +Route metric + +Default 1. + +</div> + +## 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..f35f1747 --- /dev/null +++ b/docs/configuration/protocols/md-igmp-proxy.md @@ -0,0 +1,88 @@ +lastproofread +2023-11-13 + +# IGMP Proxy + +`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 + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols igmp-proxy disable + +Disable this service. + +</div> + +### Example + +Interface <span class="title-ref">eth1</span> LAN is behind NAT. In order to subscribe <span class="title-ref">10.0.0.0/23</span> subnet +multicast which is in <span class="title-ref">eth0</span> 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 + +<div class="opcmd"> + +restart igmp-proxy + +Restart the IGMP proxy process. + +</div> diff --git a/docs/configuration/protocols/md-index.md b/docs/configuration/protocols/md-index.md new file mode 100644 index 00000000..60e20bc9 --- /dev/null +++ b/docs/configuration/protocols/md-index.md @@ -0,0 +1,20 @@ +# Protocols + +<div class="toctree" maxdepth="1" includehidden=""> + +babel +bfd +bgp +failover +igmp-proxy +isis +mpls +segment-routing +ospf +pim +pim6 +rip +rpki +static + +</div> diff --git a/docs/configuration/protocols/md-isis.md b/docs/configuration/protocols/md-isis.md new file mode 100644 index 00000000..8081860a --- /dev/null +++ b/docs/configuration/protocols/md-isis.md @@ -0,0 +1,662 @@ +# IS-IS + +`IS-IS (Intermediate System to Intermediate System)` is a link-state +interior gateway protocol (IGP) which is described in ISO10589, +`1195`, `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 +`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 `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. + +<div class="cfgcmd"> + +set protocols isis net \<network-entity-title\> + +This commad sets network entity title (NET) provided in ISO format. + +Here is an example `NET (Network Entity Title)` value: + +``` none +49.0001.1921.6800.1002.00 +``` + +The CLNS address consists of the following parts: + +- `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`. +- `NET (Network Entity Title)` selector: `00` Must always be 00. This + setting indicates "this system" or "local system." + +</div> + +<div class="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. + +</div> + +#### IS-IS Global Configuration + +<div class="cfgcmd"> + +set protocols isis dynamic-hostname + +This command enables support for dynamic hostname TLV. Dynamic hostname +mapping determined as described in `2763`, Dynamic Hostname +Exchange Mechanism for IS-IS. + +</div> + +<div class="cfgcmd"> + +set protocols isis level \<level-1[|level-1-2|](##SUBST##|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. + +</div> + +<div class="cfgcmd"> + +set protocols isis lsp-mtu \<size\> + +This command configures the maximum size of generated +`LSPs (Link State PDUs)`, in bytes. The size range is 128 to 4352. + +</div> + +<div class="cfgcmd"> + +set protocols isis metric-style \<narrow[|transition|](##SUBST##|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. + +</div> + +<div class="cfgcmd"> + +set protocols isis purge-originator + +This command enables `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. + +</div> + +<div class="cfgcmd"> + +set protocols isis set-attached-bit + +This command sets ATT bit to 1 in Level1 LSPs. It is described in `3787`. + +</div> + +<div class="cfgcmd"> + +set protocols isis set-overload-bit + +This command sets overload bit to avoid any transit traffic through this +router. It is described in `3787`. + +</div> + +<div class="cfgcmd"> + +set protocols isis name default-information originate \<ipv4|ipv6\> +level-1 + +This command will generate a default-route in L1 database. + +</div> + +<div class="cfgcmd"> + +set protocols isis name default-information originate \<ipv4|ipv6\> +level-2 + +This command will generate a default-route in L2 database. + +</div> + +<div class="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 `5443`. By +default all interfaces operational in IS-IS are enabled for synchronization. +Loopbacks are exempt. + +</div> + +<div class="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. + +</div> + +#### Interface Configuration + +<div class="cfgcmd"> + +set protocols isis interface \<interface\> circuit-type +\<level-1[|level-1-2|](##SUBST##|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 + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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 +`3719`. This helps to prevent a premature adjacency Up state when one +routing devices MTU does not meet the requirements to establish the adjacency. + +</div> + +<div class="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). + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols isis interface \<interface\> passive + +This command configures the passive mode for this interface. + +</div> + +<div class="cfgcmd"> + +set protocols isis interface \<interface\> password +plaintext-password \<text\> + +This command configures the authentication password for the interface. + +</div> + +<div class="cfgcmd"> + +set protocols isis interface \<interface\> priority \<number\> + +This command sets priority for the interface for +`DIS (Designated Intermediate System)` election. The priority +range is 0 to 127. + +</div> + +<div class="cfgcmd"> + +set protocols isis interface \<interface\> psnp-interval +\<number\> + +This command sets PSNP interval in seconds. The interval range is 0 +to 127. + +</div> + +<div class="cfgcmd"> + +set protocols isis interface \<interface\> +no-three-way-handshake + +This command disables Three-Way Handshake for P2P adjacencies which +described in `5303`. Three-Way Handshake is enabled by default. + +</div> + +<div class="cfgcmd"> + +set protocols isis interface \<interface\> ldp-sync disable + +This command disables IGP-LDP sync for this specific interface. + +</div> + +<div class="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. + +</div> + +#### Route Redistribution + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +#### Timers + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols isis spf-delay-ietf holddown \<milliseconds\> + +</div> + +<div class="cfgcmd"> + +set protocols isis spf-delay-ietf init-delay +\<milliseconds\> + +</div> + +<div class="cfgcmd"> + +set protocols isis spf-delay-ietf long-delay +\<milliseconds\> + +</div> + +<div class="cfgcmd"> + +set protocols isis spf-delay-ietf short-delay +\<milliseconds\> + +</div> + +<div class="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 `8405`. + +</div> + +## 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..8b729d8c --- /dev/null +++ b/docs/configuration/protocols/md-mpls.md @@ -0,0 +1,419 @@ +# MPLS + +`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)](https://en.wikipedia.org/wiki/Multiprotocol_Label_Switching). + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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). + +</div> + +## Label Distribution Protocol + +The `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 `5036`. + +`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 + +<div class="cfgcmd"> + +set protocols mpls interface \<interface\> + +Use this command to enable MPLS processing on the interface you define. + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp interface \<interface\> + +Use this command to enable LDP on the interface you define. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp discovery transport-ipv4-address \<address\> + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp discovery transport-ipv6-address \<address\> + +Use this command to set the IPv4 or IPv6 transport-address used by LDP. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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). + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp discovery hello-ipv4-interval \<seconds\> + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp discovery hello-ipv4-holdtime \<seconds\> + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp discovery hello-ipv6-interval \<seconds\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp discovery session-ipv4-holdtime \<seconds\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp import ipv4 import-filter filter-access-list +\<access list number\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp export ipv4 export-filter filter-access-list +\<access list number\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp export ipv4 explicit-null + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp allocation ipv4 access-list +\<access list number\> + +</div> + +<div class="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. + +</div> + +<div class="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 +`7552`. + +</div> + +<div class="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 `5036`. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp targeted-neighbor ipv4 enable + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp targeted-neighbor ipv4 address \<address\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp targeted-neighbor ipv4 hello-holdtime +\<seconds\> + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp targeted-neighbor ipv4 hello-interval +\<seconds\> + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp targeted-neighbor ipv6 hello-holdtime +\<seconds\> + +</div> + +<div class="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. + +</div> + +### 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 + +<div class="opcmd"> + +show mpls ldp binding + +Use this command to see the Label Information Base. + +</div> + +<div class="opcmd"> + +show mpls ldp discovery + +Use this command to see discovery hello information + +</div> + +<div class="opcmd"> + +show mpls ldp interface + +Use this command to see LDP interface information + +</div> + +<div class="opcmd"> + +show mpls ldp neighbor + +Use this command to see LDP neighbor information + +</div> + +<div class="opcmd"> + +show mpls ldp neighbor detail + +Use this command to see detailed LDP neighbor information + +</div> + +### Reset + +<div class="opcmd"> + +reset mpls ldp neighbor \<IPv4 or IPv6 address\> + +Use this command to reset an LDP neighbor/TCP session that is established + +</div> diff --git a/docs/configuration/protocols/md-ospf.md b/docs/configuration/protocols/md-ospf.md new file mode 100644 index 00000000..a70bd840 --- /dev/null +++ b/docs/configuration/protocols/md-ospf.md @@ -0,0 +1,1772 @@ +# OSPF + +`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 `2328` (1998) +for IPv4. Updates for IPv6 are specified as OSPF Version 3 in `5340` +(2008). OSPF supports the `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. + +<div class="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 `set protocols ospf interface <interface> area <x.x.x.x | x>` + +</div> + +<div class="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). + +</div> + +<div class="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! + +</div> + +#### Optional + +<div class="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 `always` keyword is given then the default is always +advertised, even when there is no default present in the routing table. +The argument `route-map` specifies to advertise the default route +if the route map is satisfied. + +</div> + +<div class="cfgcmd"> + +set protocols ospf distance global \<distance\> + +This command change distance value of OSPF globally. +The distance range is 1 to 255. + +</div> + +<div class="cfgcmd"> + +set protocols ospf distance ospf \<external[|inter-area|](##SUBST##|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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Routes with a distance of 255 are effectively disabled and not +installed into the kernel. + +</div> + +</div> + +<div class="cfgcmd"> + +set protocols ospf log-adjacency-changes \[detail\] + +This command allows to log changes in adjacency. With the optional +`detail` argument, all changes in adjacency status are shown. +Without `detail`, only changes to full or regressions are shown. + +</div> + +<div class="cfgcmd"> + +set protocols ospf max-metric router-lsa +\<administrative[|on-shutdown \<seconds\>|](##SUBST##|on-shutdown <seconds>|)on-startup \<seconds\>\> + +This enables `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 +`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 `on-startup <seconds>` command +and/or for a period of seconds prior to shutdown with the +`on-shutdown <seconds>` command. The time range is 5 to 86400. + +</div> + +<div class="cfgcmd"> + +set protocols ospf parameters abr-type +\<cisco[|ibm|](##SUBST##|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 `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 <span class="title-ref">ospf-shortcut-abr-02.txt</span> + +</div> + +<div class="cfgcmd"> + +set protocols ospf parameters rfc1583-compatibility + +`2328`, the successor to `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. + +</div> + +<div class="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 <span class="title-ref">disable</span> option allows to exclude interface from passive state. +This command is used if the command `passive-interface default` was +configured. + +</div> + +<div class="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 `passive disable` flag for the specific interface. + +</div> + +<div class="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). + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols ospf timers throttle spf +\<delay[|initial-holdtime|](##SUBST##|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. `delay` sets the +initial SPF schedule delay in milliseconds. The default value is 200 ms. +`initial-holdtime` sets the minimum hold time between two +consecutive SPF calculations. The default value is 1000 ms. +`max-holdtime` sets the maximum wait time between two +consecutive SPF calculations. The default value is 10000 ms. + +</div> + +<div class="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 `5443`. By +default all interfaces operational in OSPF are enabled for synchronization. +Loopbacks are exempt. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols ospf capability opaque + +ospfd supports Opaque LSA `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) + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +</div> + +#### Area Configuration + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols ospf area \<number\> area-type nssa translate +\<always[|candidate|](##SUBST##|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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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 +`cost` specifies the aggregated link metric. The metric range is 0 +to 16777215. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols ospf area \<number\> shortcut \<default[|disable|](##SUBST##|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. + +</div> + +<div class="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. + +</div> + +#### Interface Configuration + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols ospf interface \<interface\> bfd + +This command enables `BFD (Bidirectional Forwarding Detection)` on +this OSPF link interface. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols ospf interface \<interface\> ldp-sync disable + +This command disables IGP-LDP sync for this specific interface. + +</div> + +<div class="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. + +</div> + +#### 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. + +<div class="cfgcmd"> + +set protocols ospf aggregation timer \<seconds\> + +Configure aggregation delay timer interval. + +Summarisation starts only after this delay timer expiry. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +#### Graceful Restart + +<div class="cfgcmd"> + +set protocols ospf graceful-restart \[grace-period (1-1800)\] + +Configure Graceful Restart `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. + +</div> + +<div class="cfgcmd"> + +set protocols ospf graceful-restart helper enable \[router-id A.B.C.D\] + +Configure Graceful Restart `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. + +</div> + +<div class="cfgcmd"> + +set protocols ospf graceful-restart helper no-strict-lsa-checking + +By default <span class="title-ref">strict-lsa-checking</span> is configured then the helper will abort +the Graceful Restart when a LSA change occurs which affects the restarting +router. + +This command disables it. + +</div> + +<div class="cfgcmd"> + +set protocols ospf graceful-restart helper supported-grace-time + +Supports as HELPER for configured grace period. + +</div> + +<div class="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. + +</div> + +#### 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. + +<div class="cfgcmd"> + +set protocols ospf neighbor \<A.B.C.D\> + +This command specifies the IP address of the neighboring device. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +#### Redistribution Configuration + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols ospf default-metric \<number\> + +This command specifies the default metric value of redistributed routes. +The metric range is 0 to 16777214. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +#### Operational Mode Commands + +<div class="opcmd"> + +show ip ospf neighbor + +This command displays the neighbors status. + +</div> + +``` 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 +``` + +<div class="opcmd"> + +show ip ospf neighbor detail + +This command displays the neighbors information in a detailed form, not +just a summary table. + +</div> + +``` 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 +``` + +<div class="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. + +</div> + +<div class="opcmd"> + +show ip ospf neighbor \<interface\> + +This command displays the neighbors status for a neighbor on the specified +interface. + +</div> + +<div class="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. + +</div> + +``` 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 +``` + +<div class="opcmd"> + +show ip ospf route \[detail\] + +This command displays the OSPF routing table, as determined by the most +recent SPF calculation. With the optional `detail` argument, +each route item's advertiser router and network attribute will be shown. + +</div> + +``` 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. + +<div class="opcmd"> + +show ip ospf border-routers + +This command displays a table of paths to area boundary and autonomous +system boundary routers. + +</div> + +<div class="opcmd"> + +show ip ospf database + +This command displays a summary table with a database contents (LSA). + +</div> + +``` 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] +``` + +<div class="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. + +`adv-router <A.B.C.D>` – router id, which link advertisements need +to be reviewed. + +`self-originate` displays only self-originated LSAs from the local +router. + +</div> + +``` 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 +``` + +<div class="opcmd"> + +show ip ospf database max-age + +This command displays LSAs in MaxAge list. + +</div> + +#### 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 +``` + +## OSPFv3 (IPv6) + +### Configuration + +#### 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. + +<div class="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. + +</div> + +<div class="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! + +</div> + +#### Optional + +<div class="cfgcmd"> + +set protocols ospfv3 distance global \<distance\> + +This command change distance value of OSPFv3 globally. +The distance range is 1 to 255. + +</div> + +<div class="cfgcmd"> + +set protocols ospfv3 distance ospfv3 +\<external[|inter-area|](##SUBST##|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. + +</div> + +#### Area Configuration + +<div class="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. + +</div> + +<div class="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. + +</div> + +#### Interface Configuration + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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). + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +#### Graceful Restart + +<div class="cfgcmd"> + +set protocols ospfv3 graceful-restart \[grace-period (1-1800)\] + +Configure Graceful Restart `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. + +</div> + +<div class="cfgcmd"> + +set protocols ospfv3 graceful-restart helper enable \[router-id A.B.C.D\] + +Configure Graceful Restart `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. + +</div> + +<div class="cfgcmd"> + +set protocols ospfv3 graceful-restart helper lsa-check-disable + +By default <span class="title-ref">strict-lsa-checking</span> is configured then the helper will abort +the Graceful Restart when a LSA change occurs which affects the restarting +router. + +This command disables it. + +</div> + +<div class="cfgcmd"> + +set protocols ospfv3 graceful-restart helper supported-grace-time + +Supports as HELPER for configured grace period. + +</div> + +<div class="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. + +</div> + +#### Redistribution Configuration + +<div class="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. + +</div> + +<div class="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. + +</div> + +#### Operational Mode Commands + +<div class="opcmd"> + +show ipv6 ospfv3 neighbor + +This command displays the neighbors status. + +</div> + +<div class="opcmd"> + +show ipv6 ospfv3 neighbor detail + +This command displays the neighbors information in a detailed form, not +just a summary table. + +</div> + +<div class="opcmd"> + +show ipv6 ospfv3 neighbor drchoice + +This command displays the neighbor DR choice information. + +</div> + +<div class="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 +`prefix` this command shows connected prefixes to advertise. + +</div> + +<div class="opcmd"> + +show ipv6 ospfv3 route + +This command displays the OSPF routing table, as determined by the most +recent SPF calculation. + +</div> + +<div class="opcmd"> + +show ipv6 ospfv3 border-routers + +This command displays a table of paths to area boundary and autonomous +system boundary routers. + +</div> + +<div class="opcmd"> + +show ipv6 ospfv3 database + +This command displays a summary table with a database contents (LSA). + +</div> + +<div class="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. + +</div> + +<div class="opcmd"> + +show ipv6 ospfv3 redistribute + +This command displays external information redistributed into OSPFv3 + +</div> + +#### 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 +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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 `T1483`. + +</div> + +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..2f31de95 --- /dev/null +++ b/docs/configuration/protocols/md-pim.md @@ -0,0 +1,345 @@ +lastproofread +2023-11-13 + +# PIM – Protocol Independent Multicast + +VyOS supports `PIM-SM (PIM Sparse Mode)` as well as +`IGMP (Internet Group Management Protocol)` v2 and v3 + +`PIM (Protocol Independent Multicast)` must be configured in every +interface of every participating router. Every router must also have the +location of the Rendevouz Point manually configured. Then, unidirectional +shared trees rooted at the Rendevouz Point will automatically be built +for multicast distribution. + +Traffic from multicast sources will go to the Rendezvous Point, and +receivers will pull it from a shared tree using `IGMP (Internet +Group Management Protocol)`. + +Multicast receivers will talk IGMP to their local router, so, besides +having PIM configured in every router, IGMP must also be configured in +any router where there could be a multicast receiver locally connected. + +VyOS supports both IGMP version 2 and version 3 (which allows +source-specific multicast). + +## PIM-SM - PIM Sparse Mode + +<div class="cfgcmd"> + +set protocols pim ecmp + +If PIM has the a choice of ECMP nexthops for a particular +`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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols pim rp \<address\> group \<group\> + +In order to use PIM, it is necessary to configure a `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. + +</div> + +<div class="cfgcmd"> + +set protocols pim rp keep-alive-timer \<n\> + +Modify the time out value for a S,G flow from 1-65535 seconds at +`RP (Rendezvous Point)`. The normal keepalive period for the KAT(S,G) +defaults to 210 seconds. However, at the `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 `7761#section-4.1` for details. + +</div> + +<div class="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 `RPF (Reverse Path Forwarding)` lookup +if this option is not set (default). + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols pim ssm prefix-list \<list\> + +Specify a range of group addresses via a prefix-list that forces PIM to never +do `SSM (Source-Specific Multicast)` over. + +</div> + +### Interface specific commands + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols pim interface \<interface\> dr-priority \<n\> + +Set the `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. + +</div> + +<div class="cfgcmd"> + +set protocols pim interface \<interface\> hello \<n\> + +Set the PIM hello and hold interval for a interface. + +</div> + +<div class="cfgcmd"> + +set protocols pim interface \<interface\> no-bsm + +Tell PIM that we would not like to use this interface to process +bootstrap messages. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols pim interface \<interface\> passive + +Disable sending and receiving PIM control packets on the interface. + +<div class="cfgcmd"> + +set protocols pim interface \<interface\> source-address \<ip-address\> + +</div> + +If you have multiple addresses configured on a particular interface and would +like PIM to use a specific source address associated with that interface. + +</div> + +## IGMP - Internet Group Management Protocol) + +<div class="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. + +</div> + +### Interface specific commands + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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 `7761#section-4.1` has timed out. + +</div> + +<div class="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. + +</div> + +#### Example + +In the following example we can see a basic multicast setup: + +<img src="/_static/images/multicast-basic.webp" class="align-center" style="width:90.0%" alt="Network Topology Diagram" /> + +**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..6b3c00fc --- /dev/null +++ b/docs/configuration/protocols/md-pim6.md @@ -0,0 +1,122 @@ +# 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. + +<div class="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 `mld disable` is configured. + +</div> + +<div class="cfgcmd"> + +set protocols pim6 interface \<interface-name\> mld disable + +Disable MLD reports and query on the interface. + +</div> + +## Tuning commands + +You can also tune multicast with the following commands. + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols pim6 interface \<interface-name\> mld join \<multicast-address\> + +Use this command to allow the selected interface to join a multicast group. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols pim6 interface \<interface-name\> mld version \<version-number\> + +Set the MLD version used on this interface. The default value is 2. + +</div> + +### Configuration Example + +To enable MLD reports and query on interfaces <span class="title-ref">eth0</span> and \`eth1\`: + +``` none +set protocols pim6 interface eth0 +set protocols pim6 interface eth1 +``` + +The following configuration explicitly joins multicast group <span class="title-ref">ff15::1234</span> on interface <span class="title-ref">eth1</span> +and source-specific multicast group <span class="title-ref">ff15::5678</span> with source address <span class="title-ref">2001:db8::1</span> 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..1bd580ab --- /dev/null +++ b/docs/configuration/protocols/md-rip.md @@ -0,0 +1,361 @@ +lastproofread +2021-10-04 + +# RIP + +`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 `1058` +> - RIPv2 as described in `2453` + +## General Configuration + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols rip passive-interface interface default + +This command specifies all interfaces to passive mode. + +</div> + +## Optional Configuration + +<div class="cfgcmd"> + +set protocols rip default-distance \<distance\> + +This command change the distance value of RIP. The distance range is 1 to 255. + +> <div class="note"> +> +> <div class="title"> +> +> Note +> +> </div> +> +> Routes with a distance of 255 are effectively disabled and not +> installed into the kernel. +> +> </div> + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols rip default-information originate + +This command generate a default route into the RIP. + +</div> + +<div class="cfgcmd"> + +set protocols rip distribute-list access-list \<in|out\> \<number\> + +This command can be used to filter the RIP path using access lists. +`in` and `out` this is the direction in which the access +lists are applied. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols rip distribute-list prefix-list \<in|out\> \<name\> + +This command can be used to filter the RIP path using prefix lists. +`in` and `out` this is the direction in which the prefix +lists are applied. + +</div> + +<div class="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. + +</div> + +<div class="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 `redistribute static`. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +## Redistribution Configuration + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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 +`redistribute connected`. To modify connected routes metric +value, please use `redistribute connected metric`. + +</div> + +## Interfaces Configuration + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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 + +</div> + +<div class="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. + +</div> + +## Operational Mode Commands + +<div class="opcmd"> + +show ip rip + +This command displays RIP routes. + +</div> + +``` 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 +``` + +<div class="opcmd"> + +show ip rip status + +The command displays current RIP status. It includes RIP timer, filtering, +version, RIP enabled interface and RIP peer information. + +</div> + +``` 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..f41e4d59 --- /dev/null +++ b/docs/configuration/protocols/md-rpki.md @@ -0,0 +1,238 @@ +# RPKI + +> 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 + +`RPKI (Resource Public Key Infrastructure)` is a framework designed to +secure the Internet routing infrastructure. It associates BGP route +announcements with the correct originating `ASN (Autonomus System +Number)` which BGP routers can then use to check each route against the +corresponding `ROA (Route Origin Authorisation)` for validity. RPKI is +described in `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 `RTR (RPKI to Router)` protocol. There are several +open source implementations to choose from, such as NLNetLabs' [Routinator](https://www.nlnetlabs.nl/projects/rpki/routinator/) +(written in Rust), OpenBSD's [rpki-client](https://www.rpki-client.org/) (written in C), and [StayRTR](https://github.com/bgp/stayrtr/) (written +in Go). The RTR protocol is described in `8210`. + +<div class="tip"> + +<div class="title"> + +Tip + +</div> + +If you are new to these routing security technologies then there is an +[excellent guide to RPKI](https://rpki.readthedocs.io/) 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](https://rpki.readthedocs.io/en/latest/about/help.html) including "What can I do about my route +having an Invalid state?" + +</div> + +## Getting started + +First you will need to deploy an RPKI validator for your routers to use. NLnet +Labs provides a collection of [software](https://rpki.readthedocs.io/en/latest/ops/tools.html#relying-party-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 `DFZ +> (default-free zone)` at the start of 2024. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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 <span class="title-ref">notfound</span> by RPKI. For most ASNs this will involve +publishing ROAs via your `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](https://www.nlnetlabs.nl/projects/rpki/krill/) if this is a rabbit hole you need or especially want +to dive down. + +</div> + +### 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 + +<div class="cfgcmd"> + +set protocols rpki polling-period \<1-86400\> + +Define the time interval to update the local cache + +The default value is 300 seconds. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +### 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. + +<div class="cfgcmd"> + +set protocols rpki cache \<address\> ssh username \<user\> + +SSH username to establish an SSH connection to the cache server. + +</div> + +<div class="cfgcmd"> + +set protocols rpki cache \<address\> ssh private-key-file \<filepath\> + +Local path that includes the private key file of the router. + +</div> + +<div class="cfgcmd"> + +set protocols rpki cache \<address\> ssh public-key-file \<filepath\> + +Local path that includes the public key file of the router. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +When using SSH, private-key-file and public-key-file +are mandatory options. + +</div> + +## Example + +We can build route-maps for import based on these states. Here is a simple +RPKI configuration, where <span class="title-ref">routinator</span> 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 <span class="title-ref">invalid</span>, and set a higher +<span class="title-ref">local-preference</span> if the prefix is RPKI <span class="title-ref">valid</span> rather than merely +<span class="title-ref">notfound</span>. + +``` 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](https://isbgpsafeyet.com/) +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. diff --git a/docs/configuration/protocols/md-segment-routing.md b/docs/configuration/protocols/md-segment-routing.md new file mode 100644 index 00000000..24516103 --- /dev/null +++ b/docs/configuration/protocols/md-segment-routing.md @@ -0,0 +1,442 @@ +# 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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +## 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: + +<div class="note"> + +<div class="title"> + +Note + +</div> + +`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 + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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 +indentify it + +</div> + +<div class="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. + +</div> + +<div class="opcmd"> + +show isis segment-routing node + +Show detailed information about all learned Segment Routing Nodes + +</div> + +<div class="opcmd"> + +show isis route prefix-sid + +Show detailed information about prefix-sid and label learned + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +more information related IGP - `routing-isis` + +</div> + +## 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: + +<div class="cfgcmd"> + +set protocols ospf parameters opaque-lsa + +Enable the Opaque-LSA capability (rfc2370), necessary to transport label +on IGP + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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 +indentify it + +</div> + +<div class="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. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +more information related IGP - `routing-ospf` + +</div> + +## 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..dca76d53 --- /dev/null +++ b/docs/configuration/protocols/md-static.md @@ -0,0 +1,322 @@ +# 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 `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 + +<div class="cfgcmd"> + +set protocols static route \<subnet\> next-hop \<address\> + +Configure next-hop <span class="title-ref">\<address\></span> for an IPv4 static route. Multiple static +routes can be created. + +</div> + +<div class="cfgcmd"> + +set protocols static route \<subnet\> next-hop \<address\> disable + +Disable this IPv4 static route entry. + +</div> + +<div class="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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Routes with a distance of 255 are effectively disabled and not +installed into the kernel. + +</div> + +</div> + +<div class="cfgcmd"> + +set protocols static route6 \<subnet\> next-hop \<address\> + +Configure next-hop <span class="title-ref">\<address\></span> for an IPv6 static route. Multiple static +routes can be created. + +</div> + +<div class="cfgcmd"> + +set protocols static route6 \<subnet\> next-hop \<address\> disable + +Disable this IPv6 static route entry. + +</div> + +<div class="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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Routes with a distance of 255 are effectively disabled and not +installed into the kernel. + +</div> + +</div> + +<div class="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 <span class="title-ref">/</span> separator can be used to specify multiple segment instructions. + +Example: + +``` 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' +``` + +``` 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 +``` + +</div> + +### Interface Routes + +<div class="cfgcmd"> + +set protocols static route \<subnet\> interface +\<interface\> + +Allows you to configure the next-hop interface for an interface-based IPv4 +static route. <span class="title-ref">\<interface\></span> will be the next-hop interface where traffic is +routed for the given <span class="title-ref">\<subnet\></span>. + +</div> + +<div class="cfgcmd"> + +set protocols static route \<subnet\> interface +\<interface\> disable + +Disables interface-based IPv4 static route. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols static route6 \<subnet\> interface +\<interface\> + +Allows you to configure the next-hop interface for an interface-based IPv6 +static route. <span class="title-ref">\<interface\></span> will be the next-hop interface where traffic is +routed for the given <span class="title-ref">\<subnet\></span>. + +</div> + +<div class="cfgcmd"> + +set protocols static route6 \<subnet\> interface +\<interface\> disable + +Disables interface-based IPv6 static route. + +</div> + +<div class="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. + +</div> + +<div class="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 <span class="title-ref">/</span> separator can be used to specify multiple segment instructions. + +Example: + +``` none +set protocols static route6 2001:db8:1000::/36 interface eth0 segments '2001:db8:aaaa::7/2002::4/2002::3/2002::2' +``` + +</div> + +### Blackhole + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +### Alternate Routing Tables + +TBD + +Alternate routing tables are used with policy based routing by utilizing +`vrf`. + +# ARP + +`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 +`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](https://en.wikipedia.org/wiki/Address_Resolution_Protocol) table entries, the following commands are +implemented. + +## Configure + +<div class="cfgcmd"> + +set protocols static arp interface \<interface\> address \<host\> +mac \<mac\> + +This will configure a static ARP entry always resolving <span class="title-ref">\<address\></span> to +<span class="title-ref">\<mac\></span> for interface <span class="title-ref">\<interface\></span>. + +Example: + +``` none +set protocols static arp interface eth0 address 192.0.2.1 mac 01:23:45:67:89:01 +``` + +</div> + +## Operation + +<div class="opcmd"> + +show protocols static arp + +Display all known ARP table entries spanning across all interfaces + +</div> + +``` 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 +``` + +<div class="opcmd"> + +show protocols static arp interface eth1 + +Display all known ARP table entries on a given interface only (<span class="title-ref">eth1</span>): + +</div> + +``` 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 +``` diff --git a/docs/configuration/service/md-broadcast-relay.md b/docs/configuration/service/md-broadcast-relay.md new file mode 100644 index 00000000..2214ade3 --- /dev/null +++ b/docs/configuration/service/md-broadcast-relay.md @@ -0,0 +1,94 @@ +# 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 + +<div class="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. + +</div> + +<div class="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 <span class="title-ref">eth1</span> and <span class="title-ref">eth2</span> both interfaces need +to be added. + +</div> + +<div class="cfgcmd"> + +set service broadcast-relay id \<n\> address \<ipv4-address\> + +Set the source IP of forwarded packets, otherwise original senders address +is used. + +</div> + +<div class="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. + +</div> + +<div class="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: + +</div> + +<div class="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. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +You can run the UDP broadcast relay service on multiple routers +connected to a subnet. There is **NO** UDP broadcast relay packet storm! + +</div> + +## Example + +To forward all broadcast packets received on <span class="title-ref">UDP port 1900</span> on <span class="title-ref">eth3</span>, <span class="title-ref">eth4</span> +or <span class="title-ref">eth5</span> 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..db803cb4 --- /dev/null +++ b/docs/configuration/service/md-config-sync.md @@ -0,0 +1,121 @@ +# 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 + +<div class="cfgcmd"> + +set service config-sync secondary +\<address[|key|](##SUBST##|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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service config-sync mode \<load|set\> + +Two options are available for \`mode\`: either <span class="title-ref">load</span> and replace or <span class="title-ref">set</span> +the configuration section. + +</div> + +``` 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 <span class="title-ref">service +config-sync</span>, 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..011080a5 --- /dev/null +++ b/docs/configuration/service/md-conntrack-sync.md @@ -0,0 +1,380 @@ +# 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: + +`set service conntrack-sync interface eth0 peer 192.168.0.250` + +## Configuration + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service conntrack-sync expect-sync \<all[|ftp|](##SUBST##|ftp|)h323[|nfs|](##SUBST##|nfs|)sip|sqlnet\> + +Protocol for which expect entries need to be synchronized. + +</div> + +<div class="cfgcmd"> + +set service conntrack-sync failover-mechanism vrrp sync-group \<group\> + +Failover mechanism to use for conntrack-sync. + +Only VRRP is supported. Required option. + +</div> + +<div class="cfgcmd"> + +set service conntrack-sync ignore-address \<x.x.x.x\> + +IP addresses or networks for which local conntrack entries will not be synced + +</div> + +<div class="cfgcmd"> + +set service conntrack-sync interface \<name\> + +Interface to use for syncing conntrack entries. + +</div> + +<div class="cfgcmd"> + +set service conntrack-sync interface \<name\> port \<port\> + +Port number used by connection. + +</div> + +<div class="cfgcmd"> + +set service conntrack-sync listen-address \<ipv4address\> + +Local IPv4 addresses for service to listen on. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service conntrack-sync sync-queue-size \<size\> + +Queue size for syncing conntrack entries in MB. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +<div class="cfgcmd"> + +set service conntrack-sync disable-syslog + +Disable connection logging via Syslog. + +</div> + +<div class="cfgcmd"> + +set service conntrack-sync startup-resync + +Order conntrackd to request a complete conntrack table resync against +the other node at startup. + +</div> + +## Operation + +<div class="opcmd"> + +show conntrack table ipv4 + +Make sure conntrack is enabled by running and show connection tracking table. + +``` 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 +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. `set firewall state-policy established action accept` + +</div> + +</div> + +<div class="opcmd"> + +show conntrack-sync cache external + +Show connection syncing external cache entries + +</div> + +<div class="opcmd"> + +show conntrack-sync cache internal + +Show connection syncing internal cache entries + +</div> + +<div class="opcmd"> + +show conntrack-sync statistics + +Retrieve current statistics of connection tracking subsystem. + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show conntrack-sync status + +Retrieve current status of connection tracking subsystem. + +``` 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 +``` + +</div> + +## Example + +The next example is a simple configuration of conntrack-sync. + +<figure> +<img src="/_static/images/service_conntrack_sync-schema.webp" alt="Conntrack Sync Example" /> +</figure> + +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..2e28b85d --- /dev/null +++ b/docs/configuration/service/md-console-server.md @@ -0,0 +1,206 @@ +# 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: `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. + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service console-server device \<device\> description \<string\> + +A user friendly description identifying the connected peripheral. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service console-server device \<device\> speed +\[ 300 | 1200 | 2400 | 4800 | 9600 | 19200 | 38400 | 57600 | 115200 \] + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +</div> + +### 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. + +<div class="cfgcmd"> + +set service console-server device \<device\> ssh port \<port\> + +Accept SSH connections for the given <span class="title-ref">\<device\></span> on TCP port <span class="title-ref">\<port\></span>. +After successfull authentication the user will be directly dropped to +the connected serial device. + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +Multiple users can connect to the same serial device but only +one is allowed to write to the console port. + +</div> + +</div> + +## Operation + +<div class="opcmd"> + +show console-server ports + +Show configured serial ports and their respective interface configuration. + +``` none +vyos@vyos:~$ show console-server ports + usb0b2.4p1.0 on /dev/serial/by-bus/usb0b2.4p1.0@ at 9600n +``` + +</div> + +<div class="opcmd"> + +show console-server user + +Show currently connected users. + +``` none +vyos@vyos:~$ show console-server user + usb0b2.4p1.0 up vyos@localhost +``` + +</div> + +<div class="opcmd"> + +connect console \<device\> + +Locally connect to serial port identified by <span class="title-ref">\<device\></span>. + +``` none +vyos@vyos-r1:~$ connect console usb0b2.4p1.0 +[Enter `^Ec?' for help] +[-- MOTD -- VyOS Console Server] + +vyos-r2 login: +``` + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +Multiple users can connect to the same serial device but only +one is allowed to write to the console port. + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +The sequence `^Ec?` translates to: `Ctrl+E c ?`. To quit +the session use: `Ctrl+E c .` + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +If `alias` is set, it can be used instead of the device when +connecting. + +</div> + +</div> + +<div class="opcmd"> + +show log console-server + +Show the console server log. + +</div> diff --git a/docs/configuration/service/md-dhcp-relay.md b/docs/configuration/service/md-dhcp-relay.md new file mode 100644 index 00000000..2cf304bf --- /dev/null +++ b/docs/configuration/service/md-dhcp-relay.md @@ -0,0 +1,242 @@ +# 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 + +<div class="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`. + +</div> + +<div class="cfgcmd"> + +set service dhcp-relay listen-interface \<interface\> + +Interface for DHCP Relay Agent to listen for requests. + +</div> + +<div class="cfgcmd"> + +set service dhcp-relay upstream-interface \<interface\> + +Interface for DHCP Relay Agent to forward requests out. + +</div> + +<div class="cfgcmd"> + +set service dhcp-relay server \<server\> + +Configure IP address of the DHCP <span class="title-ref">\<server\></span> which will handle the relayed +packets. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service dhcp-relay disable + +Disable dhcp-relay service. + +</div> + +#### Options + +<div class="cfgcmd"> + +set service dhcp-relay relay-options hop-count \<count\> + +Set the maximum hop <span class="title-ref">\<count\></span> before packets are discarded. Range 0...255, +default 10. + +</div> + +<div class="cfgcmd"> + +set service dhcp-relay relay-options max-size \<size\> + +Set maximum <span class="title-ref">\<size\></span> 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. + +</div> + +<div class="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. + +</div> + +### 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> +<img src="/_static/images/service_dhcp-relay01.webp" alt="DHCP relay example" /> +<figcaption aria-hidden="true">DHCP relay example</figcaption> +</figure> + +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 + +<div class="opcmd"> + +restart dhcp relay-agent + +Restart DHCP relay service + +</div> + +## IPv6 relay + +### Configuration + +<div class="cfgcmd"> + +set service dhcpv6-relay listen-interface \<interface\> + +Set eth1 to be the listening interface for the DHCPv6 relay. + +Multiple interfaces may be specified. + +</div> + +<div class="cfgcmd"> + +set service dhcpv6-relay upstream-interface \<interface\> +address \<server\> + +Specifies an upstream network <span class="title-ref">\<interface\></span> from which replies from +<span class="title-ref">\<server\></span> and other relay agents will be accepted. + +</div> + +<div id="dhcp-relay:ipv6_options"> + +<div class="cfgcmd"> + +set service dhcpv6-relay disable + +Disable dhcpv6-relay service. + +</div> + +</div> + +#### Options + +<div class="cfgcmd"> + +set service dhcpv6-relay max-hop-count \<count\> + +Set maximum hop count before packets are discarded, default: 10 + +</div> + +<div class="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. + +</div> + +### Example + +- DHCPv6 requests are received by the router on <span class="title-ref">listening interface</span> `eth1` +- Requests are forwarded through `eth2` as the <span class="title-ref">upstream interface</span> +- External DHCPv6 server is at 2001:db8::4 + +<figure> +<img src="/_static/images/service_dhcpv6-relay01.webp" alt="DHCPv6 relay example" /> +<figcaption aria-hidden="true">DHCPv6 relay example</figcaption> +</figure> + +The generated configuration will look like: + +``` none +commit +show service dhcpv6-relay + listen-interface eth1 { + } + upstream-interface eth2 { + address 2001:db8::4 + } +``` + +### Operation + +<div class="opcmd"> + +restart dhcpv6 relay-agent + +Restart DHCPv6 relay agent immediately. + +</div> diff --git a/docs/configuration/service/md-dhcp-server.md b/docs/configuration/service/md-dhcp-server.md new file mode 100644 index 00000000..f77daec3 --- /dev/null +++ b/docs/configuration/service/md-dhcp-server.md @@ -0,0 +1,1128 @@ +# 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 + +<div class="cfgcmd"> + +set service dhcp-server hostfile-update + +Create DNS record per client lease, by adding clients to /etc/hosts file. +Entry will have format: <span class="title-ref">\<shared-network-name\>\_\<hostname\>.\<domain-name\></span> + +</div> + +<div class="cfgcmd"> + +set service dhcp-server host-decl-name + +Will drop <span class="title-ref">\<shared-network-name\>\_</span> from client DNS record, using only the +host declaration name and domain: <span class="title-ref">\<hostname\>.\<domain-name\></span> + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service dhcp-server shared-network-name \<name\> +name-server \<address\> + +Inform client that the DNS server can be found at <span class="title-ref">\<address\></span>. + +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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +#### Individual Client Subnet + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service dhcp-server shared-network-name \<name\> subnet \<subnet\> +default-router \<address\> + +This is a configuration parameter for the <span class="title-ref">\<subnet\></span>, saying that as part of +the response, tell the client that the default gateway can be reached at +<span class="title-ref">\<address\></span>. + +</div> + +<div class="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 <span class="title-ref">\<address\></span>. + +Multiple DNS servers can be defined. + +</div> + +<div class="cfgcmd"> + +set service dhcp-server shared-network-name \<name\> subnet \<subnet\> +lease \<time\> + +Assign the IP address to this machine for <span class="title-ref">\<time\></span> seconds. + +The default value is 86400 seconds which corresponds to one day. + +</div> + +<div class="cfgcmd"> + +set service dhcp-server shared-network-name \<name\> subnet \<subnet\> +range \<n\> start \<address\> + +Create DHCP address range with a range id of <span class="title-ref">\<n\></span>. DHCP leases are taken +from this pool. The pool starts at address <span class="title-ref">\<address\></span>. + +</div> + +<div class="cfgcmd"> + +set service dhcp-server shared-network-name \<name\> subnet \<subnet\> +range \<n\> stop \<address\> + +Create DHCP address range with a range id of <span class="title-ref">\<n\></span>. DHCP leases are taken +from this pool. The pool stops with address <span class="title-ref">\<address\></span>. + +</div> + +<div class="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. + +</div> + +<div class="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). + +</div> + +<div class="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). + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service dhcp-server shared-network-name \<name\> subnet \<subnet\> +enable-failover + +Enable DHCP failover configuration for this address pool. + +</div> + +#### 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: + +<div class="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 <span class="title-ref">active-active</span> + +</div> + +<div class="cfgcmd"> + +set service dhcp-server high-availability source-address \<address\> + +Local IP <span class="title-ref">\<address\></span> used when communicating to the HA peer. + +</div> + +<div class="cfgcmd"> + +set service dhcp-server high-availability remote \<address\> + +Remote peer IP <span class="title-ref">\<address\></span> of the second DHCP server in this HA +cluster. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service dhcp-server high-availability status \<primary +| secondary\> + +The primary and secondary statements determines whether the server is primary +or secondary. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +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. + +</div> + +</div> + +#### 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. + +<div class="cfgcmd"> + +set service dhcp-server shared-network-name \<name\> subnet +\<subnet\> static-mapping \<description\> mac-address \<address\> + +Create a new DHCP static mapping named <span class="title-ref">\<description\></span> which is valid for +the host identified by its MAC <span class="title-ref">\<address\></span>. + +</div> + +<div class="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 <span class="title-ref">\<description\></span>. IP +address must be inside the <span class="title-ref">\<subnet\></span> which is defined but can be outside +the dynamic range created with `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. + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +This is the equivalent of the host block in dhcpd.conf of +isc-dhcpd. + +</div> + +</div> + +**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 + +<table> +<colgroup> +<col style="width: 11%" /> +<col style="width: 6%" /> +<col style="width: 22%" /> +<col style="width: 39%" /> +<col style="width: 19%" /> +</colgroup> +<thead> +<tr> +<th>Setting name</th> +<th>Option number</th> +<th>ISC-DHCP Option name</th> +<th>Option description</th> +<th>Multi</th> +</tr> +</thead> +<tbody> +<tr> +<td>client-prefix-length</td> +<td>1</td> +<td>subnet-mask</td> +<td>Specifies the clients subnet mask as per RFC 950. If unset, +subnet declaration is used.</td> +<td>N</td> +</tr> +<tr> +<td>time-offset</td> +<td>2</td> +<td>time-offset</td> +<td>Offset of the client's subnet in seconds from Coordinated +Universal Time (UTC)</td> +<td>N</td> +</tr> +<tr> +<td>default-router</td> +<td>3</td> +<td>routers</td> +<td>IPv4 address of router on the client's subnet</td> +<td>N</td> +</tr> +<tr> +<td>time-server</td> +<td>4</td> +<td>time-servers</td> +<td>RFC 868 time server IPv4 address</td> +<td>Y</td> +</tr> +<tr> +<td>name-server</td> +<td>6</td> +<td>domain-name-servers</td> +<td>DNS server IPv4 address</td> +<td>Y</td> +</tr> +<tr> +<td>domain-name</td> +<td>15</td> +<td>domain-name</td> +<td>Client domain name</td> +<td>Y</td> +</tr> +<tr> +<td>ip-forwarding</td> +<td>19</td> +<td>ip-forwarding</td> +<td>Enable IP forwarding on client</td> +<td>N</td> +</tr> +<tr> +<td>ntp-server</td> +<td>42</td> +<td>ntp-servers</td> +<td>IP address of NTP server</td> +<td>Y</td> +</tr> +<tr> +<td>wins-server</td> +<td>44</td> +<td>netbios-name-servers</td> +<td>NetBIOS over TCP/IP name server</td> +<td>Y</td> +</tr> +<tr> +<td>server-identifier</td> +<td>54</td> +<td>dhcp-server-identifier</td> +<td>IP address for DHCP server identifier</td> +<td>N</td> +</tr> +<tr> +<td>bootfile-server</td> +<td>siaddr</td> +<td>next-server</td> +<td>IPv4 address of next bootstrap server</td> +<td>N</td> +</tr> +<tr> +<td>tftp-server-name</td> +<td>66</td> +<td>tftp-server-name</td> +<td>Name or IPv4 address of TFTP server</td> +<td>N</td> +</tr> +<tr> +<td>bootfile-name</td> +<td>67</td> +<td>bootfile-name, filename</td> +<td>Bootstrap file name</td> +<td>N</td> +</tr> +<tr> +<td>bootfile-size</td> +<td>13</td> +<td>boot-size</td> +<td>Boot image length in 512-octet blocks</td> +<td>N</td> +</tr> +<tr> +<td>smtp-server</td> +<td>69</td> +<td>smtp-server</td> +<td>IP address of SMTP server</td> +<td>Y</td> +</tr> +<tr> +<td>pop-server</td> +<td>70</td> +<td>pop-server</td> +<td>IP address of POP3 server</td> +<td>Y</td> +</tr> +<tr> +<td>domain-search</td> +<td>119</td> +<td>domain-search</td> +<td>Client domain search</td> +<td>Y</td> +</tr> +<tr> +<td>static-route</td> +<td>121, 249</td> +<td>rfc3442-static-route, windows-static-route</td> +<td>Classless static route</td> +<td>N</td> +</tr> +<tr> +<td>wpad-url</td> +<td>252</td> +<td>wpad-url, wpad-url code 252 = text</td> +<td>Web Proxy Autodiscovery (WPAD) URL</td> +<td>N</td> +</tr> +<tr> +<td>lease</td> +<td></td> +<td>default-lease-time, max-lease-time</td> +<td>Lease timeout in seconds (default: 86400)</td> +<td>N</td> +</tr> +<tr> +<td>range</td> +<td></td> +<td>range</td> +<td>DHCP lease range</td> +<td>Y</td> +</tr> +<tr> +<td>exclude</td> +<td></td> +<td></td> +<td>IP address to exclude from DHCP lease range</td> +<td>Y</td> +</tr> +<tr> +<td>failover</td> +<td></td> +<td></td> +<td>DHCP failover parameters</td> +<td></td> +</tr> +<tr> +<td>static-mapping</td> +<td></td> +<td></td> +<td>Name of static mapping</td> +<td>Y</td> +</tr> +</tbody> +</table> + +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 `dhcp-dns-quick-start` configuration. + +#### 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 <span class="title-ref">192.0.2.254</span> +- The primary DHCP server named dhcp-primary uses address <span class="title-ref">192.168.189.252</span> +- The secondary DHCP server named dhcp-secondary uses address <span class="title-ref">192.168.189.253</span> +- DHCP range spans from <span class="title-ref">192.168.189.10</span> - <span class="title-ref">192.168.189.250</span> + +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' +``` + +#### 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 + +<div class="opcmd"> + +show log dhcp server + +Show DHCP server daemon log file + +</div> + +<div class="opcmd"> + +show log dhcp client + +Show logs from all DHCP client processes. + +</div> + +<div class="opcmd"> + +show log dhcp client interface \<interface\> + +Show logs from specific <span class="title-ref">interface</span> DHCP client process. + +</div> + +<div class="opcmd"> + +restart dhcp server + +Restart the DHCP server + +</div> + +<div class="opcmd"> + +show dhcp server statistics + +Show the DHCP server statistics: + +</div> + +``` none +vyos@vyos:~$ show dhcp server statistics +Pool Size Leases Available Usage +----------- ------ -------- ----------- ------- +dhcpexample 99 2 97 2% +``` + +<div class="opcmd"> + +show dhcp server statistics pool \<pool\> + +Show the DHCP server statistics for the specified pool. + +</div> + +<div class="opcmd"> + +show dhcp server leases + +Show statuses of all active leases: + +</div> + +``` 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:~$ +``` + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +Static mappings aren't shown. To show all states, use +`show dhcp server leases state all`. + +</div> + +<div class="opcmd"> + +show dhcp server leases origin \[local | remote\] + +Show statuses of all active leases granted by local (this server) or +remote (failover server): + +</div> + +``` 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:~$ +``` + +<div class="opcmd"> + +show dhcp server leases pool \<pool\> + +Show only leases in the specified pool. + +</div> + +``` 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:~$ +``` + +<div class="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) + +</div> + +<div class="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) + +</div> + +## IPv6 server + +VyOS also provides DHCPv6 server functionality which is described in this +section. + +### Configuration + +<div class="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`. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service dhcpv6-server shared-network-name \<name\> subnet +\<prefix\> nis-domain \<domain-name\> + +A `NIS (Network Information Service)` domain can be set to be used for +DHCPv6 clients. + +</div> + +<div class="cfgcmd"> + +set service dhcpv6-server shared-network-name \<name\> subnet +\<prefix\> nisplus-domain \<domain-name\> + +The procedure to specify a `NIS+ (Network Information Service Plus)` +domain is similar to the NIS domain one: + +</div> + +<div class="cfgcmd"> + +set service dhcpv6-server shared-network-name \<name\> subnet +\<prefix\> nis-server \<address\> + +Specify a NIS server address for DHCPv6 clients. + +</div> + +<div class="cfgcmd"> + +set service dhcpv6-server shared-network-name \<name\> subnet +\<prefix\> nisplus-server \<address\> + +Specify a NIS+ server address for DHCPv6 clients. + +</div> + +<div class="cfgcmd"> + +set service dhcpv6-server shared-network-name \<name\> subnet +\<prefix\> sip-server \<address | fqdn\> + +Specify a `SIP (Session Initiation Protocol)` server by IPv6 +address of Fully Qualified Domain Name for all DHCPv6 clients. + +</div> + +<div class="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. + +</div> + +#### Prefix Delegation + +<div class="note"> + +<div class="title"> + +Note + +</div> + +VyOS =\< 1.4.3 does not add the prefixes to the routing table. + +</div> + +To hand out individual prefixes to your clients the following configuration is +used: + +<div class="cfgcmd"> + +set service dhcpv6-server shared-network-name \<name\> subnet +\<prefix\> prefix-delegation start \<address\> prefix-length \<length\> + +Hand out prefixes of size <span class="title-ref">\<length\></span> to clients in subnet <span class="title-ref">\<prefix\></span> when +they request for prefix delegation. + +</div> + +<div class="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. + +</div> + +**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 + } + } +``` + +#### 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` + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +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`. + +</div> + +``` 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 + } + } +``` + +### Operation Mode + +<div class="opcmd"> + +show log dhcpv6 server + +Show DHCPv6 server daemon log file + +</div> + +<div class="opcmd"> + +show log dhcpv6 client + +Show logs from all DHCPv6 client processes. + +</div> + +<div class="opcmd"> + +show log dhcpv6 client interface \<interface\> + +Show logs from specific <span class="title-ref">interface</span> DHCPv6 client process. + +</div> + +<div class="opcmd"> + +restart dhcpv6 server + +To restart the DHCPv6 server + +</div> + +<div class="opcmd"> + +show dhcpv6 server leases + +Shows status of all assigned leases: + +</div> + +``` 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 +``` + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +Static mappings aren't shown. To show all states, use `show dhcp server leases state all`. + +</div> + +<div class="opcmd"> + +show dhcpv6 server leases pool \<pool\> + +Show only leases in the specified pool. + +</div> + +<div class="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) + +</div> + +<div class="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) + +</div> diff --git a/docs/configuration/service/md-dns.md b/docs/configuration/service/md-dns.md new file mode 100644 index 00000000..08a24b48 --- /dev/null +++ b/docs/configuration/service/md-dns.md @@ -0,0 +1,574 @@ +# 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. + +<div class="cfgcmd"> + +set service dns forwarding system + +Forward incoming DNS queries to the DNS servers configured under the `system name-server` nodes. + +</div> + +<div class="cfgcmd"> + +set service dns forwarding dhcp \<interface\> + +Interfaces whose DHCP client nameservers to forward requests to. + +</div> + +<div class="cfgcmd"> + +set service dns forwarding name-server \<address\> port \<port\> + +Send all DNS queries to the IPv4/IPv6 DNS server specified under <span class="title-ref">\<address\></span> +on optional port specified under <span class="title-ref">\<port\></span>. The port defaults to 53. You can +configure multiple nameservers here. + +</div> + +<div class="cfgcmd"> + +set service dns forwarding domain \<domain-name\> name-server \<address\> + +Forward received queries for a particular domain +(specified via <span class="title-ref">domain-name</span>) to a given nameserver. Multiple nameservers +can be specified. You can use this feature for a DNS split-horizon +configuration. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +This also works for reverse-lookup zones (`18.172.in-addr.arpa`). + +</div> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service dns forwarding domain \<domain-name\> recursion-desired + +Set the "recursion desired" bit in requests to the upstream nameserver. + +</div> + +<div class="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. + +</div> + +<div class="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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The `CD`-bit is honored correctly for process and validate. For +log-fail, failures will be logged too. + +</div> + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +## 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 + +<div class="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. + +</div> + +<div class="opcmd"> + +restart dns forwarding + +Restarts the DNS recursor process. This also invalidates the local DNS +forwarding cache. + +</div> + +# 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](https://github.com/ddclient/ddclient), a Perl script written for +this only one purpose. + +[ddclient](https://github.com/ddclient/ddclient) uses two methods to update a DNS record. The first one will send +updates directly to the DNS daemon, in compliance with `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. + +## Configuration + +### `2136` Based + +<div class="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 <span class="title-ref">\<interface\></span> on the service you configured under +<span class="title-ref">\<service-name\></span>. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> description \<text\> + +Set description <span class="title-ref">\<text\></span> for dynamic DNS service being configured. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> key \<filename\> + +File identified by <span class="title-ref">\<filename\></span> containing the TSIG authentication key for RFC2136 +nsupdate on remote DNS server. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> server \<server\> + +Configure the DNS <span class="title-ref">\<server\></span> IP/FQDN used when updating this dynamic +assignment. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> zone \<zone\> + +Configure DNS <span class="title-ref">\<zone\></span> to be updated. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> host-name \<record\> + +Configure DNS <span class="title-ref">\<record\></span> which should be updated. This can be set multiple times. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> ttl \<ttl\> + +Configure optional TTL value on the given resource record. This defaults to +600 seconds. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic interval \<60-3600\> + +Specify interval in seconds to wait between Dynamic DNS updates. +The default is 300 seconds. + +</div> + +#### 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](https://github.com/ddclient/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 +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +You can also keep different DNS zone updated. Just create a new +config node: `set service dns dynamic interface <interface> rfc2136 <other-service-name>` + +</div> + +### 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. + +<div class="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 <span class="title-ref">\<interface\></span> on the service you configured under +<span class="title-ref">\<service-name\></span>. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> description \<text\> + +Set description <span class="title-ref">\<text\></span> for dynamic DNS service being configured. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> host-name \<hostname\> + +Setup the dynamic DNS hostname <span class="title-ref">\<hostname\></span> associated with the DynDNS +provider identified by <span class="title-ref">\<service-name\></span>. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> username \<username\> + +Configure <span class="title-ref">\<username\></span> used when authenticating the update request for +DynDNS service identified by <span class="title-ref">\<service-name\></span>. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> password \<password\> + +Configure <span class="title-ref">\<password\></span> used when authenticating the update request for +DynDNS service identified by <span class="title-ref">\<service-name\></span>. + +</div> + +<div class="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 <span class="title-ref">\<protocol\></span>. See the embedded +completion helper when entering above command for available protocols. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> server \<server\> + +When a `custom` DynDNS provider is used the <span class="title-ref">\<server\></span> where update +requests are being sent to must be specified. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> ip-version 'ipv6' + +Allow explicit IPv6 address for the interface. + +</div> + +#### 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' +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Multiple services can be used per interface. Just specify as many +services per interface as you like! + +</div> + +#### 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](https://github.com/ddclient/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](https://github.com/ddclient/ddclient) has another way to determine the WAN IP address. This is controlled +by: + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> address web \<url\> + +Use configured <span class="title-ref">\<url\></span> to determine your IP address. [ddclient](https://github.com/ddclient/ddclient) will load +<span class="title-ref">\<url\></span> and tries to extract your IP address from the response. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> address web skip \<pattern\> + +[ddclient](https://github.com/ddclient/ddclient) will skip any address located before the string set in <span class="title-ref">\<pattern\></span>. + +</div> diff --git a/docs/configuration/service/md-eventhandler.md b/docs/configuration/service/md-eventhandler.md new file mode 100644 index 00000000..5280c43a --- /dev/null +++ b/docs/configuration/service/md-eventhandler.md @@ -0,0 +1,150 @@ +# 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](#create-an-event-handler) +> +> [2. Add regex to the script](#add-regex-to-the-script) +> +> [3. Add a full path to the script](#add-a-full-path-to-the-script) +> +> [4. Add optional parameters](#add-optional-parameters) + +## Event Handler Configuration Steps + +### 1. Create an event handler + +> <div class="cfgcmd"> +> +> set service event-handler event \<event-handler name\> +> +> </div> +> +> 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 + +> <div class="cfgcmd"> +> +> set service event-handler event \<event-handler name\> filter pattern \<regex\> +> +> </div> +> +> This is a mandatory command. Sets regular expression to match against log string message. +> +> <div class="note"> +> +> <div class="title"> +> +> Note +> +> </div> +> +> The regular expression matches if and only if the entire string matches the pattern. +> +> </div> + +### 3. Add a full path to the script + +> <div class="cfgcmd"> +> +> set service event-handler event \<event-handler name\> script path \<path to script\> +> +> </div> +> +> This is a mandatory command. Sets the full path to the script. The script file must be executable. + +### 4. Add optional parameters + +> <div class="cfgcmd"> +> +> set service event-handler event \<event-handler name\> filter syslog-identifier \<sylogid name\> +> +> </div> +> +> This is an optional command. Filters log messages by syslog-identifier. +> +> <div class="cfgcmd"> +> +> set service event-handler event \<event-handler name\> script environment \<env name\> value \<env value\> +> +> </div> +> +> 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. +> +> <div class="cfgcmd"> +> +> set service event-handler event \<event-handler name\> script arguments \<arguments\> +> +> </div> +> +> This is an optional command. Adds arguments to the script. Arguments must be separated by spaces. +> +> <div class="note"> +> +> <div class="title"> +> +> Note +> +> </div> +> +> We don't recomend to use arguments. Using environments is more preffereble. +> +> </div> + +## 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..e68bcd50 --- /dev/null +++ b/docs/configuration/service/md-https.md @@ -0,0 +1,122 @@ +# 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 `vyosapi` page for an detailed how-to. + +## Configuration + +<div class="cfgcmd"> + +set service https allow-client address \<address\> + +Only allow certain IP addresses or prefixes to access the https +webserver. + +</div> + +<div class="cfgcmd"> + +set service https certificates ca-certificate \<name\> + +Use CA certificate from PKI subsystem + +</div> + +<div class="cfgcmd"> + +set service https certificates certificate \<name\> + +Use certificate from PKI subsystem + +</div> + +<div class="cfgcmd"> + +set service https certificates dh-params \<name\> + +Use `DH (Diffie–Hellman)` parameters from PKI subsystem. +Must be at least 2048 bits in length. + +</div> + +<div class="cfgcmd"> + +set service https listen-address \<address\> + +Webserver should only listen on specified IP address + +</div> + +<div class="cfgcmd"> + +set service https port \<number\> + +Webserver should listen on specified port. + +Default: 443 + +</div> + +<div class="cfgcmd"> + +set service https enable-http-redirect + +Enable automatic redirect from http to https. + +</div> + +<div class="cfgcmd"> + +set service https tls-version \<1.2 | 1.3\> + +Select TLS version used. + +This defaults to both 1.2 and 1.3. + +</div> + +<div class="cfgcmd"> + +set service https vrf \<name\> + +Start Webserver in given VRF. + +</div> + +### API + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service https api debug + +To enable debug messages. Available via `show log` or +`monitor log` + +</div> + +<div class="cfgcmd"> + +set service https api strict + +Enforce strict path checking + +</div> + +## 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..b22c93dd --- /dev/null +++ b/docs/configuration/service/md-ids.md @@ -0,0 +1,228 @@ +# 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 + +<div class="cfgcmd"> + +set service ids ddos-protection alert-script \<text\> + +Configure alert script that will be executed when an attack is detected. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service ids ddos-protection direction \[in | out\] + +Configure direction for processing traffic. + +</div> + +<div class="cfgcmd"> + +set service ids ddos-protection exclude-network \<x.x.x.x/x\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service ids ddos-protection listen-interface \<text\> + +Configure listen interface for mirroring traffic. + +</div> + +<div class="cfgcmd"> + +set service ids ddos-protection mode \[mirror | sflow\] + +Configure traffic capture mode. + +</div> + +<div class="cfgcmd"> + +set service ids ddos-protection network \<x.x.x.x/x\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service ids ddos-protection sflow listen-address \<x.x.x.x\> + +Configure local IPv4 address to listen for sflow. + +</div> + +<div class="cfgcmd"> + +set service ids ddos-protection sflow port \<1-65535\> + +Configure port number to be used for sflow conection. Default port is 6343. + +</div> + +<div class="cfgcmd"> + +set service ids ddos-protection threshold general +\[fps | mbps | pps\] \<0-4294967294\> + +Configure general threshold parameters. + +</div> + +<div class="cfgcmd"> + +set service ids ddos-protection threshold icmp +\[fps | mbps | pps\] \<0-4294967294\> + +Configure ICMP threshold parameters. + +</div> + +<div class="cfgcmd"> + +set service ids ddos-protection threshold tcp +\[fps | mbps | pps\] \<0-4294967294\> + +Configure TCP threshold parameters + +</div> + +<div class="cfgcmd"> + +set service ids ddos-protection threshold udp +\[fps | mbps | pps\] \<0-4294967294\> + +Configure UDP threshold parameters + +</div> + +### 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..420efc6d --- /dev/null +++ b/docs/configuration/service/md-index.md @@ -0,0 +1,28 @@ +# Service + +<div class="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 + +</div> diff --git a/docs/configuration/service/md-ipoe-server.md b/docs/configuration/service/md-ipoe-server.md new file mode 100644 index 00000000..dc66163d --- /dev/null +++ b/docs/configuration/service/md-ipoe-server.md @@ -0,0 +1,656 @@ +# IPoE Server + +VyOS utilizes [accel-ppp]() to provide `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 `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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +## 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' +``` + +<div class="cfgcmd"> + +set service ipoe-server authentication interface \<interface\> mac \<MAC\> + +Creates local IPoE user with username=\*\*\<interface\>\*\* and +password=\*\*\<MAC\>\*\* (mac-address) + +</div> + +<div class="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 + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server default-pool \<POOL-NAME\> + +Use this command to define default address pool name. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +``` 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 +``` + +<div class="cfgcmd"> + +set service ipoe-server authentication radius server \<server\> key \<secret\> + +Configure RADIUS <span class="title-ref">\<server\></span> and its required shared <span class="title-ref">\<secret\></span> for +communicating with the RADIUS server. + +</div> + +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' +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +### 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. + +<div class="cfgcmd"> + +set service ipoe-server authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queires. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The `source-address` must be configured on one of VyOS interface. +Best practice would be a loopback or dummy interface. + +</div> + +### RADIUS advanced options + +<div class="cfgcmd"> + +set service ipoe-server authentication radius server \<server\> port \<port\> + +Configure RADIUS <span class="title-ref">\<server\></span> and its required port for authentication requests. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication radius server \<server\> fail-time \<time\> + +Mark RADIUS server as offline for this given <span class="title-ref">\<time\></span> in seconds. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication radius server \<server\> disable + +Temporary disable this RADIUS server. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication radius acct-timeout \<timeout\> + +Timeout to wait reply for Interim-Update packets. (default 3 seconds) + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication radius dynamic-author server \<address\> + +Specifies IP address for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication radius dynamic-author port \<port\> + +Port for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication radius dynamic-author key \<secret\> + +Secret for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication radius max-try \<number\> + +Maximum number of tries to send Access-Request/Accounting-Request queries + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication radius timeout \<timeout\> + +Timeout to wait response from server (seconds) + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queires. + +</div> + +<div class="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 <span class="title-ref">Filter-Id</span>. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you set a custom RADIUS attribute you must define it on both +dictionaries at RADIUS server and client. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication radius rate-limit enable + +Enables bandwidth shaping via RADIUS. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication radius rate-limit vendor + +Specifies the vendor dictionary, dictionary needs to be in +/usr/share/accel-ppp/radius. + +</div> + +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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +`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](https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911). + +</div> + +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](https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel). +Define it in your RADIUS server. + +## IPv6 + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server default-ipv6-pool \<IPv6-POOL-NAME\> + +Use this command to define default IPv6 address pool name. + +</div> + +``` 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 + +<div class="cfgcmd"> + +set service ipoe-server extended-scripts on-change \<path_to_script\> + +Script to run when session interface changed by RADIUS CoA handling + +</div> + +<div class="cfgcmd"> + +set service ipoe-server extended-scripts on-down \<path_to_script\> + +Script to run when session interface going to terminate + +</div> + +<div class="cfgcmd"> + +set service ipoe-server extended-scripts on-pre-up \<path_to_script\> + +Script to run before session interface comes up + +</div> + +<div class="cfgcmd"> + +set service ipoe-server extended-scripts on-up \<path_to_script\> + +Script to run when session interface is completely configured and started + +</div> + +## Advanced Options + +### Authentication Advanced Options + +<div class="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\> + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication interface \<interface\> mac \<MAC\> rate-limit +download \<bandwidth\> + +Download bandwidth limit in kbit/s for user on interface <span class="title-ref">\<interface\></span>. + +</div> + +<div class="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 <span class="title-ref">\<interface\></span>. + +</div> + +### Client IP Pool Advanced Options + +<div class="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. + +</div> + +### Advanced Interface Options + +<div class="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 <span class="title-ref">client-ip-pool</span> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server interface \<interface\> external-dhcp giaddr \<x.x.x.x\> + +Specifies relay agent IP addre + +</div> + +### Global Advanced options + +<div class="cfgcmd"> + +set service ipoe-server description \<description\> + +Set description. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server limits burst \<value\> + +Burst count + +</div> + +<div class="cfgcmd"> + +set service ipoe-server limits connection-limit \<value\> + +Acceptable rate of connections (e.g. 1/min, 60/sec) + +</div> + +<div class="cfgcmd"> + +set service ipoe-server limits timeout \<value\> + +Timeout in seconds + +</div> + +<div class="cfgcmd"> + +set service ipoe-server max-concurrent-sessions + +Maximum number of concurrent session start attempts + +</div> + +<div class="cfgcmd"> + +set service ipoe-server name-server \<address\> + +Connected client should use <span class="title-ref">\<address\></span> 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. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server shaper fwmark \<1-2147483647\> + +Match firewall mark value + +</div> + +<div class="cfgcmd"> + +set service ipoe-server snmp master-agent + +Enable SNMP + +</div> + +## Monitoring + +<div class="opcmd"> + +show ipoe-server sessions + +Use this command to locally check the active sessions in the IPoE +server. + +</div> + +``` 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>] +``` diff --git a/docs/configuration/service/md-lldp.md b/docs/configuration/service/md-lldp.md new file mode 100644 index 00000000..84d734a0 --- /dev/null +++ b/docs/configuration/service/md-lldp.md @@ -0,0 +1,176 @@ +# LLDP + +`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 +`CDP (Cisco Discovery Protocol)`, +`FDP (Foundry Discovery Protocol)`, +`NDP (Nortel Discovery Protocol)` and `LLTD (Link Layer Topology +Discovery)`. + +Information gathered with LLDP is stored in the device as a `MIB +(Management Information Database)` and can be queried with `SNMP (Simple +Network Management Protocol)` as specified in `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 + +<div class="cfgcmd"> + +set service lldp + +Enable LLDP service + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service lldp interface \<interface\> + +Enable transmission of LLDP information on given <span class="title-ref">\<interface\></span>. You can also +say `all` here so LLDP is turned on on every interface. + +</div> + +<div class="cfgcmd"> + +set service lldp interface \<interface\> disable + +Disable transmit of LLDP frames on given <span class="title-ref">\<interface\></span>. Useful to exclude +certain interfaces from LLDP when `all` have been enabled. + +</div> + +<div class="cfgcmd"> + +set service lldp snmp + +Enable SNMP queries of the LLDP database + +</div> + +<div class="cfgcmd"> + +set service lldp legacy-protocols \<cdp[|edp|](##SUBST##|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 + +</div> + +## Operation + +<div class="opcmd"> + +show lldp neighbors + +Displays information about all neighbors discovered via LLDP. + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show lldp neighbors detail + +Get detailed information about LLDP neighbors. + +``` 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 +------------------------------------------------------------------------------- +``` + +</div> + +<div class="opcmd"> + +show lldp neighbors interface \<interface\> + +Show LLDP neighbors connected via interface <span class="title-ref">\<interface\></span>. + +</div> + +<div class="opcmd"> + +show log lldp + +Used for troubleshooting. + +</div> diff --git a/docs/configuration/service/md-mdns.md b/docs/configuration/service/md-mdns.md new file mode 100644 index 00000000..504843d4 --- /dev/null +++ b/docs/configuration/service/md-mdns.md @@ -0,0 +1,162 @@ +# mDNS Repeater + +Starting with VyOS 1.2 a `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 +<span class="title-ref">"administratively scoped"</span> 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 `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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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! + +</div> + +## Configuration + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service mdns repeater disable + +mDNS repeater can be temporarily disabled without deleting the service using + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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 + +</div> + +## 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 <span class="title-ref">eth0</span> and <span class="title-ref">eth1</span> mDNS packets and also repeat packets +received on <span class="title-ref">eth0</span> to <span class="title-ref">eth1</span> (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 + +<div class="opcmd"> + +restart mdns repeater + +Restart mDNS repeater service. + +</div> + +<div class="opcmd"> + +show log mdns repeater + +Show logs for mDNS repeater service. + +</div> + +<div class="opcmd"> + +monitor log mdns repeater + +Follow the logs for mDNS repeater service. + +</div> diff --git a/docs/configuration/service/md-monitoring.md b/docs/configuration/service/md-monitoring.md new file mode 100644 index 00000000..8dff341a --- /dev/null +++ b/docs/configuration/service/md-monitoring.md @@ -0,0 +1,230 @@ +# Monitoring + +## Azure-data-explorer + +Telegraf output plugin [azure-data-explorer](https://github.com/influxdata/telegraf/tree/master/plugins/outputs/azure_data_explorer) + +<div class="cfgcmd"> + +set service monitoring telegraf azure-data-explorer authentication client-id \<client-id\> + +Authentication application client-id. + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf azure-data-explorer authentication client-secret \<client-secret\> + +Authentication application client-secret. + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf azure-data-explorer authentication tenant-id \<tenant-id\> + +Authentication application tenant-id + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf azure-data-explorer database \<name\> + +Remote database name. + +</div> + +<div class="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`. + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf azure-data-explorer table \<name\> + +Name of the single table Only if set group-metrics single-table. + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf azure-data-explorer url \<url\> + +Remote URL. + +</div> + +## Prometheus-client + +Telegraf output plugin [prometheus-client](https://github.com/influxdata/telegraf/tree/master/plugins/outputs/prometheus_client) + +<div class="cfgcmd"> + +set service monitoring telegraf prometheus-client + +Output plugin Prometheus client + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf prometheus-client allow-from \<prefix\> + +Networks allowed to query this server + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf prometheus-client authentication username \<username\> + +HTTP basic authentication username + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf prometheus-client authentication password \<password\> + +HTTP basic authentication username + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf prometheus-client listen-address \<address\> + +Local IP addresses to listen on + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf prometheus-client metric-version \<1 | 2\> + +Metris version, the default is `2` + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf prometheus-client port \<port\> + +Port number used by connection, default is `9273` + +</div> + +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](https://www.splunk.com/en_us/blog/it/splunk-metrics-via-telegraf.html). HTTP Event Collector. + +<div class="cfgcmd"> + +set service monitoring telegraf splunk authentication insecure + +Use TLS but skip host validation + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf splunk authentication token \<token\> + +Authorization token + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf splunk authentication url \<url\> + +Remote URL to Splunk collector + +</div> + +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. + +<div class="cfgcmd"> + +set service monitoring telegraf influxdb authentication organization \<organization\> + +Authentication organization name + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf influxdb authentication token \<token\> + +Authentication token + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf bucket \<bucket\> + +Remote `InfluxDB` bucket name + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf influxdb port \<port\> + +Remote port + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf influxdb url \<url\> + +Remote URL + +</div> + +## 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' +``` diff --git a/docs/configuration/service/md-ntp.md b/docs/configuration/service/md-ntp.md new file mode 100644 index 00000000..871f5fec --- /dev/null +++ b/docs/configuration/service/md-ntp.md @@ -0,0 +1,136 @@ +# NTP + +`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 `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 +`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 `5905`. It is backward compatible with version 3, specified +in `1305`. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +VyOS 1.4 uses chrony instead of ntpd (see `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 <span class="title-ref">allow-client</span> directive. + +</div> + +## Configuration + +<div class="cfgcmd"> + +set service ntp server \<address\> + +Configure one or more servers for synchronisation. Server name can be either +an IP address or `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` + +</div> + +<div class="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 `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. + +</div> + +<div class="cfgcmd"> + +set service ntp listen-address \<address\> + +NTP process will only listen on the specified IP address. You must specify +the <span class="title-ref">\<address\></span> 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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service ntp vrf \<name\> + +Specify name of the `VRF (Virtual Routing and Forwarding)` instance. + +</div> + +<div class="cfgcmd"> + +set service ntp leap-second \[ignore[|smear|](##SUBST##|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 + +</div> diff --git a/docs/configuration/service/md-pppoe-server.md b/docs/configuration/service/md-pppoe-server.md new file mode 100644 index 00000000..3c77e425 --- /dev/null +++ b/docs/configuration/service/md-pppoe-server.md @@ -0,0 +1,957 @@ +lastproofread +2022-09-17 + +# PPPoE Server + +VyOS utilizes [accel-ppp]() to provide PPPoE server functionality. It can +be used with local authentication or a connected RADIUS server. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +## 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 +``` + +<div class="cfgcmd"> + +set service pppoe-server access-concentrator \<name\> + +Use this command to set a name for this PPPoE-server access +concentrator. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication local-users username +\<name\> password \<password\> + +Create <span class="title-ref">\<user\></span> for local authentication on this system. The users password +will be set to <span class="title-ref">\<pass\></span>. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server default-pool \<POOL-NAME\> + +Use this command to define default address pool name. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server interface \<interface\> + +Use this command to define the interface the PPPoE server will use to +listen for PPPoE clients. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server gateway-address \<address\> + +Specifies single <span class="title-ref">\<gateway\></span> IP address to be used as local address of PPP +interfaces. + +</div> + +## 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 +``` + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +server \<server\> key \<secret\> + +Configure RADIUS <span class="title-ref">\<server\></span> and its required shared <span class="title-ref">\<secret\></span> for +communicating with the RADIUS server. + +</div> + +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' +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +### 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. + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +source-address \<address\> + +Source IPv4 address used in all RADIUS server queires. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The `source-address` must be configured on one of VyOS interface. +Best practice would be a loopback or dummy interface. + +</div> + +### RADIUS advanced options + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +server \<server\> port \<port\> + +Configure RADIUS <span class="title-ref">\<server\></span> and its required port for authentication requests. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +server \<server\> fail-time \<time\> + +Mark RADIUS server as offline for this given <span class="title-ref">\<time\></span> in seconds. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +server \<server\> disable + +Temporary disable this RADIUS server. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +acct-timeout \<timeout\> + +Timeout to wait reply for Interim-Update packets. (default 3 seconds) + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +dynamic-author server \<address\> + +Specifies IP address for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +dynamic-author port \<port\> + +Port for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication radius dynamic-author +key \<secret\> + +Secret for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +max-try \<number\> + +Maximum number of tries to send Access-Request/Accounting-Request queries + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +timeout \<timeout\> + +Timeout to wait response from server (seconds) + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +source-address \<address\> + +Source IPv4 address used in all RADIUS server queires. + +</div> + +<div class="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`. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you set a custom RADIUS attribute you must define it on both +dictionaries at RADIUS server and client. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +rate-limit enable + +Enables bandwidth shaping via RADIUS. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +rate-limit vendor + +Specifies the vendor dictionary, dictionary needs to be in +/usr/share/accel-ppp/radius. + +</div> + +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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +`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](https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911). + +</div> + +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](https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel). 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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The value of the attribute `NAS-Port-Id` must be less than 16 +characters, otherwise the interface won't be renamed. + +</div> + +## Automatic VLAN Creation + +<div class="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. + +</div> + +``` 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 + +<div class="cfgcmd"> + +set service pppoe-server authentication local-users username +\<user\> rate-limit download \<bandwidth\> + +Download bandwidth limit in kbit/s for <span class="title-ref">\<user\></span>. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication local-users username +\<user\> rate-limit upload \<bandwidth\> + +Upload bandwidth limit in kbit/s for <span class="title-ref">\<user\></span>. + +</div> + +``` 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. + +<div class="cfgcmd"> + +set service pppoe-server authentication radius rate-limit enable + +Use this command to enable bandwidth shaping via RADIUS. + +</div> + +Other attributes can be used, but they have to be in one of the +dictionaries in */usr/share/accel-ppp/radius*. + +## Load Balancing + +<div class="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. + +</div> + +``` 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 + +<div class="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) + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server default-ipv6-pool \<IPv6-POOL-NAME\> + +Use this command to define default IPv6 address pool name. + +</div> + +``` 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 + +<div class="cfgcmd"> + +set service pppoe-server ppp-options ipv6-accept-peer-interface-id + +Accept peer interface identifier. By default is not defined. + +</div> + +<div class="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 + +</div> + +<div class="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. + +</div> + +## Scripting + +<div class="cfgcmd"> + +set service pppoe-server extended-scripts on-change \<path_to_script\> + +Script to run when session interface changed by RADIUS CoA handling + +</div> + +<div class="cfgcmd"> + +set service pppoe-server extended-scripts on-down \<path_to_script\> + +Script to run when session interface going to terminate + +</div> + +<div class="cfgcmd"> + +set service pppoe-server extended-scripts on-pre-up \<path_to_script\> + +Script to run before session interface comes up + +</div> + +<div class="cfgcmd"> + +set service pppoe-server extended-scripts on-up \<path_to_script\> + +Script to run when session interface is completely configured and started + +</div> + +## Advanced Options + +### Authentication Advanced Options + +<div class="cfgcmd"> + +set service pppoe-server authentication local-users +username \<user\> disable + +Disable <span class="title-ref">\<user\></span> account. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication local-users +username \<user\> static-ip \<address\> + +Assign static IP address to <span class="title-ref">\<user\></span> account. + +</div> + +<div class="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. + +</div> + +### Client IP Pool Advanced Options + +<div class="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. + +</div> + +### PPP Advanced Options + +<div class="cfgcmd"> + +set service pppoe-server ppp-options disable-ccp + +Disable Compression Control Protocol (CCP). +CCP is enabled by default. + +</div> + +<div class="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**. + +</div> + +<div class="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 + +</div> + +<div class="cfgcmd"> + +set service pppoe-server ppp-options lcp-echo-failure \<number\> + +Defines the maximum <span class="title-ref">\<number\></span> of unanswered echo requests. Upon reaching the +value <span class="title-ref">\<number\></span>, the session will be reset. Default value is **3**. + +</div> + +<div class="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 <span class="title-ref">\<interval\></span> seconds. +Default value is **30**. + +</div> + +<div class="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**. + +</div> + +<div class="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**. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server ppp-options mppe \<require | prefer | deny\> + +Specifies `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. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server ppp-options mru \<number\> + +Defines preferred MRU. By default is not defined. + +</div> + +### Global Advanced options + +<div class="cfgcmd"> + +set service pppoe-server description \<description\> + +Set description. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server limits burst \<value\> + +Burst count + +</div> + +<div class="cfgcmd"> + +set service pppoe-server limits connection-limit \<value\> + +Acceptable rate of connections (e.g. 1/min, 60/sec) + +</div> + +<div class="cfgcmd"> + +set service pppoe-server limits timeout \<value\> + +Timeout in seconds + +</div> + +<div class="cfgcmd"> + +set service pppoe-server mtu + +Maximum Transmission Unit (MTU) (default: **1492**) + +</div> + +<div class="cfgcmd"> + +set service pppoe-server max-concurrent-sessions + +Maximum number of concurrent session start attempts + +</div> + +<div class="cfgcmd"> + +set service pppoe-server name-server \<address\> + +Connected client should use <span class="title-ref">\<address\></span> 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. + +</div> + +<div class="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: <span class="title-ref">sn1,sn2,sn3</span> + +</div> + +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. + +<div class="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)** + +</div> + +<div class="cfgcmd"> + +set service pppoe-server shaper fwmark \<1-2147483647\> + +Match firewall mark value + +</div> + +<div class="cfgcmd"> + +set service pppoe-server snmp master-agent + +Enable SNMP + +</div> + +<div class="cfgcmd"> + +set service pppoe-server wins-server \<address\> + +Windows Internet Name Service (WINS) servers propagated to client + +</div> + +## Monitoring + +<div class="opcmd"> + +show pppoe-server sessions + +Use this command to locally check the active sessions in the PPPoE +server. + +</div> + +``` 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 +``` diff --git a/docs/configuration/service/md-router-advert.md b/docs/configuration/service/md-router-advert.md new file mode 100644 index 00000000..3367e7aa --- /dev/null +++ b/docs/configuration/service/md-router-advert.md @@ -0,0 +1,241 @@ +# Router Advertisements + +`RAs (Router advertisements)` are described in `4861#section-4.6.2`. +They are part of what is known as `SLAAC (Stateless Address +Autoconfiguration)`. + +Supported interface types: + +> - bonding +> - bridge +> - ethernet +> - geneve +> - l2tpv3 +> - openvpn +> - pseudo-ethernet +> - tunnel +> - vxlan +> - wireguard +> - wireless +> - wwan + +## Configuration + +<div class="cfgcmd"> + +set service router-advert interface \<interface\> ... + +</div> + +<table> +<colgroup> +<col style="width: 25%" /> +<col style="width: 25%" /> +<col style="width: 50%" /> +</colgroup> +<thead> +<tr> +<th>Field</th> +<th>VyOS Option</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td>Cur Hop Limit</td> +<td>hop-limit</td> +<td>Hop count field of the outgoing RA packets</td> +</tr> +<tr> +<td>"Managed address configuration" flag</td> +<td>managed-flag</td> +<td>Tell hosts to use the administered stateful protocol (i.e. DHCP) for autoconfiguration</td> +</tr> +<tr> +<td>"Other configuration" flag</td> +<td>other-config-flag</td> +<td>Tell hosts to use the administered (stateful) protocol (i.e. DHCP) for autoconfiguration of other (non-address) information</td> +</tr> +<tr> +<td>MTU</td> +<td>link-mtu</td> +<td>Link MTU value placed in RAs, exluded in RAs if unset</td> +</tr> +<tr> +<td>Router Lifetime</td> +<td>default-lifetime</td> +<td>Lifetime associated with the default router in units of seconds</td> +</tr> +<tr> +<td>Reachable Time</td> +<td>reachable-time</td> +<td>Time, in milliseconds, that a node assumes a neighbor is reachable after having received a reachability confirmation</td> +</tr> +<tr> +<td>Retransmit Timer</td> +<td>retrans-timer</td> +<td>Time in milliseconds between retransmitted Neighbor Solicitation messages</td> +</tr> +<tr> +<td>Default Router Preference</td> +<td>default-preference</td> +<td>Preference associated with the default router</td> +</tr> +<tr> +<td>Interval</td> +<td>interval</td> +<td>Min and max intervals between unsolicited multicast RAs</td> +</tr> +<tr> +<td>DNSSL</td> +<td>dnssl</td> +<td>DNS search list to advertise</td> +</tr> +<tr> +<td>Name Server</td> +<td>name-server</td> +<td>Advertise DNS server per <a href="https://tools.ietf.org/html/rfc6106">https://tools.ietf.org/html/rfc6106</a></td> +</tr> +</tbody> +</table> + +### Advertising a Prefix + +<div class="cfgcmd"> + +set service router-advert interface \<interface\> prefix \<prefix/mask\> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +You can also opt for using <span class="title-ref">::/64</span> as prefix for your `RAs (Router +Advertisements)`. This will take the IPv6 GUA prefix assigned to the interface, +which comes in handy when using DHCPv6-PD. + +</div> + +</div> + +<table> +<colgroup> +<col style="width: 25%" /> +<col style="width: 75%" /> +</colgroup> +<thead> +<tr> +<th>VyOS Field</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td>decrement-lifetime</td> +<td>Lifetime is decremented by the number of seconds since the last RA - use in conjunction with a DHCPv6-PD prefix</td> +</tr> +<tr> +<td>deprecate-prefix</td> +<td>Upon shutdown, this option will deprecate the prefix by announcing it in the shutdown RA</td> +</tr> +<tr> +<td>no-autonomous-flag</td> +<td>Prefix can not be used for stateless address auto-configuration</td> +</tr> +<tr> +<td>no-on-link-flag</td> +<td>Prefix can not be used for on-link determination</td> +</tr> +<tr> +<td>preferred-lifetime</td> +<td>Time in seconds that the prefix will remain preferred (default 4 hours)</td> +</tr> +<tr> +<td>valid-lifetime</td> +<td>Time in seconds that the prefix will remain valid (default: 30 days)</td> +</tr> +</tbody> +</table> + +### Advertising a NAT64 Prefix + +<div class="cfgcmd"> + +set service router-advert interface \<interface\> nat64prefix \<prefix/mask\> + +Enable PREF64 option as outlined in `8781`. + +NAT64 prefix mask must be one of: /32, /40, /48, /56, /64 or 96. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The well known NAT64 prefix is `64:ff9b::/96` + +</div> + +</div> + +<table> +<colgroup> +<col style="width: 25%" /> +<col style="width: 75%" /> +</colgroup> +<thead> +<tr> +<th>VyOS Field</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td>valid-lifetime</td> +<td>Time in seconds that the prefix will remain valid (default: 65528 seconds)</td> +</tr> +</tbody> +</table> + +### Disabling Advertisements + +To disable advertisements without deleting the configuration: + +<div class="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. + +</div> + +<div class="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. + +</div> + +## 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..8783d0b4 --- /dev/null +++ b/docs/configuration/service/md-salt-minion.md @@ -0,0 +1,58 @@ +# Salt-Minion + +[SaltStack](https://saltproject.io/) 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 + +<div class="cfgcmd"> + +set service salt-minion hash \<type\> + +The hash type used when discovering file on master server (default: sha256) + +</div> + +<div class="cfgcmd"> + +set service salt-minion id \<id\> + +Explicitly declare ID for this minion to use (default: hostname) + +</div> + +<div class="cfgcmd"> + +set service salt-minion interval \<1-1440\> + +Interval in minutes between updates (default: 60) + +</div> + +<div class="cfgcmd"> + +set service salt-minion master \<hostname | IP\> + +The hostname or IP address of the master + +</div> + +<div class="cfgcmd"> + +set service salt-minion master-key \<key\> + +URL with signature of master for auth reply verification + +</div> + +Please take a look in the Automation section to find some usefull +Examples. diff --git a/docs/configuration/service/md-snmp.md b/docs/configuration/service/md-snmp.md new file mode 100644 index 00000000..84877df3 --- /dev/null +++ b/docs/configuration/service/md-snmp.md @@ -0,0 +1,252 @@ +# SNMP + +`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](https://en.wikipedia.org/wiki/Management_information_base)) 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> +<img src="/_static/images/service_snmp_communication_principles_diagram.webp" alt="Principle of SNMP Communication" /> +<figcaption>Image thankfully borrowed from +<a href="https://en.wikipedia.org/wiki/File:SNMP_communication_principles_diagram.PNG">https://en.wikipedia.org/wiki/File:SNMP_communication_principles_diagram.PNG</a> +which is under the GNU Free Documentation License</figcaption> +</figure> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +VyOS SNMP supports both IPv4 and IPv6. + +</div> + +## SNMP Protocol Versions + +VyOS itself supports [SNMPv2](https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_2) (version 2) and [SNMPv3](https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_3) (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. + +#### 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> +``` diff --git a/docs/configuration/service/md-ssh.md b/docs/configuration/service/md-ssh.md new file mode 100644 index 00000000..12384878 --- /dev/null +++ b/docs/configuration/service/md-ssh.md @@ -0,0 +1,374 @@ +# SSH + +`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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +VyOS 1.1 supported login as user `root`. This has been removed due +to tighter security in VyOS 1.2. + +</div> + +<div class="seealso"> + +SSH `ssh_key_based_authentication` + +</div> + +## Configuration + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service ssh listen-address \<address\> + +Specify IPv4/IPv6 listen address of SSH server. Multiple addresses can be +defined. + +</div> + +<div class="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` + +</div> + +<div class="cfgcmd"> + +set service ssh disable-password-authentication + +Disable password based authentication. Login via SSH keys only. This hardens +security! + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service ssh mac \<mac\> + +Specifies the available `MAC (Message Authentication Code)` algorithms. +The MAC algorithm is used in protocol version 2 for data integrity protection. +Multiple algorithms can be 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` + +</div> + +<div class="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`. + +</div> + +<div class="cfgcmd"> + +set service ssh client-keepalive-interval \<interval\> + +Specify timeout interval for keepalive message in seconds. + +</div> + +<div class="cfgcmd"> + +set service ssh key-exchange \<kex\> + +Specify allowed `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`. + +</div> + +<div class="cfgcmd"> + +set service ssh loglevel \<quiet | fatal | error | info | verbose\> + +Set the `sshd` log level. The default is `info`. + +</div> + +<div class="cfgcmd"> + +set service ssh vrf \<name\> + +Specify name of the `VRF (Virtual Routing and Forwarding)` instance. + +</div> + +## 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. + +<div class="cfgcmd"> + +set service ssh dynamic-protection + +Allow `ssh` dynamic-protection. + +</div> + +<div class="cfgcmd"> + +set service ssh dynamic-protection allow-from \<address | prefix\> + +Whitelist of addresses and networks. Always allow inbound connections from +these systems. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service ssh dynamic-protection detect-time \<sec\> + +Remember source IP in seconds before reset their score. The default is 1800. + +</div> + +<div class="cfgcmd"> + +set service ssh dynamic-protection threshold \<sec\> + +Block source IP when their cumulative attack score exceeds threshold. The +default is 30. + +</div> + +## Operation + +<div class="opcmd"> + +restart ssh + +Restart the SSH daemon process, the current session is not affected, only the +background daemon is restarted. + +</div> + +<div class="opcmd"> + +generate ssh server-key + +Re-generated the public/private keyportion which SSH uses to secure +connections. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Already learned known_hosts files of clients need an update as the +public key will change. + +</div> + +</div> + +<div class="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: + +``` 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. + +</div> + +<div class="opcmd"> + +generate public-key-command user \<username\> path \<location\> + +Generate the configuration mode commands to add a public key for +`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: + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show log ssh + +Show SSH server log. + +</div> + +<div class="opcmd"> + +monitor log ssh + +Follow the SSH server log. + +</div> + +<div class="opcmd"> + +show log ssh dynamic-protection + +Show SSH dynamic-protection log. + +</div> + +<div class="opcmd"> + +monitor log ssh dynamic-protection + +Follow the SSH dynamic-protection log. + +</div> + +<div class="opcmd"> + +show ssh dynamic-protection + +Show list of IPs currently blocked by SSH dynamic-protection. + +</div> + +<div class="opcmd"> + +show ssh fingerprints + +Show SSH server public key fingerprints. + +</div> + +<div class="opcmd"> + +show ssh fingerprints ascii + +Show SSH server public key fingerprints, including a visual ASCII art representation. + +</div> diff --git a/docs/configuration/service/md-tftp-server.md b/docs/configuration/service/md-tftp-server.md new file mode 100644 index 00000000..1d8e6e15 --- /dev/null +++ b/docs/configuration/service/md-tftp-server.md @@ -0,0 +1,105 @@ +# TFTP Server + +`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 + +<div class="cfgcmd"> + +set service tftp-server directory \<directory\> + +Enable TFTP service by specifying the <span class="title-ref">\<directory\></span> which will be used to serve +files. + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set service tftp-server listen-address \<address\> vrf \<name\> + +</div> + +Additional option to run TFTP server in the `VRF (Virtual Routing and Forwarding)` context + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Configuring a listen-address is essential for the service to work. + +</div> + +<div class="cfgcmd"> + +set service tftp-server allow-upload + +Optional, if you want to enable uploads, else TFTP server will act as a +read-only server. + +</div> + +### 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..4a881cea --- /dev/null +++ b/docs/configuration/service/md-webproxy.md @@ -0,0 +1,536 @@ +# Webproxy + +The proxy service in VyOS is based on [Squid](http://www.squid-cache.org/) and some related modules. + +[Squid](http://www.squid-cache.org/) 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](http://www.squidguard.org/). + +## Configuration + +<div class="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`. + +``` none +set service webproxy append-domain vyos.net +``` + +</div> + +<div class="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. + +``` none +set service webproxy cache-size 1024 +``` + +</div> + +<div class="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. + +``` none +set service webproxy default-port 8080 +``` + +</div> + +<div class="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. + +``` none +set service webproxy domain-block vyos.net +``` + +</div> + +<div class="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. + +``` none +set service webproxy domain-noncache vyos.net +``` + +</div> + +<div class="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! + +``` none +set service webproxy listen-address 192.0.2.1 +``` + +</div> + +<div class="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. + +``` none +set service webproxy listen-address 192.0.2.1 disable-transparent +``` + +</div> + +<div class="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. + +``` none +set service webproxy listen-address 192.0.2.1 port 8080 +``` + +</div> + +<div class="cfgcmd"> + +set service webproxy reply-block-mime \<mime\> + +Used to block a specific mime-type. + +``` none +# block all PDFs +set service webproxy reply-block-mime application/pdf +``` + +</div> + +<div class="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. + +``` none +set service webproxy reply-body-max-size 2048 +``` + +</div> + +<div class="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 + +</div> + +<div class="cfgcmd"> + +set service webproxy ssl-safe-ports \<port\> + +Add new port to SSL-ports acl. Ports included by default in SSL-ports acl: +443 + +</div> + +### 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. + +<div class="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. + +``` none +set service webproxy authentication children 10 +``` + +</div> + +<div class="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. + +``` none +set service webproxy authentication credentials-ttl 120 +``` + +</div> + +<div class="cfgcmd"> + +set service webproxy authentication method \<ldap\> + +Proxy authentication method, currently only LDAP is supported. + +``` none +set service webproxy authentication method ldap +``` + +</div> + +<div class="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. + +``` none +set service webproxy authentication realm "VyOS proxy auth" +``` + +</div> + +#### LDAP + +<div class="cfgcmd"> + +set service webproxy authentication ldap base-dn \<base-dn\> + +Specifies the base DN under which the users are located. + +``` none +set service webproxy authentication ldap base-dn DC=vyos,DC=net +``` + +</div> + +<div class="cfgcmd"> + +set service webproxy authentication ldap bind-dn \<bind-dn\> + +The DN and password to bind as while performing searches. + +``` none +set service webproxy authentication ldap bind-dn CN=proxyuser,CN=Users,DC=vyos,DC=net +``` + +</div> + +<div class="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 `2037` directories. For a +detailed description of LDAP search filter syntax see `2254`. + +``` none +set service webproxy authentication ldap filter-expression (cn=%s) +``` + +</div> + +<div class="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. + +``` none +set service webproxy authentication ldap password vyos +``` + +</div> + +<div class="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. + +``` none +set service webproxy authentication ldap persistent-connection +``` + +</div> + +<div class="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. + +``` none +set service webproxy authentication ldap port 389 +``` + +</div> + +<div class="cfgcmd"> + +set service webproxy authentication ldap server \<server\> + +Specify the LDAP server to connect to. + +``` none +set service webproxy authentication ldap server ldap.vyos.net +``` + +</div> + +<div class="cfgcmd"> + +set service webproxy authentication ldap use-ssl + +Use TLS encryption. + +``` none +set service webproxy authentication ldap use-ssl +``` + +</div> + +<div class="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 (<span class="title-ref">filter-expression</span>). + +Defaults to 'uid' + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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 (<span class="title-ref">filter-expression</span>). + +</div> + +``` none +set service webproxy authentication ldap username-attribute uid +``` + +</div> + +<div class="cfgcmd"> + +set service webproxy authentication ldap version \<2 | 3\> + +LDAP protocol version. Defaults to 3 if not specified. + +``` none +set service webproxy authentication ldap version 2 +``` + +</div> + +### URL filtering + +<div class="cfgcmd"> + +set service webproxy url-filtering disable + +Disables web filtering without discarding configuration. + +``` none +set service webproxy url-filtering disable +``` + +</div> + +## Operation + +### 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. + +<div class="opcmd"> + +update webproxy blacklists + +Download/Update complete blacklist + +``` 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:~$ +``` + +</div> + +<div class="opcmd"> + +update webproxy blacklists category \<category\> + +Download/Update partial blacklist. + +Use tab completion to get a list of categories. + +</div> + +- 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 + +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 + } +``` diff --git a/docs/configuration/system/md-acceleration.md b/docs/configuration/system/md-acceleration.md new file mode 100644 index 00000000..21096988 --- /dev/null +++ b/docs/configuration/system/md-acceleration.md @@ -0,0 +1,168 @@ +# Acceleration + +In this command tree, all hardware acceleration options will be handled. +At the moment only [Intel® QAT](https://www.intel.com/content/www/us/en/architecture-and-technology/intel-quick-assist-technology-overview.html) is supported + +## Intel® QAT + +<div class="opcmd"> + +show system acceleration qat + +use this command to check if there is an Intel® QAT supported Processor in +your system. + +``` +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 ``\` + +</div> + +<div class="cfgcmd"> + +set system acceleration qat + +if there is a supported device, enable Intel® QAT + +</div> + +<div class="opcmd"> + +show system acceleration qat status + +Check if the Intel® QAT device is up and ready to do the job. + +``` +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 +``` + +</div> + +### Operation Mode + +<div class="opcmd"> + +show system acceleration qat device \<device\> config + +Show the full config uploaded to the QAT device. + +</div> + +<div class="opcmd"> + +show system acceleration qat device \<device\> flows + +Get an overview over the encryption counters. + +</div> + +<div class="opcmd"> + +show system acceleration qat interrupts + +Show binded qat device interrupts to certain core. + +</div> + +### 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 `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 +``` diff --git a/docs/configuration/system/md-conntrack.md b/docs/configuration/system/md-conntrack.md new file mode 100644 index 00000000..2d5afdfd --- /dev/null +++ b/docs/configuration/system/md-conntrack.md @@ -0,0 +1,473 @@ +# 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 + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack table-size \<1-50000000\> + +The connection tracking table contains one entry for each connection being +tracked by the system. + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack expect-table-size \<1-50000000\> + +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. + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack hash-size \<1-50000000\> + +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. + +</div> + +<div class="cfgcmd"> + +set system conntrack modules ftp + +</div> + +<div class="cfgcmd"> + +set system conntrack modules h323 + +</div> + +<div class="cfgcmd"> + +set system conntrack modules nfs + +</div> + +<div class="cfgcmd"> + +set system conntrack modules pptp + +</div> + +<div class="cfgcmd"> + +set system conntrack modules sip + +</div> + +<div class="cfgcmd"> + +set system conntrack modules sqlnet + +</div> + +<div class="cfgcmd"> + +set system conntrack modules tftp + +Configure the connection tracking protocol helper modules. +All modules are enable by default. + +Use <span class="title-ref">delete system conntrack modules</span> to deactive all modules.\ +Or, for example ftp, <span class="title-ref">delete system conntrack modules ftp</span>. + +</div> + +### 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. + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout icmp \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout other \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout tcp close \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout tcp close-wait \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout tcp established \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout tcp fin-wait \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout tcp last-ack \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout tcp syn-recv \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout tcp syn-sent \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout tcp time-wait \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout udp other \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout udp stream \<1-21474836\> + +Set the timeout in secounds for a protocol or state. + +</div> + +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. + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> description \<test\> + +Set a rule description. + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> destination address \<ip-address\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> source address \<ip-address\> + +set a destination and/or source address. Accepted input: + +``` 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 +``` + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> destination port \<value\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> source port \<value\> + +Set a destination and/or source port. Accepted input: + +``` 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: +<span class="title-ref">!22,telnet,http,123,1001-1005</span>\` + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol icmp \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol other \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol tcp close \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol tcp close-wait \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol tcp established \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol tcp fin-wait \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol tcp last-ack \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol tcp syn-recv \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol tcp syn-sent \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol tcp time-wait \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol udp other \<1-21474836\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack tcp half-open-connections \<1-21474836\> + +Set the maximum number of TCP half-open connections. + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack tcp loose \<enable | disable\> + +Policy to track previously established connections. + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack tcp max-retrans \<1-2147483647\> + +Set the number of TCP maximum retransmit attempts. + +</div> + +<div class="cfgcmd"> + +set system conntrack ignore rule \<1-9999\> description \<text\> + +</div> + +<div class="cfgcmd"> + +set system conntrack ignore rule \<1-9999\> destination address \<ip-address\> + +</div> + +<div class="cfgcmd"> + +set system conntrack ignore rule \<1-9999\> destination port \<port\> + +</div> + +<div class="cfgcmd"> + +set system conntrack ignore rule \<1-9999\> inbound-interface \<interface\> + +</div> + +<div class="cfgcmd"> + +set system conntrack ignore rule \<1-9999\> protocol \<protocol\> + +</div> + +<div class="cfgcmd"> + +set system conntrack ignore rule \<1-9999\> source address \<ip-address\> + +</div> + +<div class="cfgcmd"> + +set system conntrack ignore rule \<1-9999\> source port \<port\> + +Customized ignore rules, based on a packet and flow selector. + +</div> + +<div class="cfgcmd"> + +set system conntrack log icmp destroy + +</div> + +<div class="cfgcmd"> + +set system conntrack log icmp new + +</div> + +<div class="cfgcmd"> + +set system conntrack log icmp update + +</div> + +<div class="cfgcmd"> + +set system conntrack log other destroy + +</div> + +<div class="cfgcmd"> + +set system conntrack log other new + +</div> + +<div class="cfgcmd"> + +set system conntrack log other update + +</div> + +<div class="cfgcmd"> + +set system conntrack log tcp destroy + +</div> + +<div class="cfgcmd"> + +set system conntrack log tcp new + +</div> + +<div class="cfgcmd"> + +set system conntrack log tcp update close-wait + +</div> + +<div class="cfgcmd"> + +set system conntrack log tcp update established + +</div> + +<div class="cfgcmd"> + +set system conntrack log tcp update fin-wait + +</div> + +<div class="cfgcmd"> + +set system conntrack log tcp update last-ack + +</div> + +<div class="cfgcmd"> + +set system conntrack log tcp update syn-received + +</div> + +<div class="cfgcmd"> + +set system conntrack log tcp update time-wait + +</div> + +<div class="cfgcmd"> + +set system conntrack log udp destroy + +</div> + +<div class="cfgcmd"> + +set system conntrack log udp new + +</div> + +<div class="cfgcmd"> + +set system conntrack log udp update + +Log the connection tracking events per protocol. + +</div> diff --git a/docs/configuration/system/md-console.md b/docs/configuration/system/md-console.md new file mode 100644 index 00000000..3a58301d --- /dev/null +++ b/docs/configuration/system/md-console.md @@ -0,0 +1,59 @@ +# 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 `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. + +<div class="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 + +</div> + +<div class="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) + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +</div> diff --git a/docs/configuration/system/md-default-route.md b/docs/configuration/system/md-default-route.md new file mode 100644 index 00000000..c973dc09 --- /dev/null +++ b/docs/configuration/system/md-default-route.md @@ -0,0 +1,48 @@ +# Default Gateway/Route + +In the past (VyOS 1.1) used a gateway-address configured under the system tree +(`set system gateway-address <address>`), this is no longer supported +and existing configurations are migrated to the new CLI command. + +## Configuration + +<div class="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 <span class="title-ref">\<address\></span>. + +</div> + +<div class="cfgcmd"> + +delete protocols static route 0.0.0.0/0 + +Delete default route from the system. + +</div> + +## Operation + +<div class="opcmd"> + +show ip route 0.0.0.0 + +Show routing table entry for the default route. + +``` 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 +``` + +</div> + +<div class="seealso"> + +Configuration of `routing-static` + +</div> diff --git a/docs/configuration/system/md-flow-accounting.md b/docs/configuration/system/md-flow-accounting.md new file mode 100644 index 00000000..3a66fce5 --- /dev/null +++ b/docs/configuration/system/md-flow-accounting.md @@ -0,0 +1,312 @@ +# 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. + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +You need to disable the in-memory table in production environments! +Using `IMT (In-Memory Table)` may lead to heavy CPU overloading and +unstable flow-accounting behavior. + +</div> + +## 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 + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +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. + +</div> + +In order for flow accounting information to be collected and displayed for an +interface, the interface must be configured for flow accounting. + +<div class="cfgcmd"> + +set system flow-accounting interface \<interface\> + +Configure and enable collection of flow information for the interface +identified by <span class="title-ref">\<interface\></span>. + +You can configure multiple interfaces which whould participate in flow +accounting. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Will be recorded only packets/flows on **incoming** direction in +configured interfaces by default. + +</div> + +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: + +<div class="cfgcmd"> + +set system flow-accounting disable-imt + +If you need to sample also egress traffic, you may want to +configure egress flow-accounting: + +</div> + +<div class="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: + +</div> + +<div class="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: + +</div> + +<div class="cfgcmd"> + +set system flow-accounting syslog-facility \<facility\> + +TBD + +</div> + +### Flow Export + +In addition to displaying flow accounting information locally, one can also +exported them to a collection server. + +#### NetFlow + +<div class="cfgcmd"> + +set system flow-accounting netflow version \<version\> + +There are multiple versions available for the NetFlow data. The <span class="title-ref">\<version\></span> +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** - `IPFIX (IP Flow Information Export)` as per `3917` + +</div> + +<div class="cfgcmd"> + +set system flow-accounting netflow server \<address\> + +Configure address of NetFlow collector. NetFlow server at <span class="title-ref">\<address\></span> can +be both listening on an IPv4 or IPv6 address. + +</div> + +<div class="cfgcmd"> + +set system flow-accounting netflow source-ip \<address\> + +IPv4 or IPv6 source address of NetFlow packets + +</div> + +<div class="cfgcmd"> + +set system flow-accounting netflow engine-id \<id\> + +NetFlow engine-id which will appear in NetFlow data. The range is 0 to 255. + +</div> + +<div class="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 <span class="title-ref">\<rate\></span> packets, where <span class="title-ref">\<rate\></span> 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). + +</div> + +<div class="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. + +</div> + +<div class="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). + +</div> + +#### sFlow + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Using <span class="title-ref">system sflow</span> is recommended in favor of +<span class="title-ref">system flow-accounting</span>. See [sflow](sflow.html) + +</div> + +<div class="cfgcmd"> + +set system flow-accounting sflow server \<address\> + +Configure address of sFlow collector. sFlow server at <span class="title-ref">\<address\></span> can +be an IPv4 or IPv6 address. But you cannot export to both IPv4 and +IPv6 collectors at the same time! + +</div> + +<div class="cfgcmd"> + +set system flow-accounting sflow sampling-rate \<rate\> + +Enable sampling of packets, which will be transmitted to sFlow collectors. + +</div> + +<div class="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. + +</div> + +### 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. + +<div class="opcmd"> + +show flow-accounting interface \<interface\> + +Show flow accounting information for given <span class="title-ref">\<interface\></span>. + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show flow-accounting interface \<interface\> host \<address\> + +Show flow accounting information for given <span class="title-ref">\<interface\></span> for a specific host +only. + +``` 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 +``` + +</div> diff --git a/docs/configuration/system/md-frr.md b/docs/configuration/system/md-frr.md new file mode 100644 index 00000000..7116d1de --- /dev/null +++ b/docs/configuration/system/md-frr.md @@ -0,0 +1,50 @@ +# 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. + +<div class="cfgcmd"> + +set system frr bmp + +Enable `BMP (BGP Monitoring Protocol)` support + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set system frr irdp + +Enable ICMP Router Discovery Protocol support + +</div> + +<div class="cfgcmd"> + +set system frr snmp \<daemon\> + +Enable SNMP support for an individual routing daemon. + +Supported daemons: + +- bgpd +- isisd +- ldpd +- ospf6d +- ospfd +- ripd +- zebra + +</div> diff --git a/docs/configuration/system/md-host-name.md b/docs/configuration/system/md-host-name.md new file mode 100644 index 00000000..ebb83a5f --- /dev/null +++ b/docs/configuration/system/md-host-name.md @@ -0,0 +1,86 @@ +# 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. + +<div class="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 <span class="title-ref">vyos</span>. + +</div> + +## 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 <span class="title-ref">example.com</span>, and you would ping the +unqualified name of <span class="title-ref">crux</span>, then VyOS qualifies the name to <span class="title-ref">crux.example.com</span>. + +<div class="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. + +</div> + +## Static Hostname Mapping + +How an IP address is assigned to an interface in `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 +<span class="title-ref">/etc/hosts</span> file entries. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Do *not* manually edit <span class="title-ref">/etc/hosts</span>. 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. + +</div> + +<div class="cfgcmd"> + +set system static-host-mapping host-name \<hostname\> inet \<address\> + +Create a static hostname mapping which will always resolve the name +<span class="title-ref">\<hostname\></span> to IP address <span class="title-ref">\<address\></span>. + +</div> + +<div class="cfgcmd"> + +set system static-host-mapping host-name \<hostname\> alias \<alias\> + +Create named <span class="title-ref">\<alias\></span> for the configured static mapping for <span class="title-ref">\<hostname\></span>. +Thus the address configured as `set system static-host-mapping +host-name <hostname> inet <address>` can be reached via multiple names. + +Multiple aliases can be specified per host-name. + +</div> diff --git a/docs/configuration/system/md-index.md b/docs/configuration/system/md-index.md new file mode 100644 index 00000000..ea77a2c6 --- /dev/null +++ b/docs/configuration/system/md-index.md @@ -0,0 +1,31 @@ +# System + +<div class="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 + +</div> + +<div class="toctree" maxdepth="1" includehidden=""> + +default-route + +</div> diff --git a/docs/configuration/system/md-ip.md b/docs/configuration/system/md-ip.md new file mode 100644 index 00000000..cbdc53c4 --- /dev/null +++ b/docs/configuration/system/md-ip.md @@ -0,0 +1,132 @@ +# IP + +## System configuration commands + +<div class="cfgcmd"> + +set system ip disable-forwarding + +Use this command to disable IPv4 forwarding on all interfaces. + +</div> + +<div class="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. + +</div> + +<div class="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). + +</div> + +<div class="cfgcmd"> + +set system ip multipath layer4-hashing + +Use this command to use Layer 4 information for IPv4 ECMP hashing. + +</div> + +### 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. + +<div class="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 + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you choose any as the option that will cause all protocols that +are sending routes to zebra. + +</div> + +</div> + +### 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. + +<div class="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. + +</div> + +## 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..47b775e6 --- /dev/null +++ b/docs/configuration/system/md-ipv6.md @@ -0,0 +1,278 @@ +# IPv6 + +## System configuration commands + +<div class="cfgcmd"> + +set system ipv6 disable-forwarding + +Use this command to disable IPv6 forwarding on all interfaces. + +</div> + +<div class="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). + +</div> + +<div class="cfgcmd"> + +set system ipv6 strict-dad + +Use this command to disable IPv6 operation on interface when +Duplicate Address Detection fails on Link-Local address. + +</div> + +<div class="cfgcmd"> + +set system ipv6 multipath layer4-hashing + +Use this command to user Layer 4 information for ECMP hashing. + +</div> + +### 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. + +<div class="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 + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you choose any as the option that will cause all protocols that +are sending routes to zebra. + +</div> + +</div> + +### 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. + +<div class="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. + +</div> + +## Operational commands + +### Show commands + +<div class="opcmd"> + +show ipv6 neighbors + +Use this command to show IPv6 Neighbor Discovery Protocol information. + +</div> + +<div class="opcmd"> + +show ipv6 groups + +Use this command to show IPv6 multicast group membership. + +</div> + +<div class="opcmd"> + +show ipv6 forwarding + +Use this command to show IPv6 forwarding status. + +</div> + +<div class="opcmd"> + +show ipv6 route + +Use this command to show IPv6 routes. + +Check the many parameters available for the <span class="title-ref">show ipv6 route</span> command: + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show ipv6 prefix-list + +Use this command to show all IPv6 prefix lists + +There are different parameters for getting prefix-list information: + +``` 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 +``` + +</div> + +<div class="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: + +``` none +vyos@vyos:~$ show ipv6 access-list +Possible completions: + <Enter> Execute the current command + <text> Show specified IPv6 access-list +``` + +</div> + +<div class="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: + +``` 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 +``` + +</div> + +<div class="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: + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show ipv6 ripng + +Use this command to get information about the RIPNG protocol + +</div> + +<div class="opcmd"> + +show ipv6 ripng status + +Use this command to show the status of the RIPNG protocol + +</div> + +### Reset commands + +<div class="opcmd"> + +reset bgp ipv6 \<address\> + +Use this command to clear Border Gateway Protocol statistics or +status. + +</div> + +<div class="opcmd"> + +reset ipv6 neighbors \<address | interface\> + +Use this command to reset IPv6 Neighbor Discovery Protocol cache for +an address or interface. + +</div> + +<div class="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. + +</div> diff --git a/docs/configuration/system/md-lcd.md b/docs/configuration/system/md-lcd.md new file mode 100644 index 00000000..b5a50b3c --- /dev/null +++ b/docs/configuration/system/md-lcd.md @@ -0,0 +1,52 @@ +# System Display (LCD) + +The system LCD `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 +(<span class="title-ref">ttySxx</span>) or serial via USB or even old parallel port interfaces. + +## Configuration + +<div class="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: `hardware_usb`. + +</div> + +<div class="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 + +<div class="note"> + +<div class="title"> + +Note + +</div> + +We can't support all displays from the beginning. If your display +type is missing, please create a feature request via [Phabricator](). + +</div> + +</div> diff --git a/docs/configuration/system/md-login.md b/docs/configuration/system/md-login.md new file mode 100644 index 00000000..253e3673 --- /dev/null +++ b/docs/configuration/system/md-login.md @@ -0,0 +1,549 @@ +lastproofread +2022-10-15 + +# Login/User Management + +The default VyOS user account (<span class="title-ref">vyos</span>), 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 `RADIUS (Remote +Authentication Dial-In User Service)` accounts are supported. + +## Local + +<div class="cfgcmd"> + +set system login user \<name\> full-name "\<string\>" + +Create new system user with username <span class="title-ref">\<name\></span> and real-name specified by +<span class="title-ref">\<string\></span>. + +</div> + +<div class="cfgcmd"> + +set system login user \<name\> authentication plaintext-password +\<password\> + +Specify the plaintext password user by user <span class="title-ref">\<name\></span> on this system. The +plaintext password will be automatically transferred into a secure hashed +password and not saved anywhere in plaintext. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set system login user \<name\> disable + +Disable (lock) account. User will not be able to log in. + +</div> + +### 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. + +<div class="seealso"> + +SSH `ssh_operation` + +</div> + +<div class="cfgcmd"> + +set system login user \<username\> authentication public-keys +\<identifier\> key \<key\> + +Assign the SSH public key portion <span class="title-ref">\<key\></span> identified by per-key +<span class="title-ref">\<identifier\></span> to the local user <span class="title-ref">\<username\></span>. + +</div> + +<div class="cfgcmd"> + +set system login user \<username\> authentication public-keys +\<identifier\> type \<type\> + +Every SSH public key portion referenced by <span class="title-ref">\<identifier\></span> requires the +configuration of the <span class="title-ref">\<type\></span> 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` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +You can assign multiple keys to the same user by using a unique +identifier per SSH key. + +</div> + +</div> + +<div class="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. + +</div> + +### MFA/2FA authentication using OTP (one time passwords) + +It is possible to enhance authentication security by using the `2FA +(Two-factor authentication)`/`MFA (Multi-factor authentication)` feature +together with `OTP (One-Time-Pad)` on VyOS. `2FA (Two-factor +authentication)`/`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. + +<div class="cfgcmd"> + +set system login user \<username\> authentication otp key \<key\> + +Enable OTP 2FA for user <span class="title-ref">username</span> with default settings, using the BASE32 +encoded 2FA/MFA key specified by <span class="title-ref">\<key\></span>. + +</div> + +#### Optional/default settings + +<div class="cfgcmd" defaultvalue=""> + +set system login user \<username\> authentication otp rate-limit \<limit\> + +Limit logins to <span class="title-ref">\<limit\></span> per every `rate-time` seconds. Rate limit +must be between 1 and 10 attempts. + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system login user \<username\> authentication otp rate-time \<seconds\> + +Limit logins to `rate-limit` attemps per every <span class="title-ref">\<seconds\></span>. Rate time must +be between 15 and 600 seconds. + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system login user \<username\> authentication otp window-size \<size\> + +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. + +</div> + +#### OTP-key generation + +The following command can be used to generate the OTP key as well +as the CLI commands to configure them: + +<div class="cfgcmd"> + +generate system login username \<username\> otp-key hotp-time +rate-limit \<1-10\> rate-time \<15-600\> window-size \<1-21\> + +</div> + +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: + +<div class="cfgcmd"> + +sh system login authentication user \<username\> otp +\<full[|key-b32|](##SUBST##|key-b32|)qrcode|uri\> + +</div> + +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 `RADIUS (Remote Authentication +Dial-In User Service)` servers as backend for user authentication. + +### Configuration + +<div class="cfgcmd"> + +set system login radius server \<address\> key \<secret\> + +Specify the IP <span class="title-ref">\<address\></span> of the RADIUS server user with the pre-shared-secret +given in <span class="title-ref">\<secret\></span>. + +Multiple servers can be specified. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set system login radius server \<address\> disable + +Temporary disable this RADIUS server. It won't be queried. + +</div> + +<div class="cfgcmd"> + +set system login radius server \<address\> timeout \<timeout\> + +Setup the <span class="title-ref">\<timeout\></span> in seconds when querying the RADIUS server. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set system login radius vrf \<name\> + +Source all connections to the RADIUS servers from given VRF <span class="title-ref">\<name\></span>. + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +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. + +</div> + +## TACACS+ + +In addition to `RADIUS (Remote Authentication Dial-In User Service)`, +`TACACS (Terminal Access Controller Access Control System)` can also be +found in large deployments. +VyOS only supports <span class="title-ref">Authentication</span> via <span class="title-ref">TACACS+</span> servers but does not support <span class="title-ref">Authorization</span> or <span class="title-ref">Accounting</span> yet + +TACACS is defined in `8907`. + +### Configuration + +<div class="cfgcmd"> + +set system login tacas server \<address\> key \<secret\> + +Specify the IP <span class="title-ref">\<address\></span> of the TACACS server user with the pre-shared-secret +given in <span class="title-ref">\<secret\></span>. + +Multiple servers can be specified. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set system login tacas server \<address\> disable + +Temporary disable this TACACS server. It won't be queried. + +</div> + +<div class="cfgcmd"> + +set system login tacas server \<address\> timeout \<timeout\> + +Setup the <span class="title-ref">\<timeout\></span> in seconds when querying the TACACS server. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set system login tacas vrf \<name\> + +Source all connections to the TACACS servers from given VRF <span class="title-ref">\<name\></span>. + +</div> + +## Login Banner + +You are able to set post-login or pre-login banner messages to display certain +information for this system. + +<div class="cfgcmd"> + +set system login banner pre-login \<message\> + +Configure <span class="title-ref">\<message\></span> which is shown during SSH connect and before a user is +logged in. + +</div> + +<div class="cfgcmd"> + +set system login banner post-login \<message\> + +Configure <span class="title-ref">\<message\></span> which is shown after user has logged in to the system. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +To create a new line in your login message you need to escape the new +line character by using `\\n`. + +</div> + +## Limits + +Login limits + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set system login timeout \<timeout\> + +Configure session timeout after which the user will be logged out. + +</div> + +## Example + +In the following example, both <span class="title-ref">User1</span> and <span class="title-ref">User2</span> will be able to SSH into +VyOS as user `vyos` using their very own keys. <span class="title-ref">User1</span> 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..ea544b16 --- /dev/null +++ b/docs/configuration/system/md-name-server.md @@ -0,0 +1,81 @@ +# System DNS + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +If you are configuring a VRF for management purposes, there is +currently no way to force system DNS traffic via a specific VRF. + +</div> + +This section describes configuring DNS on the system, namely: + +> - DNS name servers +> - Domain search order + +## DNS name servers + +<div class="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. + +</div> + +### 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. + +<div class="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. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Domain names can include letters, numbers, hyphens and periods +with a maximum length of 253 characters. + +</div> + +### 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..8ad69d76 --- /dev/null +++ b/docs/configuration/system/md-option.md @@ -0,0 +1,262 @@ +# Option + +This chapter describe the possibilities of advanced system behavior. + +## General + +<div class="cfgcmd"> + +set system option ctrl-alt-delete \<ignore | reboot | poweroff\> + +Action which will be run once the ctrl-alt-del keystroke is received. + +</div> + +<div class="cfgcmd"> + +set system option reboot-on-panic + +Automatically reboot system on kernel panic after 60 seconds. + +</div> + +<div class="cfgcmd"> + +set system option startup-beep + +Play an audible beep to the system speaker when system is ready. + +</div> + +<div class="cfgcmd"> + +set system option root-partition-auto-resize + +Enables the root partition auto-extension and resizes to the maximum +available space on system boot. + +</div> + +### Kernel + +<div class="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` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Setting will only become active with the next reboot! + +</div> + +</div> + +<div class="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 + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Setting will only become active with the next reboot! + +</div> + +</div> + +<div class="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 + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Setting will only become active with the next reboot! + +</div> + +<div class="seealso"> + +<https://docs.kernel.org/admin-guide/pm/amd-pstate.html> + +</div> + +</div> + +<div class="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. + +</div> + +## HTTP client + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +<span class="title-ref">source-address</span> and <span class="title-ref">source-interface</span> can not be used at the same +time. + +</div> + +## SSH client + +<div class="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. + +</div> + +<div class="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. + +</div> + +## 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. + +<div class="cfgcmd"> + +set system option keyboard-layout \<us | fr | de | fi | no | dk\> + +Change system keyboard layout to given language. + +Defaults to `us`. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +</div> + +## Performance + +As more and more routers run on Hypervisors, expecially with a `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 <span class="title-ref">tuned</span> for dynamic resource balancing based on profiles. + +<div class="seealso"> + +<https://access.redhat.com/sites/default/files/attachments/201501-perf-brief-low-latency-tuning-rhel7-v2.1.pdf> + +</div> + +<div class="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. + +</div> diff --git a/docs/configuration/system/md-proxy.md b/docs/configuration/system/md-proxy.md new file mode 100644 index 00000000..911392ad --- /dev/null +++ b/docs/configuration/system/md-proxy.md @@ -0,0 +1,40 @@ +# 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 `add system image` command (`update_vyos`). + +<div class="cfgcmd"> + +set system proxy url \<url\> + +Set proxy for all connections initiated by VyOS, including HTTP, HTTPS, and +FTP (anonymous ftp). + +</div> + +<div class="cfgcmd"> + +set system proxy port \<port\> + +Configure proxy port if it does not listen to the default port 80. + +</div> + +<div class="cfgcmd"> + +set system proxy username \<username\> + +Some proxys require/support the "basic" HTTP authentication scheme as per +`7617`, thus a username can be configured. + +</div> + +<div class="cfgcmd"> + +set system proxy password \<password\> + +Some proxys require/support the "basic" HTTP authentication scheme as per +`7617`, thus a password can be configured. + +</div> diff --git a/docs/configuration/system/md-sflow.md b/docs/configuration/system/md-sflow.md new file mode 100644 index 00000000..b64de63f --- /dev/null +++ b/docs/configuration/system/md-sflow.md @@ -0,0 +1,81 @@ +# 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 + +<div class="cfgcmd"> + +set system sflow agent-address \<address\> + +Configure sFlow agent IPv4 or IPv6 address + +</div> + +<div class="cfgcmd"> + +set system sflow agent-interface \<interface\> + +Configure agent IP address associated with this interface. + +</div> + +<div class="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 + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set system sflow polling \<sec\> + +Configure schedule counter-polling in seconds (default: 30) + +</div> + +<div class="cfgcmd"> + +set system sflow sampling-rate \<rate\> + +Use this command to configure the sampling rate for sFlow accounting (default: 1000) + +</div> + +<div class="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. + +</div> + +## 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..2786ceea --- /dev/null +++ b/docs/configuration/system/md-sysctl.md @@ -0,0 +1,12 @@ +# 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/. + +<div class="cfgcmd"> + +set system sysctl parameter \<parameter\> value \<value\> + +</div> diff --git a/docs/configuration/system/md-syslog.md b/docs/configuration/system/md-syslog.md new file mode 100644 index 00000000..fc4d5eef --- /dev/null +++ b/docs/configuration/system/md-syslog.md @@ -0,0 +1,606 @@ +# 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 +<span class="title-ref">local7</span> 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 `IP (Internet Protocol)` UDP/TCP. + +### Console + +<div class="cfgcmd"> + +set system syslog console facility \<keyword\> level \<keyword\> + +Log syslog messages to `/dev/console`, for an explanation on +`syslog_facilities` keywords and `syslog_severity_level` keywords +see tables below. + +</div> + +### Custom File + +<div class="cfgcmd"> + +set system syslog file \<filename\> facility \<keyword\> level \<keyword\> + +Log syslog messages to file specified via <span class="title-ref">\<filename\></span>, for an explanation on +`syslog_facilities` keywords and `syslog_severity_level` keywords +see tables below. + +</div> + +<div class="cfgcmd"> + +set system syslog file \<filename\> archive size \<size\> + +Syslog will write <span class="title-ref">\<size\></span> kilobytes into the file specified by <span class="title-ref">\<filename\></span>. +After this limit has been reached, the custom file is "rotated" by logrotate +and a new custom file is created. + +</div> + +<div class="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 <span class="title-ref">\<number\></span> rotated file before they are deleted on the +system. + +</div> + +### 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. + +<div class="cfgcmd"> + +set system syslog host \<address\> facility \<keyword\> level \<keyword\> + +Log syslog messages to remote host specified by <span class="title-ref">\<address\></span>. The address +can be specified by either FQDN or IP address. For an explanation on +`syslog_facilities` keywords and `syslog_severity_level` +keywords see tables below. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set system syslog vrf \<name\> + +Specify name of the `VRF (Virtual Routing and Forwarding)` instance. + +</div> + +#### `TLS (Transport Layer Security)`-encrypted remote logging + +VyOS supports `TLS (Transport Layer Security)`-encrypted remote logging +over TCP to ensure secure transmission of syslog data to remote syslog servers. + +**Prerequisites**: Before configuring `TLS (Transport Layer +Security)`-encrypted remote logging, ensure you have: + +- A valid remote syslog server address. + +- Valid `CA (Certificate Authority)` and client certificates uploaded + to the local `PKI (Public Key Infrastructure)` storage. + +- The **remote syslog transport protocol** is set to **TCP**: + + ``` none + set system syslog remote <address> protocol tcp + ``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +`TLS (Transport Layer Security)`-encrypted remote logging is +**not supported** over **UDP**. + +</div> + +<div class="cfgcmd"> + +set system syslog remote \<address\> tls + +Enable TLS-encrypted remote logging. + +</div> + +<div class="cfgcmd"> + +set system syslog remote \<address\> tls ca-certificate \<ca_name\> + +**Configure the** `CA (Certificate Authority)` **certificate.** + +The syslog client uses the `CA (Certificate Authority)` certificate to +verify the identity of the remote syslog server. + +The `CA (Certificate Authority)` certificate is required for **all** +authentication modes except `anon`. + +</div> + +<div class="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. + +</div> + +<div class="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 + `MITM (Man-in-the-Middle)` attacks. + +- `fingerprint`: Verifies the server’s certificate fingerprint against the + value preconfigured with: + + ``` none + set system syslog remote <address> tls permitted-peer <peer> + ``` + +- `certvalid`: Verifies the server certificate is signed by a trusted + `CA (Certificate Authority)`, skipping `CN (Common Name)` check. + +- `name`: Verifies that: + + - The server’s certificate is signed by a trusted `CA (Certificate + Authority)`. + - The `CN (Common Name)` in the certificate matches the value + preconfigured with: + + ``` none + set system syslog remote <address> tls permitted-peer <peer> + ``` + + This is a **recommended** secure mode for production environments. + +</div> + +<div class="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 `CNs (Common Names)`. + +For `anon` and `certvalid` authentication modes, certificate identifiers +are not required. + +</div> + +#### 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 + `PKI system </configuration/pki/index>`. + +### Local User Account + +<div class="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 +`syslog_facilities` keywords and `syslog_severity_level` keywords +see tables below. + +</div> + +## 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: + +<table style="width:99%;"> +<colgroup> +<col style="width: 14%" /> +<col style="width: 14%" /> +<col style="width: 69%" /> +</colgroup> +<thead> +<tr> +<th>Facility +Code</th> +<th>Keyword</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td></td> +<td>all</td> +<td>All facilities</td> +</tr> +<tr> +<td>0</td> +<td>kern</td> +<td>Kernel messages</td> +</tr> +<tr> +<td>1</td> +<td>user</td> +<td>User-level messages</td> +</tr> +<tr> +<td>2</td> +<td>mail</td> +<td>Mail system</td> +</tr> +<tr> +<td>3</td> +<td>daemon</td> +<td>System daemons</td> +</tr> +<tr> +<td>4</td> +<td>auth</td> +<td>Security/authentication messages</td> +</tr> +<tr> +<td>5</td> +<td>syslog</td> +<td>Messages generated internally by syslogd</td> +</tr> +<tr> +<td>6</td> +<td>lpr</td> +<td>Line printer subsystem</td> +</tr> +<tr> +<td>7</td> +<td>news</td> +<td>Network news subsystem</td> +</tr> +<tr> +<td>8</td> +<td>uucp</td> +<td>UUCP subsystem</td> +</tr> +<tr> +<td>9</td> +<td>cron</td> +<td>Clock daemon</td> +</tr> +<tr> +<td>10</td> +<td>security</td> +<td>Security/authentication messages</td> +</tr> +<tr> +<td>11</td> +<td>ftp</td> +<td>FTP daemon</td> +</tr> +<tr> +<td>12</td> +<td>ntp</td> +<td>NTP subsystem</td> +</tr> +<tr> +<td>13</td> +<td>logaudit</td> +<td>Log audit</td> +</tr> +<tr> +<td>14</td> +<td>logalert</td> +<td>Log alert</td> +</tr> +<tr> +<td>15</td> +<td>clock</td> +<td>clock daemon (note 2)</td> +</tr> +<tr> +<td>16</td> +<td>local0</td> +<td>local use 0 (local0)</td> +</tr> +<tr> +<td>17</td> +<td>local1</td> +<td>local use 1 (local1)</td> +</tr> +<tr> +<td>18</td> +<td>local2</td> +<td>local use 2 (local2)</td> +</tr> +<tr> +<td>19</td> +<td>local3</td> +<td>local use 3 (local3)</td> +</tr> +<tr> +<td>20</td> +<td>local4</td> +<td>local use 4 (local4)</td> +</tr> +<tr> +<td>21</td> +<td>local5</td> +<td>local use 5 (local5)</td> +</tr> +<tr> +<td>22</td> +<td>local6</td> +<td><blockquote> +<p>use 6 (local6)</p> +</blockquote></td> +</tr> +<tr> +<td>23</td> +<td>local7</td> +<td>local use 7 (local7)</td> +</tr> +</tbody> +</table> + +## Severity Level + +<table style="width:98%;"> +<colgroup> +<col style="width: 10%" /> +<col style="width: 20%" /> +<col style="width: 12%" /> +<col style="width: 55%" /> +</colgroup> +<thead> +<tr> +<th>Value</th> +<th>Severity</th> +<th>Keyword</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td></td> +<td></td> +<td>all</td> +<td>Log everything</td> +</tr> +<tr> +<td>0</td> +<td>Emergency</td> +<td>emerg</td> +<td>System is unusable - a panic condition</td> +</tr> +<tr> +<td>1</td> +<td>Alert</td> +<td>alert</td> +<td>Action must be taken immediately - A +condition that should be corrected +immediately, such as a corrupted system +database.</td> +</tr> +<tr> +<td>2</td> +<td>Critical</td> +<td>crit</td> +<td>Critical conditions - e.g. hard drive +errors.</td> +</tr> +<tr> +<td>3</td> +<td>Error</td> +<td>err</td> +<td>Error conditions</td> +</tr> +<tr> +<td>4</td> +<td>Warning</td> +<td>warning</td> +<td>Warning conditions</td> +</tr> +<tr> +<td>5</td> +<td>Notice</td> +<td>notice</td> +<td>Normal but significant conditions - +conditions that are not error conditions, +but that may require special handling.</td> +</tr> +<tr> +<td>6</td> +<td>Informational</td> +<td>info</td> +<td>Informational messages</td> +</tr> +<tr> +<td>7</td> +<td>Debug</td> +<td>debug</td> +<td>Debug-level messages - Messages that +contain information normally of use only +when debugging a program.</td> +</tr> +</tbody> +</table> + +## Display Logs + +<div class="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 + +</div> + +If no option is specified, this defaults to <span class="title-ref">all</span>. + +<div class="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: + +<table> +<colgroup> +<col style="width: 25%" /> +<col style="width: 75%" /> +</colgroup> +<tbody> +<tr> +<td>all</td> +<td>Display contents of all master log files of the specified image</td> +</tr> +<tr> +<td>authorization</td> +<td>Display all authorization attempts of the specified image</td> +</tr> +<tr> +<td>directory</td> +<td>Display list of all user-defined log files of the specified image</td> +</tr> +<tr> +<td>file <file name></td> +<td>Display contents of a specified user-defined log file of the specified +image</td> +</tr> +<tr> +<td>tail</td> +<td>Display last lines of the system log of the specified image</td> +</tr> +<tr> +<td><lines></td> +<td>Number of lines to be displayed, default 10</td> +</tr> +</tbody> +</table> + +</div> + +When no options/parameters are used, the contents of the main syslog file are +displayed. + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +Use `show log | strip-private` if you want to hide private data +when sharing your logs. + +</div> + +## Delete Logs + +<div class="opcmd"> + +delete log file \<text\> + +</div> + +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 `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..9a43b430 --- /dev/null +++ b/docs/configuration/system/md-task-scheduler.md @@ -0,0 +1,70 @@ +# Task Scheduler + +The task scheduler allows you to execute tasks on a given schedule. It makes +use of UNIX [cron](https://en.wikipedia.org/wiki/Cron). + +<div class="note"> + +<div class="title"> + +Note + +</div> + +All scripts excecuted this way are executed as root user - this may +be dangerous. Together with `command-scripting` this can be used for +automating (re-)configuration. + +</div> + +<div class="cfgcmd"> + +set system task-scheduler task \<task\> interval \<interval\> + +Specify the time interval when <span class="title-ref">\<task\></span> 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 + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If suffix is omitted, minutes are implied. + +</div> + +</div> + +<div class="cfgcmd"> + +set system task-scheduler task \<task\> crontab-spec \<spec\> + +Set execution time in common [cron](https://en.wikipedia.org/wiki/Cron) time format. A cron <span class="title-ref">\<spec\></span> of +`30 */6 * * *` would execute the <span class="title-ref">\<task\></span> at minute 30 past every 6th hour. + +</div> + +<div class="cfgcmd"> + +set system task-scheduler task \<task\> executable path \<path\> + +Specify absolute <span class="title-ref">\<path\></span> to script which will be run when <span class="title-ref">\<task\></span> is +executed. + +</div> + +<div class="cfgcmd"> + +set system task-scheduler task \<task\> executable arguments \<args\> + +Arguments which will be passed to the executable. + +</div> diff --git a/docs/configuration/system/md-time-zone.md b/docs/configuration/system/md-time-zone.md new file mode 100644 index 00000000..20f24b41 --- /dev/null +++ b/docs/configuration/system/md-time-zone.md @@ -0,0 +1,18 @@ +# 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. + +<div class="cfgcmd"> + +set system time-zone \<timezone\> + +Specify the systems <span class="title-ref">\<timezone\></span> 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. + +</div> diff --git a/docs/configuration/system/md-updates.md b/docs/configuration/system/md-updates.md new file mode 100644 index 00000000..4e0460ac --- /dev/null +++ b/docs/configuration/system/md-updates.md @@ -0,0 +1,39 @@ +# Updates + +VyOS supports online checking for updates + +## Configuration + +<div class="cfgcmd"> + +set system update-check auto-check + +Configure auto-checking for new images + +</div> + +<div class="cfgcmd"> + +set system update-check url \<url\> + +Configure a URL that contains information about images. + +</div> + +## 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..de67ee11 --- /dev/null +++ b/docs/configuration/trafficpolicy/md-index.md @@ -0,0 +1,1738 @@ +# 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](https://en.wikipedia.org/wiki/Tc_(Linux)) 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 + +In the `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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +``` 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](https://blog.vyos.io/using-the-policy-route-and-packet-marking-for-custom-qos-matches). + +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" +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +An IPv4 TCP filter will only match packets with an IPv4 header +length of 20 bytes (which is the majority of IPv4 packets anyway). + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +IPv6 TCP filters will only match IPv6 packets with no header +extension, see <https://en.wikipedia.org/wiki/IPv6_packet#Extension_headers> + +</div> + +#### 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 `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 `2474` and `4595`: +> +> <table style="width:88%;"> +> <colgroup> +> <col style="width: 13%" /> +> <col style="width: 18%" /> +> <col style="width: 12%" /> +> <col style="width: 43%" /> +> </colgroup> +> <thead> +> <tr> +> <th>Binary +> value</th> +> <th>Configured +> value</th> +> <th><blockquote> +> <p>Drop +> rate</p> +> </blockquote></th> +> <th>Description</th> +> </tr> +> </thead> +> <tbody> +> <tr> +> <td>101110</td> +> <td><blockquote> +> <p>46</p> +> </blockquote></td> +> <td><blockquote> +> <ul> +> <li></li> +> </ul> +> </blockquote></td> +> <td>Expedited forwarding (EF)</td> +> </tr> +> <tr> +> <td>000000</td> +> <td><blockquote> +> <p>0</p> +> </blockquote></td> +> <td><blockquote> +> <ul> +> <li></li> +> </ul> +> </blockquote></td> +> <td>Best effort traffic, default</td> +> </tr> +> <tr> +> <td>001010</td> +> <td><blockquote> +> <p>10</p> +> </blockquote></td> +> <td>Low</td> +> <td>Assured Forwarding(AF) 11</td> +> </tr> +> <tr> +> <td>001100</td> +> <td><blockquote> +> <p>12</p> +> </blockquote></td> +> <td>Medium</td> +> <td>Assured Forwarding(AF) 12</td> +> </tr> +> <tr> +> <td>001110</td> +> <td><blockquote> +> <p>14</p> +> </blockquote></td> +> <td>High</td> +> <td>Assured Forwarding(AF) 13</td> +> </tr> +> <tr> +> <td>010010</td> +> <td><blockquote> +> <p>18</p> +> </blockquote></td> +> <td>Low</td> +> <td>Assured Forwarding(AF) 21</td> +> </tr> +> <tr> +> <td>010100</td> +> <td><blockquote> +> <p>20</p> +> </blockquote></td> +> <td>Medium</td> +> <td>Assured Forwarding(AF) 22</td> +> </tr> +> <tr> +> <td>010110</td> +> <td><blockquote> +> <p>22</p> +> </blockquote></td> +> <td>High</td> +> <td>Assured Forwarding(AF) 23</td> +> </tr> +> <tr> +> <td>011010</td> +> <td><blockquote> +> <p>26</p> +> </blockquote></td> +> <td>Low</td> +> <td>Assured Forwarding(AF) 31</td> +> </tr> +> <tr> +> <td>011100</td> +> <td><blockquote> +> <p>28</p> +> </blockquote></td> +> <td>Medium</td> +> <td>Assured Forwarding(AF) 32</td> +> </tr> +> <tr> +> <td>011110</td> +> <td><blockquote> +> <p>30</p> +> </blockquote></td> +> <td>High</td> +> <td>Assured Forwarding(AF) 33</td> +> </tr> +> <tr> +> <td>100010</td> +> <td><blockquote> +> <p>34</p> +> </blockquote></td> +> <td>Low</td> +> <td>Assured Forwarding(AF) 41</td> +> </tr> +> <tr> +> <td>100100</td> +> <td><blockquote> +> <p>36</p> +> </blockquote></td> +> <td>Medium</td> +> <td>Assured Forwarding(AF) 42</td> +> </tr> +> <tr> +> <td>100110</td> +> <td><blockquote> +> <p>38</p> +> </blockquote></td> +> <td>High</td> +> <td>Assured Forwarding(AF) 43</td> +> </tr> +> </tbody> +> </table> + +#### 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 <span class="title-ref">queue-type</span> +setting allows these combinations. You will be able to use it +in many policies. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Some policies already include other embedded policies inside. +That is the case of [Shaper](#shaper): each of its classes use fair-queue +unless you change it. + +</div> + +### 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](#embed) a different +policy that will be applied to a class of the main policy. + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +**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](#shaper) **policy and you want to** +`set its queues <embed>` **as FQ-CoDel**. + +</div> + +#### 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.** + +<div class="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). + +</div> + +#### 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. + +<div class="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. + +</div> + +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. + +<div class="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). + +</div> + +When dequeuing, each hash-bucket with data is queried in a round robin +fashion. You can configure the length of the queue. + +<div class="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. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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](#embed) Fair-Queue into a classful shaping policy to make sure it owns +the queue. + +</div> + +#### 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](#DRR)) queue +scheduler with the CoDel Active Queue Management (AQM) algorithm +operating on each queue. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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](#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. + +</div> + +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 +<span class="title-ref">queue-limit</span> 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](#shaper) and you have large rates +(100Mbit and above), you may consider increasing <span class="title-ref">quantum</span> to 8000 or +higher so that the scheduler saves CPU. + +On low rates (below 40Mbit) you may want to tune <span class="title-ref">quantum</span> down to +something like 300 bytes. + +At very low rates (below 3Mbit), besides tuning <span class="title-ref">quantum</span> (300 keeps +being ok) you may also want to increase <span class="title-ref">target</span> to something like 15ms +and increase <span class="title-ref">interval</span> to something around 150 ms. + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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). + +</div> + +<div class="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). + +</div> + +<div class="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). + +</div> + +##### 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](#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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +In the case you want to apply some kind of **shaping** to your +**inbound** traffic, check the [ingress-shaping](#ingress-shaping) section. + +</div> + +<div class="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. + +</div> + +Once the matching rules are set for a class, you can start configuring +how you want matching traffic to behave. + +<div class="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. + +</div> + +<div class="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). + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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). + +</div> + +#### 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. + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +#### 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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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](#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. + +</div> + +Up to seven queues -defined as [classes](#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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +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](#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) +``` + +<div class="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. + +</div> + +#### 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 `791`: + +> <table style="width:50%;"> +> <colgroup> +> <col style="width: 18%" /> +> <col style="width: 31%" /> +> </colgroup> +> <thead> +> <tr> +> <th>Precedence</th> +> <th><blockquote> +> <p>Priority</p> +> </blockquote></th> +> </tr> +> </thead> +> <tbody> +> <tr> +> <td><blockquote> +> <p>7</p> +> </blockquote></td> +> <td>Network Control</td> +> </tr> +> <tr> +> <td><blockquote> +> <p>6</p> +> </blockquote></td> +> <td>Internetwork Control</td> +> </tr> +> <tr> +> <td><blockquote> +> <p>5</p> +> </blockquote></td> +> <td>CRITIC/ECP</td> +> </tr> +> <tr> +> <td><blockquote> +> <p>4</p> +> </blockquote></td> +> <td>Flash Override</td> +> </tr> +> <tr> +> <td><blockquote> +> <p>3</p> +> </blockquote></td> +> <td>Flash</td> +> </tr> +> <tr> +> <td><blockquote> +> <p>2</p> +> </blockquote></td> +> <td>Immediate</td> +> </tr> +> <tr> +> <td><blockquote> +> <p>1</p> +> </blockquote></td> +> <td>Priority</td> +> </tr> +> <tr> +> <td><blockquote> +> <p>0</p> +> </blockquote></td> +> <td>Routine</td> +> </tr> +> </tbody> +> </table> + +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. + +<div class="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. + +</div> + +<div class="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). + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +When configuring a Random-Detect policy: **the higher the +precedence number, the higher the priority**. + +</div> + +<div class="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). + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +The default values for the minimum-threshold depend on IP precedence: + +> <table style="width:51%;"> +> <colgroup> +> <col style="width: 18%" /> +> <col style="width: 33%" /> +> </colgroup> +> <thead> +> <tr> +> <th>Precedence</th> +> <th>default min-threshold</th> +> </tr> +> </thead> +> <tbody> +> <tr> +> <td><blockquote> +> <p>7</p> +> </blockquote></td> +> <td><blockquote> +> <p>16</p> +> </blockquote></td> +> </tr> +> <tr> +> <td><blockquote> +> <p>6</p> +> </blockquote></td> +> <td><blockquote> +> <p>15</p> +> </blockquote></td> +> </tr> +> <tr> +> <td><blockquote> +> <p>5</p> +> </blockquote></td> +> <td><blockquote> +> <p>14</p> +> </blockquote></td> +> </tr> +> <tr> +> <td><blockquote> +> <p>4</p> +> </blockquote></td> +> <td><blockquote> +> <p>13</p> +> </blockquote></td> +> </tr> +> <tr> +> <td><blockquote> +> <p>3</p> +> </blockquote></td> +> <td><blockquote> +> <p>12</p> +> </blockquote></td> +> </tr> +> <tr> +> <td><blockquote> +> <p>2</p> +> </blockquote></td> +> <td><blockquote> +> <p>11</p> +> </blockquote></td> +> </tr> +> <tr> +> <td><blockquote> +> <p>1</p> +> </blockquote></td> +> <td><blockquote> +> <p>10</p> +> </blockquote></td> +> </tr> +> <tr> +> <td><blockquote> +> <p>0</p> +> </blockquote></td> +> <td><blockquote> +> <p>9</p> +> </blockquote></td> +> </tr> +> </tbody> +> </table> + +<div class="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. + +</div> + +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 +`min-threshold` \< `max-threshold` \< `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. + +<div class="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. + +</div> + +<div class="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. + +</div> + +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. + +<div class="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). + +</div> + +Rate-Control is a CPU-friendly policy. You might consider using it when +you just simply want to slow traffic down. + +#### 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](#classes) you can configure (up to 4096). You can [embed](#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. + +<div class="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. + +</div> + +<div class="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. + +</div> + +As with other policies, Round-Robin can [embed](#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 + +**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. + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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](https://en.wikipedia.org/wiki/Token_bucket) in bytes, which will +be available to be sent at ceiling speed (default: 15Kb). + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +As with other policies, Shaper can [embed](#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) +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +##### 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 + +**Queueing discipline:** Deficit mode.\ +**Applies to:** Outbound traffic. + +[Common Applications Kept Enhanced](https://www.bufferbloat.net/projects/codel/wiki/Cake/) (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. + +<div class="cfgcmd"> + +set qos policy cake \<text\> bandwidth \<value\> + +Set the shaper bandwidth, either as an explicit bitrate or a percentage +of the interface bandwidth. + +</div> + +<div class="cfgcmd"> + +set qos policy cake \<text\> description + +Set a description for the shaper. + +</div> + +<div class="cfgcmd"> + +set qos policy cake \<text\> flow-isolation blind + +Disables flow isolation, all traffic passes through a single queue. + +</div> + +<div class="cfgcmd"> + +set qos policy cake \<text\> flow-isolation dst-host + +Flows are defined only by destination address. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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). + +</div> + +<div class="cfgcmd"> + +set qos policy cake \<text\> flow-isolation host + +Flows are defined by source-destination host pairs. + +</div> + +<div class="cfgcmd"> + +set qos policy cake \<text\> flow-isolation nat + +Perform NAT lookup before applying flow-isolation rules. + +</div> + +<div class="cfgcmd"> + +set qos policy cake \<text\> flow-isolation src-host + +Flows are defined only by source address. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +### 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 +``` + +### 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](https://www.linuxfoundation.org/collaborate/workgroups/networking/ifb)). 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 +``` + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +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`. + +</div> diff --git a/docs/configuration/vpn/ipsec/md-index.md b/docs/configuration/vpn/ipsec/md-index.md new file mode 100644 index 00000000..f8ef0e17 --- /dev/null +++ b/docs/configuration/vpn/ipsec/md-index.md @@ -0,0 +1,15 @@ +# IPsec + +<div class="toctree" maxdepth="1" includehidden=""> + +ipsec_general +site2site_ipsec +troubleshooting_ipsec + +</div> + +pages to sort + +<div class="toctree" maxdepth="1" includehidden=""> + +</div> 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..1fbb5974 --- /dev/null +++ b/docs/configuration/vpn/ipsec/md-ipsec_general.md @@ -0,0 +1,399 @@ +# 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 `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 `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> +<img src="/_static/images/ESP_AH.webp" alt="AH and ESP in Transport Mode and Tunnel Mode" /> +</figure> + +## 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: `2409` (IKE), `3407` +(IPsec DOI), `3947` (NAT-T), `3948` (UDP Encapsulation +of ESP Packets), `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 `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: + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec ike-group \<name\> lifetime + +IKE lifetime in seconds \<0-86400\> (default 28800). + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec ike-group \<name\> proposal \<number\> dh-group \<dh-group number\> + +Diffie-Hellman algorithm group. Default value is **2**. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec ike-group \<name\> proposal \<number\> encryption \<encryption\> + +Encryption algorithm. Default value is **aes128**. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec ike-group \<name\> proposal \<number\> hash \<hash\> + +Hash algorithm. Default value is **sha1**. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec ike-group \<name\> proposal \<number\> prf \<prf\> + +Pseudo-random function. + +</div> + +### DPD (Dead Peer Detection) Configuration + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec ike-group \<name\> dead-peer-detection interval \<interval\> + +Keep-alive interval in seconds \<2-86400\> (default 30). + +</div> + +<div class="cfgcmd"> + +set vpn ipsec ike-group \<name\> dead-peer-detection timeout \<timeout\> + +Keep-alive timeout in seconds \<2-86400\> (default 120) **IKEv1 only** + +</div> + +### 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: + +<div class="cfgcmd"> + +set vpn ipsec esp-group \<name\> compression + +Enables the IPComp(IP Payload Compression) protocol which allows +compressing the content of IP packets. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec esp-group \<name\> mode \<mode\> + +The type of the connection: + +- **tunnel** - Tunnel mode (default). +- **transport** - Transport mode. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec esp-group \<name\> proposal \<number\> encryption \<encryption\> + +Encryption algorithm. Default value is **aes128**. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec esp-group \<name\> proposal \<number\> hash \<hash\> + +Hash algorithm. Default value is **sha1**. + +</div> + +### Global IPsec Settings + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec log level \<number\> + +Level of logging. Default value is **0**. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec log subsystem \<name\> + +Subsystem of the daemon. + +</div> + +### Options + +<div class="cfgcmd"> + +set vpn ipsec options disable-route-autoinstall + +Do not automatically install routes to remote +networks. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec options virtual-ip + +Allows the installation of virtual-ip addresses. + +</div> 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..356ae23a --- /dev/null +++ b/docs/configuration/vpn/ipsec/md-remoteaccess_ipsec.md @@ -0,0 +1,185 @@ +# 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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +``` 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..451ea1be --- /dev/null +++ b/docs/configuration/vpn/ipsec/md-site2site_ipsec.md @@ -0,0 +1,944 @@ +# 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 + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Strongswan recommends to use the same lifetime value on both peers + +</div> + +Phase 2 +- Encryption +- Hashing +- PFS +- Mode (tunnel or transport) +- Lifetime + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Strongswan recommends to use the same lifetime value on both peers + +</div> + +- 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 + +<div class="note"> + +<div class="title"> + +Note + +</div> + +We do not recommend using policy-based vpn and route-based vpn configurations to the same peer. + +</div> + +**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> +<img src="/_static/images/IPSec_close_action_settings.webp" /> +</figure> + +Similar combinations are applicable for the dead-peer-detection. + +### Detailed Configuration Commands + +#### PSK Key Authentication + +<div class="cfgcmd"> + +set vpn ipsec authentication psk \<name\> dhcp-interface + +ID for authentication generated from DHCP address +dynamically. + +</div> + +<div class="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`. + +</div> + +<div class="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 +<span class="title-ref">secret-type base64</span> is configured. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec authentication psk secret-type \<type\> + +Specifies the secret type: + +- **plaintext** - Plain text type (default value). +- **base64** - Base64 type. + +</div> + +#### Peer Configuration + +##### Peer Authentication Commands + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> authentication rsa local-key \<key\> + +Name of PKI key-pair with local private key. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> authentication rsa remote-key \<key\> + +Name of PKI key-pair with remote public key. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> authentication rsa passphrase \<passphrase\> + +Local private key passphrase. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec authentication x509 passphrase \<passphrase\> + +Private key passphrase, if needed. + +</div> + +##### Global Peer Configuration Commands + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> description \<description\> + +Description for this peer. + +</div> + +<div class="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`. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> ike-group \<name\> + +Name of IKE group to use for key exchanges. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +##### CHILD SAs Configuration Commands + +###### Policy-Based CHILD SAs Configuration Commands + +Every configured tunnel under peer configuration is a new CHILD SA. + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> tunnel \<number\> disable + +Disable this tunnel. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> tunnel \<number\> esp-group \<name\> + +Specify ESP group for this CHILD SA. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> tunnel \<number\> priority \<number\> + +Priority for policy-based IPsec VPN tunnels (lowest value more +preferable). + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> tunnel \<number\> local prefix \<network\> + +IP network at the local side. + +</div> + +<div class="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`. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> tunnel \<number\> remote prefix \<network\> + +IP network at the remote side. + +</div> + +<div class="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`. + +</div> + +###### 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. + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +When using site-to-site IPsec with VTI interfaces, +be sure to disable route autoinstall. + +</div> + +``` none +set vpn ipsec options disable-route-autoinstall +``` + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> vti bind \<interface\> + +VTI interface to bind to this peer. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> vti esp-group \<name\> + +ESP group for encrypt traffic, passed this VTI interface. + +</div> + +Traffic-selectors parameters for traffic that should pass via vti +interface. + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> vti traffic-selector local prefix \<network\> + +Local prefix for interesting traffic. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> vti traffic-selector remote prefix \<network\> + +Remote prefix for interesting traffic. + +</div> + +### IPsec Op-mode Commands + +<div class="opcmd"> + +show vpn ike sa + +Shows active IKE SAs information. + +</div> + +<div class="opcmd"> + +show vpn ike secrets + +Shows configured authentication keys. + +</div> + +<div class="opcmd"> + +show vpn ike status + +Shows Strongswan daemon status. + +</div> + +<div class="opcmd"> + +show vpn ipsec connections + +Shows summary status of all configured IKE and IPsec SAs. + +</div> + +<div class="opcmd"> + +show vpn ipsec sa \[detail\] + +Shows active IPsec SAs information. + +</div> + +<div class="opcmd"> + +show vpn ipsec status + +Shows status of IPsec process. + +</div> + +<div class="opcmd"> + +show vpn ipsec policy + +Shows the in-kernel crypto policies. + +</div> + +<div class="opcmd"> + +show vpn ipsec state + +Shows the in-kernel crypto state. + +</div> + +<div class="opcmd"> + +show log ipsec + +Shows IPsec logs. + +</div> + +<div class="opcmd"> + +reset vpn ipsec site-to-site all + +Clear all ipsec connection and reinitiate them if VyOS is configured +as initiator. + +</div> + +<div class="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. + +</div> + +<div class="opcmd"> + +reset vpn ipsec site-to-site peer \<name\> tunnel \<number\> + +Clear scpecific IPsec SA and reinitiate it if VyOS is configured as +initiator. + +</div> + +<div class="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. + +</div> + +<div class="opcmd"> + +restart ipsec + +Restart Strongswan daemon. + +</div> + +## Examples: + +### Policy-Based VPN Example + +**PEER1:** + +- WAN interface on <span class="title-ref">eth0</span> +- <span class="title-ref">eth0</span> interface IP: <span class="title-ref">10.0.1.2/30</span> +- <span class="title-ref">dum0</span> interface IP: <span class="title-ref">192.168.0.1/24</span> (for testing purposes) +- Initiator + +**PEER2:** + +- WAN interface on <span class="title-ref">eth0</span> +- <span class="title-ref">eth0</span> interface IP: <span class="title-ref">10.0.2.2/30</span> +- <span class="title-ref">dum0</span> interface IP: <span class="title-ref">192.168.1.0/24</span> (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 <span class="title-ref">eth0</span> +- <span class="title-ref">eth0</span> interface IP: <span class="title-ref">10.0.1.2/30</span> +- 'vti0' interface IP: <span class="title-ref">10.100.100.1/30</span> +- <span class="title-ref">dum0</span> interface IP: <span class="title-ref">192.168.0.1/24</span> (for testing purposes) +- Role: Initiator + +**PEER2:** + +- WAN interface on <span class="title-ref">eth0</span> +- <span class="title-ref">eth0</span> interface IP: <span class="title-ref">10.0.2.2/30</span> +- 'vti0' interface IP: <span class="title-ref">10.100.100.2/30</span> +- <span class="title-ref">dum0</span> interface IP: <span class="title-ref">192.168.1.0/24</span> (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..14161e7f --- /dev/null +++ b/docs/configuration/vpn/ipsec/md-troubleshooting_ipsec.md @@ -0,0 +1,303 @@ +# 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..c335d306 --- /dev/null +++ b/docs/configuration/vpn/md-dmvpn.md @@ -0,0 +1,406 @@ +# DMVPN + +`DMVPN (Dynamic Multipoint Virtual Private Network)` is a dynamic +`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: + +- `NHRP (Next Hop Resolution Protocol)` `2332` +- `mGRE (Multipoint Generic Routing Encapsulation)` `1702` +- `IPSec (IP Security)` - too many RFCs to list, but start with + `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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +<figure> +<img src="/_static/images/vpn_dmvpn_topology01.webp" alt="Baseline DMVPN topology" /> +<figcaption aria-hidden="true">Baseline DMVPN topology</figcaption> +</figure> + +## Configuration + +- Please refer to the `tunnel-interface` documentation for the individual + tunnel related options. +- Please refer to the `ipsec_general` documentation for individual IPSec + related options. + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols nhrp tunnel \<tunnel\> dynamic-map \<address\> +nbma-domain-name \<fqdn\> + +Specifies that the `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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set protocols nhrp tunnel \<tunnel\> map nbma-address \<address\> + +Creates static peer mapping of protocol-address to `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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +It is very easy to misconfigure multicast repeating if you have +multiple NHSes. + +</div> + +</div> + +<div class="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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Currently does not do much as caching is not implemented. + +</div> + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +## Example + +This blueprint uses VyOS as the DMVPN Hub and Cisco (7206VXR) and VyOS as +multiple spoke sites. The lab was built using `EVE-NG (Emulated Virtual +Environment NG)`. + +<figure> +<img src="/_static/images/blueprint-dmvpn.webp" alt="DMVPN network" /> +<figcaption>DMVPN example network</figcaption> +</figure> + +Each node (Hub and Spoke) uses an IP address from the network 172.16.253.128/29. + +The below referenced IP address <span class="title-ref">192.0.2.1</span> is used as example address +representing a global unicast address under which the HUB can be contacted by +each and every individual spoke. + +### 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' +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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). + +</div> + +#### 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..b9aa768e --- /dev/null +++ b/docs/configuration/vpn/md-index.md @@ -0,0 +1,20 @@ +# VPN + +<div class="toctree" maxdepth="1" includehidden=""> + +ipsec/index +l2tp +openconnect +pptp +rsa-keys +sstp + +</div> + +pages to sort + +<div class="toctree" maxdepth="1" includehidden=""> + +dmvpn + +</div> diff --git a/docs/configuration/vpn/md-l2tp.md b/docs/configuration/vpn/md-l2tp.md new file mode 100644 index 00000000..1b71c71f --- /dev/null +++ b/docs/configuration/vpn/md-l2tp.md @@ -0,0 +1,837 @@ +# L2TP + +VyOS utilizes [accel-ppp](https://accel-ppp.org/) 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 +``` + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication local-users username \<user\> password +\<pass\> + +Create <span class="title-ref">\<user\></span> for local authentication on this system. The users password +will be set to <span class="title-ref">\<pass\></span>. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access default-pool \<POOL-NAME\> + +Use this command to define default address pool name. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access gateway-address \<gateway\> + +Specifies single <span class="title-ref">\<gateway\></span> IP address to be used as local address of PPP +interfaces. + +</div> + +## 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 +``` + +<div class="cfgcmd"> + +set vpn ipsec interface \<INTERFACE\> + +Use this command to define IPsec interface. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access ipsec-settings authentication mode \<pre-shared-secret | x509\> + +Set mode for IPsec authentication between VyOS and L2TP clients. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access ipsec-settings authentication pre-shared-secret \<secret\> + +Set predefined shared secret phrase. + +</div> + +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 +``` + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius server \<server\> key \<secret\> + +Configure RADIUS <span class="title-ref">\<server\></span> and its required shared <span class="title-ref">\<secret\></span> for +communicating with the RADIUS server. + +</div> + +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' +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Some [RADIUS](https://en.wikipedia.org/wiki/RADIUS) severs use an access control list which allows or denies +queries, make sure to add your VyOS router to the allowed client list. + +</div> + +### 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. + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queires. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The `source-address` must be configured to that of an interface. +Best practice would be a loopback or dummy interface. + +</div> + +### RADIUS advanced options + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius server \<server\> port \<port\> + +Configure RADIUS <span class="title-ref">\<server\></span> and its required port for authentication requests. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius server \<server\> fail-time \<time\> + +Mark RADIUS server as offline for this given <span class="title-ref">\<time\></span> in seconds. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius server \<server\> disable + +Temporary disable this RADIUS server. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius acct-timeout \<timeout\> + +Timeout to wait reply for Interim-Update packets. (default 3 seconds) + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius dynamic-author server \<address\> + +Specifies IP address for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius dynamic-author port \<port\> + +Port for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius dynamic-author key \<secret\> + +Secret for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius max-try \<number\> + +Maximum number of tries to send Access-Request/Accounting-Request queries + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius timeout \<timeout\> + +Timeout to wait response from server (seconds) + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queires. + +</div> + +<div class="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 <span class="title-ref">Filter-Id</span>. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you set a custom RADIUS attribute you must define it on both +dictionaries on the RADIUS server and client. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius rate-limit enable + +Enables bandwidth shaping via RADIUS. + +</div> + +<div class="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. + +</div> + +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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +`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](https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911). + +</div> + +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](https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel). 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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The value of the attribute `NAS-Port-Id` must be less than 16 +characters, otherwise the interface won't be renamed. + +</div> + +## Configuring LNS (L2TP Network Server) + +LNS are often used to connect to a LAC (L2TP Access Concentrator). + +<div class="cfgcmd"> + +set vpn l2tp remote-access lns host-name \<hostname\> + +Sent to the client (LAC) in the Host-Name attribute + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access lns shared-secret \<secret\> + +Tunnel password used to authenticate the client (LAC) + +</div> + +To explain the usage of LNS follow our blueprint `examples-lac-lns`. + +## IPv6 + +<div class="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) + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access default-ipv6-pool \<IPv6-POOL-NAME\> + +Use this command to define default IPv6 address pool name. + +</div> + +``` 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 + +<div class="cfgcmd"> + +set vpn l2tp remote-access ppp-options ipv6-accept-peer-interface-id + +Accept peer interface identifier. By default this is not defined. + +</div> + +<div class="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 + +</div> + +<div class="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. + +</div> + +## Scripting + +<div class="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 + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access extended-scripts on-down \<path_to_script\> + +Script to run when the session interface is about to terminate + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access extended-scripts on-pre-up \<path_to_script\> + +Script to run before the session interface comes up + +</div> + +<div class="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 + +</div> + +## Advanced Options + +### Authentication Advanced Options + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication local-users username \<user\> disable + +Disable <span class="title-ref">\<user\></span> account. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication local-users username \<user\> static-ip +\<address\> + +Assign a static IP address to <span class="title-ref">\<user\></span> account. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication local-users username \<user\> rate-limit +download \<bandwidth\> + +Rate limit the download bandwidth for <span class="title-ref">\<user\></span> to <span class="title-ref">\<bandwidth\></span> kbit/s. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication local-users username \<user\> rate-limit +upload \<bandwidth\> + +Rate limit the upload bandwidth for <span class="title-ref">\<user\></span> to <span class="title-ref">\<bandwidth\></span> kbit/s + +</div> + +<div class="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. + +</div> + +### Client IP Pool Advanced Options + +<div class="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. + +</div> + +### PPP Advanced Options + +<div class="cfgcmd"> + +set vpn l2tp remote-access ppp-options disable-ccp + +Disable Compression Control Protocol (CCP). +CCP is enabled by default. + +</div> + +<div class="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**. + +</div> + +<div class="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 + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access ppp-options lcp-echo-failure \<number\> + +Defines the maximum <span class="title-ref">\<number\></span> of unanswered echo requests. Upon reaching the +value <span class="title-ref">\<number\></span>, the session will be reset. Default value is **3**. + +</div> + +<div class="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 <span class="title-ref">\<interval\></span> seconds. +Default value is **30**. + +</div> + +<div class="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**. + +</div> + +<div class="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**. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access ppp-options mppe \<require | prefer | deny\> + +Specifies `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. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access ppp-options mru \<number\> + +Defines preferred MRU. By default is not defined. + +</div> + +### Global Advanced options + +<div class="cfgcmd"> + +set vpn l2tp remote-access description \<description\> + +Set description. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access limits burst \<value\> + +Burst count + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access limits connection-limit \<value\> + +Maximum accepted connection rate (e.g. 1/min, 60/sec) + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access limits timeout \<value\> + +Timeout in seconds + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access mtu + +Maximum Transmission Unit (MTU) (default: **1436**) + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access max-concurrent-sessions + +Maximum number of concurrent session start attempts + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access name-server \<address\> + +Connected clients should use <span class="title-ref">\<address\></span> 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. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access shaper fwmark \<1-2147483647\> + +Match firewall mark value + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access snmp master-agent + +Enable SNMP + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access wins-server \<address\> + +Windows Internet Name Service (WINS) servers propagated to client + +</div> + +## 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 +``` diff --git a/docs/configuration/vpn/md-openconnect.md b/docs/configuration/vpn/md-openconnect.md new file mode 100644 index 00000000..91310cdd --- /dev/null +++ b/docs/configuration/vpn/md-openconnect.md @@ -0,0 +1,329 @@ +# 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 +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +It is compatible with Cisco (R) AnyConnect (R) clients. + +</div> + +## 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. + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +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 + +</div> + +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 +``` + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +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. + +</div> + +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. + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +OpenConnect server matches the filename in a case sensitive +manner, make sure the username/group name you configure matches the +filename exactly. + +</div> + +### 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 +``` + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +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". + +</div> + +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..2f973da2 --- /dev/null +++ b/docs/configuration/vpn/md-pptp.md @@ -0,0 +1,808 @@ +# PPTP-Server + +The Point-to-Point Tunneling Protocol ([PPTP](#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 +``` + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication local-users username \<user\> password +\<pass\> + +Create <span class="title-ref">\<user\></span> for local authentication on this system. The users password +will be set to <span class="title-ref">\<pass\></span>. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access default-pool \<POOL-NAME\> + +Use this command to define default address pool name. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access gateway-address \<gateway\> + +Specifies single <span class="title-ref">\<gateway\></span> IP address to be used as local address of PPP +interfaces. + +</div> + +## 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 +``` + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius server \<server\> key \<secret\> + +Configure RADIUS <span class="title-ref">\<server\></span> and its required shared <span class="title-ref">\<secret\></span> for +communicating with the RADIUS server. + +</div> + +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' +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +### 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. + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queires. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The `source-address` must be configured on one of VyOS interface. +Best practice would be a loopback or dummy interface. + +</div> + +### RADIUS advanced options + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius server \<server\> port \<port\> + +Configure RADIUS <span class="title-ref">\<server\></span> and its required port for authentication requests. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius server \<server\> fail-time \<time\> + +Mark RADIUS server as offline for this given <span class="title-ref">\<time\></span> in seconds. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius server \<server\> disable + +Temporary disable this RADIUS server. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius acct-timeout \<timeout\> + +Timeout to wait reply for Interim-Update packets. (default 3 seconds) + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius dynamic-author server \<address\> + +Specifies IP address for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius dynamic-author port \<port\> + +Port for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius dynamic-author key \<secret\> + +Secret for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius max-try \<number\> + +Maximum number of tries to send Access-Request/Accounting-Request queries + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius timeout \<timeout\> + +Timeout to wait response from server (seconds) + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queires. + +</div> + +<div class="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 <span class="title-ref">Filter-Id</span>. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you set a custom RADIUS attribute you must define it on both +dictionaries at RADIUS server and client. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius rate-limit enable + +Enables bandwidth shaping via RADIUS. + +</div> + +<div class="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. + +</div> + +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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +`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](https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911). + +</div> + +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](https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel). +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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The value of the attribute `NAS-Port-Id` must be less than 16 +characters, otherwise the interface won't be renamed. + +</div> + +## IPv6 + +<div class="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) + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access default-ipv6-pool \<IPv6-POOL-NAME\> + +Use this command to define default IPv6 address pool name. + +</div> + +``` 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 + +<div class="cfgcmd"> + +set vpn pptp remote-access ppp-options ipv6-accept-peer-interface-id + +Accept peer interface identifier. By default is not defined. + +</div> + +<div class="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 + +</div> + +<div class="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. + +</div> + +## Scripting + +<div class="cfgcmd"> + +set vpn pptp remote-access extended-scripts on-change \<path_to_script\> + +Script to run when session interface changed by RADIUS CoA handling + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access extended-scripts on-down \<path_to_script\> + +Script to run when session interface going to terminate + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access extended-scripts on-pre-up \<path_to_script\> + +Script to run before session interface comes up + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access extended-scripts on-up \<path_to_script\> + +Script to run when session interface is completely configured and started + +</div> + +## Advanced Options + +### Authentication Advanced Options + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication local-users username \<user\> disable + +Disable <span class="title-ref">\<user\></span> account. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication local-users username \<user\> static-ip +\<address\> + +Assign static IP address to <span class="title-ref">\<user\></span> account. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication local-users username \<user\> rate-limit +download \<bandwidth\> + +Download bandwidth limit in kbit/s for <span class="title-ref">\<user\></span>. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication local-users username \<user\> rate-limit +upload \<bandwidth\> + +Upload bandwidth limit in kbit/s for <span class="title-ref">\<user\></span>. + +</div> + +<div class="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. + +</div> + +### Client IP Pool Advanced Options + +<div class="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. + +</div> + +### PPP Advanced Options + +<div class="cfgcmd"> + +set vpn pptp remote-access ppp-options disable-ccp + +Disable Compression Control Protocol (CCP). +CCP is enabled by default. + +</div> + +<div class="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**. + +</div> + +<div class="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 + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access ppp-options lcp-echo-failure \<number\> + +Defines the maximum <span class="title-ref">\<number\></span> of unanswered echo requests. Upon reaching the +value <span class="title-ref">\<number\></span>, the session will be reset. Default value is **3**. + +</div> + +<div class="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 <span class="title-ref">\<interval\></span> seconds. +Default value is **30**. + +</div> + +<div class="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**. + +</div> + +<div class="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**. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access ppp-options mppe \<require | prefer | deny\> + +Specifies `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. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access ppp-options mru \<number\> + +Defines preferred MRU. By default is not defined. + +</div> + +### Global Advanced options + +<div class="cfgcmd"> + +set vpn pptp remote-access description \<description\> + +Set description. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access limits burst \<value\> + +Burst count + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access limits connection-limit \<value\> + +Acceptable rate of connections (e.g. 1/min, 60/sec) + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access limits timeout \<value\> + +Timeout in seconds + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access mtu + +Maximum Transmission Unit (MTU) (default: **1436**) + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access max-concurrent-sessions + +Maximum number of concurrent session start attempts + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access name-server \<address\> + +Connected client should use <span class="title-ref">\<address\></span> 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. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access shaper fwmark \<1-2147483647\> + +Match firewall mark value + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access snmp master-agent + +Enable SNMP + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access wins-server \<address\> + +Windows Internet Name Service (WINS) servers propagated to client + +</div> + +## Monitoring + +<div class="opcmd"> + +show pptp-server sessions + +Use this command to locally check the active sessions in the PPTP +server. + +</div> + +``` 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 +``` diff --git a/docs/configuration/vpn/md-rsa-keys.md b/docs/configuration/vpn/md-rsa-keys.md new file mode 100644 index 00000000..7d54126f --- /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 name\>". 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..8ac7d665 --- /dev/null +++ b/docs/configuration/vpn/md-sstp.md @@ -0,0 +1,919 @@ +# SSTP Server + +`SSTP (Secure Socket Tunneling Protocol)` is a form of `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 - `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' +``` + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication local-users username \<user\> password +\<pass\> + +Create <span class="title-ref">\<user\></span> for local authentication on this system. The users password +will be set to <span class="title-ref">\<pass\></span>. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set vpn sstp default-pool \<POOL-NAME\> + +Use this command to define default address pool name. + +</div> + +<div class="cfgcmd"> + +set vpn sstp gateway-address \<gateway\> + +Specifies single <span class="title-ref">\<gateway\></span> IP address to be used as local address of PPP +interfaces. + +</div> + +<div class="cfgcmd"> + +set vpn sstp ssl ca-certificate \<file\> + +Name of installed certificate authority certificate. + +</div> + +<div class="cfgcmd"> + +set vpn sstp ssl certificate \<file\> + +Name of installed server certificate. + +</div> + +## 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 +``` + +<div class="cfgcmd"> + +set vpn sstp authentication radius server \<server\> key \<secret\> + +Configure RADIUS <span class="title-ref">\<server\></span> and its required shared <span class="title-ref">\<secret\></span> for +communicating with the RADIUS server. + +</div> + +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' +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +### 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. + +<div class="cfgcmd"> + +set vpn sstp authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queires. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The `source-address` must be configured to that of an interface. +Best practice would be a loopback or dummy interface. + +</div> + +### RADIUS advanced options + +<div class="cfgcmd"> + +set vpn sstp authentication radius server \<server\> port \<port\> + +Configure RADIUS <span class="title-ref">\<server\></span> and its required port for authentication requests. + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication radius server \<server\> fail-time \<time\> + +Mark RADIUS server as offline for this given <span class="title-ref">\<time\></span> in seconds. + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication radius server \<server\> disable + +Temporary disable this RADIUS server. + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication radius acct-timeout \<timeout\> + +Timeout to wait reply for Interim-Update packets. (default 3 seconds) + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication radius dynamic-author server \<address\> + +Specifies IP address for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication radius dynamic-author port \<port\> + +Port for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication radius dynamic-author key \<secret\> + +Secret for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication radius max-try \<number\> + +Maximum number of tries to send Access-Request/Accounting-Request queries + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication radius timeout \<timeout\> + +Timeout to wait response from server (seconds) + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queires. + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication radius rate-limit attribute \<attribute\> + +Specifies which RADIUS server attribute contains the rate limit information. +The default attribute is <span class="title-ref">Filter-Id</span>. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you set a custom RADIUS attribute you must define it on both +dictionaries on the RADIUS server and client. + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication radius rate-limit enable + +Enables bandwidth shaping via RADIUS. + +</div> + +<div class="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. + +</div> + +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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +`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](https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911). + +</div> + +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](https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel). 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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The value of the attribute `NAS-Port-Id` must be less than 16 +characters, otherwise the interface won't be renamed. + +</div> + +## IPv6 + +<div class="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) + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set vpn sstp default-ipv6-pool \<IPv6-POOL-NAME\> + +Use this command to define default IPv6 address pool name. + +</div> + +``` 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 + +<div class="cfgcmd"> + +set vpn sstp ppp-options ipv6-accept-peer-interface-id + +Accept peer interface identifier. By default this is not defined. + +</div> + +<div class="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 + +</div> + +<div class="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. + +</div> + +## Scripting + +<div class="cfgcmd"> + +set vpn sstp extended-scripts on-change \<path_to_script\> + +Script to run when the session interface is changed by RADIUS CoA handling + +</div> + +<div class="cfgcmd"> + +set vpn sstp extended-scripts on-down \<path_to_script\> + +Script to run when the session interface about to terminate + +</div> + +<div class="cfgcmd"> + +set vpn sstp extended-scripts on-pre-up \<path_to_script\> + +Script to run before the session interface comes up + +</div> + +<div class="cfgcmd"> + +set vpn sstp extended-scripts on-up \<path_to_script\> + +Script to run when the session interface is completely configured and started + +</div> + +## Advanced Options + +### Authentication Advanced Options + +<div class="cfgcmd"> + +set vpn sstp authentication local-users username \<user\> disable + +Disable <span class="title-ref">\<user\></span> account. + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication local-users username \<user\> static-ip +\<address\> + +Assign a static IP address to <span class="title-ref">\<user\></span> account. + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication local-users username \<user\> rate-limit +download \<bandwidth\> + +Rate limit the download bandwidth for <span class="title-ref">\<user\></span> to <span class="title-ref">\<bandwidth\></span> kbit/s. + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication local-users username \<user\> rate-limit +upload \<bandwidth\> + +Rate limit the upload bandwidth for <span class="title-ref">\<user\></span> to <span class="title-ref">\<bandwidth\></span> kbit/s. + +</div> + +<div class="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. + +</div> + +### Client IP Pool Advanced Options + +<div class="cfgcmd"> + +set vpn sstp client-ip-pool \<POOL-NAME\> next-pool \<NEXT-POOL-NAME\> + +Use this command to define the next address pool name. + +</div> + +### PPP Advanced Options + +<div class="cfgcmd"> + +set vpn sstp ppp-options disable-ccp + +Disable Compression Control Protocol (CCP). +CCP is enabled by default. + +</div> + +<div class="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**. + +</div> + +<div class="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 + +</div> + +<div class="cfgcmd"> + +set vpn sstp ppp-options lcp-echo-failure \<number\> + +Defines the maximum <span class="title-ref">\<number\></span> of unanswered echo requests. Upon reaching the +value <span class="title-ref">\<number\></span>, the session will be reset. Default value is **3**. + +</div> + +<div class="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 <span class="title-ref">\<interval\></span> seconds. +Default value is **30**. + +</div> + +<div class="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**. + +</div> + +<div class="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**. + +</div> + +<div class="cfgcmd"> + +set vpn sstp ppp-options mppe \<require | prefer | deny\> + +Specifies `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. + +</div> + +<div class="cfgcmd"> + +set vpn sstp ppp-options mru \<number\> + +Defines preferred MRU. By default is not defined. + +</div> + +### Global Advanced options + +<div class="cfgcmd"> + +set vpn sstp description \<description\> + +Set description. + +</div> + +<div class="cfgcmd"> + +set vpn sstp limits burst \<value\> + +Burst count + +</div> + +<div class="cfgcmd"> + +set vpn sstp limits connection-limit \<value\> + +Maximum accepted connection rate (e.g. 1/min, 60/sec) + +</div> + +<div class="cfgcmd"> + +set vpn sstp limits timeout \<value\> + +Timeout in seconds + +</div> + +<div class="cfgcmd"> + +set vpn sstp mtu + +Maximum Transmission Unit (MTU) (default: **1500**) + +</div> + +<div class="cfgcmd"> + +set vpn sstp max-concurrent-sessions + +Maximum number of concurrent session start attempts + +</div> + +<div class="cfgcmd"> + +set vpn sstp name-server \<address\> + +Connected clients should use <span class="title-ref">\<address\></span> 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. + +</div> + +<div class="cfgcmd"> + +set vpn sstp shaper fwmark \<1-2147483647\> + +Match firewall mark value + +</div> + +<div class="cfgcmd"> + +set vpn sstp snmp master-agent + +Enable SNMP + +</div> + +<div class="cfgcmd"> + +set vpn sstp wins-server \<address\> + +Windows Internet Name Service (WINS) servers propagated to client + +</div> + +<div class="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. + +</div> + +## 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](https://github.com/reliablehosting/sstp-client). [sstpc](https://github.com/reliablehosting/sstp-client) 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 + +<div class="opcmd"> + +show sstp-server sessions + +Use this command to locally check the active sessions in the SSTP +server. + +</div> + +``` 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 +``` diff --git a/docs/configuration/vrf/md-index.md b/docs/configuration/vrf/md-index.md new file mode 100644 index 00000000..7ab24fc2 --- /dev/null +++ b/docs/configuration/vrf/md-index.md @@ -0,0 +1,694 @@ +lastproofread +2021-07-07 + +# VRF + +`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. + +<div class="cfgcmd"> + +set vrf name \<name\> table \<id\> + +Create a new VRF instance with <span class="title-ref">\<name\></span> and <span class="title-ref">\<id\></span>. The name is used when placing +individual interfaces into the VRF. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +</div> + +<div class="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. + +</div> + +### 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. + +<div class="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 + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you choose any as the option that will cause all protocols that +are sending routes to zebra. + +</div> + +</div> + +<div class="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 + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you choose any as the option that will cause all protocols that +are sending routes to zebra. + +</div> + +</div> + +### 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. + +<div class="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. + +</div> + +<div class="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. + +</div> + +### 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. + +<div class="cfgcmd"> + +set interfaces \<dummy | ethernet | bonding | bridge | pppoe\> +\<interface\> vrf \<name\> + +Assign interface identified by <span class="title-ref">\<interface\></span> to VRF named <span class="title-ref">\<name\></span>. + +</div> + +### Routing + +<div class="note"> + +<div class="title"> + +Note + +</div> + +VyOS 1.4 (sagitta) introduced dynamic routing support for VRFs. + +</div> + +Currently dynamic routing is supported for the following protocols: + +- `routing-bgp` +- `routing-isis` +- `routing-ospf` +- `routing-ospfv3` +- `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 <span class="title-ref">vrf +name \<name\></span> command. + +#### Example + +The following commands would be required to set options for a given dynamic +routing protocol inside a given vrf: + +- `routing-bgp`: `set vrf name <name> protocols bgp ...` +- `routing-isis`: `set vrf name <name> protocols isis ...` +- `routing-ospf`: `set vrf name <name> protocols ospf ...` +- `routing-ospfv3`: `set vrf name <name> protocols ospfv3 ...` +- `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. + +<div class="opcmd"> + +show vrf + +Lists VRFs that have been created + +``` 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 +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Command should probably be extended to list also the real +interfaces assigned to this one VRF to get a better overview. + +</div> + +</div> + +<div class="opcmd"> + +show vrf \<name\> + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show ip route vrf \<name\> + +Display IPv4 routing table for VRF identified by <span class="title-ref">\<name\></span>. + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show ipv6 route vrf \<name\> + +Display IPv6 routing table for VRF identified by <span class="title-ref">\<name\></span>. + +``` 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 +``` + +</div> + +<div class="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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Ping command can be interrupted at any given time using `<Ctrl>+c`. +A brief statistic is shown afterwards. + +</div> + +``` 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 +``` + +</div> + +<div class="opcmd"> + +traceroute vrf \<name\> \[ipv4 | ipv6\] \<host\> + +Displays the route packets taken to a network host utilizing VRF instance +identified by <span class="title-ref">\<name\></span>. 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. + +</div> + +<div class="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. + +``` none +vyos@vyos:~$ force vrf blue +vyos@vyos(vrf:blue):~$ +``` + +</div> + +## Example + +### VRF route leaking + +The following example topology was built using EVE-NG. + +<figure> +<img src="/_static/images/vrf-example-topology-01.webp" alt="VRF topology example" /> +<figcaption>VRF route leaking</figcaption> +</figure> + +- 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` + +#### 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 + +#### 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' +> ``` + +#### 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 + +`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. + +## 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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +## 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. + +<div class="cfgcmd"> + +set vrf name \<name\> protocols bgp address-family +\<ipv4-unicast[|ipv6-unicast\> rd vpn export \<asn:nn|](##SUBST##|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. + +</div> + +<div class="cfgcmd"> + +set vrf name \<name\> protocols bgp address-family +\<ipv4-unicast[|ipv6-unicast\> route-target vpn \<import|](##SUBST##|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. + +</div> + +<div class="cfgcmd"> + +set vrf name \<name\> protocols bgp address-family +\<ipv4-unicast[|ipv6-unicast\> label vpn export \<0-1048575|](##SUBST##|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. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set vrf name \<name\> protocols bgp address-family +\<ipv4-unicast[|ipv6-unicast\> route-map vpn \<import|](##SUBST##|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. + +</div> + +<div class="cfgcmd"> + +set vrf name \<name\> protocols bgp address-family +\<ipv4-unicast[|ipv6-unicast\> \<import|](##SUBST##|ipv6-unicast> <import|)export\> vpn + +Enables import or export of routes between the current unicast VRF and VPN. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +<div class="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. + +</div> + +## 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. + +<div class="opcmd"> + +show bgp \<ipv4|ipv6\> vpn + +Print active IPV4 or IPV6 routes advertised via the VPN SAFI. + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show bgp \<ipv4|ipv6\> vpn summary + +Print a summary of neighbor connections for the specified AFI/SAFI +combination. + +``` 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 + +</div> diff --git a/docs/contributing/md-build-vyos.md b/docs/contributing/md-build-vyos.md new file mode 100644 index 00000000..c8074bd7 --- /dev/null +++ b/docs/contributing/md-build-vyos.md @@ -0,0 +1,876 @@ +# Build VyOS + +## Prerequisites + +There are different ways you can build VyOS. + +Building using a `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 `build_native`. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +### 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](https://github.com/vyos/vyos-build). The `./build-vyos-image` script will also warn you if any +dependencies are missing. + +### Docker + +This will guide you through the process of building a VyOS ISO using [Docker](https://www.docker.com). +This process has been tested on clean installs of Debian Bullseye (11) and +Bookworm (12). + +Installing [Docker](https://www.docker.com) and prerequisites: + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +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. + +</div> + +[On Debian](https://docs.docker.com/engine/install/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](https://www.docker.com) without `sudo`, the current non-root user must be +added to the `docker` group by calling: `sudo usermod -aG docker yourusername`. + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +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](https://docs.docker.com/engine/install/linux-postinstall). + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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" + +</div> + +#### 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](https://hub.docker.com/u/vyos) 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). + +##### 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 +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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`. + +</div> + +#### Tips and Tricks + +You can create yourself some handy Bash aliases to always launch the latest - +per release train (<span class="title-ref">current</span> or <span class="title-ref">sagitta</span>) - 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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +## 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 <span class="title-ref">current</span> and <span class="title-ref">crux</span>. + +``` 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! + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +Building VyOS on Windows WSL2 with Docker integrated into WSL2 will +work like a charm. No problems are known so far! + +</div> + +### Customize<span id="build source"></span> + +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 + +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 <span class="title-ref">chroot</span> 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! + +### 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 <span class="title-ref">\*.deb</span> packages in the <span class="title-ref">packages</span> 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 +<span class="title-ref">vyos-build/packages/linux-kernel/patches</span> folder, copying our kernel +configuration `x86_64_vyos_defconfig` to the right location, and finally +building the Debian packages. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +``` 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 <span class="title-ref">\*.deb</span> 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 <span class="title-ref">\*.deb</span> +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 <span class="title-ref">\*.deb</span> +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 <span class="title-ref">\*.deb</span> +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 +<span class="title-ref">\*.deb</span> package inside the <span class="title-ref">packages</span> folder within <span class="title-ref">vyos-build</span>. 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 +``` + +## 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](https://github.com/vyos) in their source format can easily be compiled into +a custom Debian (<span class="title-ref">\*.deb</span>) package. + +The easiest way to compile your package is with the above mentioned +`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 <span class="title-ref">\*.deb</span> 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 <span class="title-ref">\*.deb</span> into your ISO build environment to +include it in a custom iso, see `build_custom_packages` for more +information. + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +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. + +</div> diff --git a/docs/contributing/md-debugging.md b/docs/contributing/md-debugging.md new file mode 100644 index 00000000..b7e66470 --- /dev/null +++ b/docs/contributing/md-debugging.md @@ -0,0 +1,189 @@ +# 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 `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](https://github.com/vyos/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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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`. + +</div> + +### 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](https://github.com/vyos/vyos-build/blob/current/data/live-build-config/includes.chroot/etc/systemd/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. diff --git a/docs/contributing/md-development.md b/docs/contributing/md-development.md new file mode 100644 index 00000000..cc9fae00 --- /dev/null +++ b/docs/contributing/md-development.md @@ -0,0 +1,708 @@ +# 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 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 <span class="title-ref">git bisect</span> + - 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 <span class="title-ref">git add --patch</span> 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 <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 + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +#### 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](https://jinja.palletsprojects.com/). + +### 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](https://github.com/vyos/vyos-1x/tree/current/schema) 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](https://blog.vyos.io/vyos-development-digest-10) 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](https://github.com/vyos/vyos-1x/tree/current/schema) module. This schema is a slightly modified schema from [VyConf](https://github.com/vyos/vyconf/tree/master/data/schemata) +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 +<span class="title-ref">scripts/build-command-templates</span> 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 <span class="title-ref">xml.in</span> file extension which was +implemented in `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)](https://github.com/vyos/vyos-1x/blob/current/interface-definitions/include/interface/address-ipv4-ipv6-dhcp.xml.i) address assignment +- [IPv4, IPv6](https://github.com/vyos/vyos-1x/blob/current/interface-definitions/include/interface/address-ipv4-ipv6.xml.i) address assignment +- [VLAN (VIF)](https://github.com/vyos/vyos-1x/blob/current/interface-definitions/include/interface/vif.xml.i) definition +- [MAC address](https://github.com/vyos/vyos-1x/blob/current/interface-definitions/include/interface/mac.xml.i) assignment + +All interface definition XML input files (.in suffix) will be sent to the GCC +preprocess and the output is stored in the <span class="title-ref">build/interface-definitions</span> +folder. The previously mentioned <span class="title-ref">scripts/build-command-templates</span> script +operates on the <span class="title-ref">build/interface-definitions</span> 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 + +<table> +<colgroup> +<col style="width: 25%" /> +<col style="width: 25%" /> +<col style="width: 50%" /> +</colgroup> +<thead> +<tr> +<th>Old concept/syntax</th> +<th>New syntax</th> +<th>Notes</th> +</tr> +</thead> +<tbody> +<tr> +<td>mynode/node.def</td> +<td><node name="mynode"> </node></td> +<td>Leaf nodes (nodes with values) use <leafNode> tag instead</td> +</tr> +<tr> +<td>mynode/node.tag , tag:</td> +<td><tagNode name="mynode> </node></td> +<td></td> +</tr> +<tr> +<td>help: My node</td> +<td><properties> <help>My node</help></td> +<td></td> +</tr> +<tr> +<td>val_help: <format>; some string</td> +<td><properties> <valueHelp> <format> format </format> <description> some +string </description></td> +<td>Do not add angle brackets around the format, they will be inserted +automatically</td> +</tr> +<tr> +<td>syntax:expression: pattern</td> +<td><properties> <constraint> <regex> ...</td> +<td><constraintErrorMessage> will be displayed on failure</td> +</tr> +<tr> +<td>syntax:expression: $VAR(@) in "foo", "bar", "baz"</td> +<td>None</td> +<td>Use regex</td> +</tr> +<tr> +<td>syntax:expression: exec ...</td> +<td><properties> <constraint> <validator> <name ="foo" argument="bar"></td> +<td>"${vyos_libexecdir}/validators/foo bar $VAR(@)" will be executed, +<constraintErrorMessage> will be displayed on failure</td> +</tr> +<tr> +<td>syntax:expression: (arithmetic expression)</td> +<td>None</td> +<td>External arithmetic validator may be added if there's demand, complex +validation is better left to commit-time scripts</td> +</tr> +<tr> +<td>priority: 999</td> +<td><properties> <priority>999</priority></td> +<td>Please leave a comment explaining why the priority was chosen +(e.g. "after interfaces are configured")</td> +</tr> +<tr> +<td>multi:</td> +<td><properties> <multi/></td> +<td>Only applicable to leaf nodes</td> +</tr> +<tr> +<td>allowed: echo foo bar</td> +<td><properties> <completionHelp> <list> foo bar </list></td> +<td></td> +</tr> +<tr> +<td>allowed: cli-shell-api listNodes vpn ipsec esp-group</td> +<td><properties> <completionHelp> <path> vpn ipsec esp-group </path> ...</td> +<td></td> +</tr> +<tr> +<td>allowed: /path/to/script</td> +<td><properties> <completionHelp> <script> /path/to/script </script> ...</td> +<td></td> +</tr> +<tr> +<td>default:</td> +<td>None</td> +<td>Move default values to scripts</td> +</tr> +<tr> +<td>commit:expression:</td> +<td>None</td> +<td>All commit time checks should be in the verify() function of the script</td> +</tr> +<tr> +<td>begin:/create:/delete:</td> +<td>None</td> +<td>All logic should be in the scripts</td> +</tr> +</tbody> +</table> + +## 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](https://jenkins.io/) 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 `build_iso` section - +but instead of building it from source on every run, we rather always fetch a +fresh copy (if needed) from [Dockerhub](https://hub.docker.com/u/vyos/). + +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/>. diff --git a/docs/contributing/md-issues-features.md b/docs/contributing/md-issues-features.md new file mode 100644 index 00000000..c481fec5 --- /dev/null +++ b/docs/contributing/md-issues-features.md @@ -0,0 +1,60 @@ +# Issues/Feature requests + +## 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](https://docs.vyos.io) to ensure that you have configured your system + correctly +- Get community support via [Slack](https://slack.vyos.io) or our [Forum](https://forum.vyos.io) + +### 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 + +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. diff --git a/docs/contributing/md-testing.md b/docs/contributing/md-testing.md new file mode 100644 index 00000000..4f406e05 --- /dev/null +++ b/docs/contributing/md-testing.md @@ -0,0 +1,225 @@ +# 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 <span class="title-ref">vyos-1x-smoketest</span> 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: <span class="title-ref">/usr/bin/vyos-smoketest</span> + +The script only searches for executable "test-cases" under +`/usr/libexec/vyos/tests/smoke/cli/` and executes them one by one. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +As Smoketests will alter the system configuration and you are logged +in remote you may loose your connection to the system. + +</div> + +### 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) +- ... + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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 `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. + +</div> + +``` 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 <span class="title-ref">bond</span> interface test to only make use of <span class="title-ref">eth1</span> and <span class="title-ref">eth2</span> +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# +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> diff --git a/docs/contributing/md-upstream-packages.md b/docs/contributing/md-upstream-packages.md new file mode 100644 index 00000000..bc0eeed1 --- /dev/null +++ b/docs/contributing/md-upstream-packages.md @@ -0,0 +1,77 @@ +# 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. <span class="title-ref">cd vyos-strongswan</span> +2. <span class="title-ref">./configure --enable-python-eggs</span> +3. <span class="title-ref">cd src/libcharon/plugins/vici/python</span> +4. <span class="title-ref">make</span> +5. <span class="title-ref">python3 setup.py --command-packages=stdeb.command bdist_deb</span> + +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..8cdfda44 --- /dev/null +++ b/docs/installation/cloud/md-aws-ha.md @@ -0,0 +1,132 @@ +\########## +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> +<img src="/_static/images/cloud-aws-ha-architecture.webp" alt="VyOS HA topology diagram" /> +</figure> + +# 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 <span class="title-ref">main.tf</span>, <span class="title-ref">network.tf</span>, <span class="title-ref">transit_gateway.tf</span>, <span class="title-ref">variables.tf</span>, and <span class="title-ref">outputs.tf</span> 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 <span class="title-ref">vyos_ami_id</span> variable directly in <span class="title-ref">variables.tf</span>. + +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 <span class="title-ref">variables.tf</span>, including instance type, region, and <span class="title-ref">vyos_ami_id</span>. + +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..87effb97 --- /dev/null +++ b/docs/installation/cloud/md-aws-to-azure.md @@ -0,0 +1,177 @@ +\########## +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> +<img src="/_static/images/cloud-aws-to-azure.webp" alt="VyOS Cloud-to-Cloud topology diagram" /> +</figure> + +# 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-aws.md b/docs/installation/cloud/md-aws.md new file mode 100644 index 00000000..523fd280 --- /dev/null +++ b/docs/installation/cloud/md-aws.md @@ -0,0 +1,722 @@ +\########## +VyOS Deployment on AWS +\########## + +This manual provides detailed step-by-step instructions for deploying a VyOS instance and required resources (VPC, ENIs, Subnets, Security Groups) on AWS. + +Prerequisites +======== + +1\. AWS Account +----------- +Ensure you have an AWS account with administrative access. + +2\. IAM Permissions +----------- + +To deploy VyOS and related resources, the user must have the following permissions: + +- `ec2:` for managing EC2, ENIs, and EIPs. +- `vpc:` for creating VPCs, subnets, and route tables. +- `iam:` for attaching roles. + +3\. SSH Key Pair +----------- + +You can use Amazon EC2 to create your key pairs, or you can use a third-party tool to create your key pairs and then import them to Amazon EC2. +Amazon EC2 supports: + +- `2048-bit SSH-2 RSA keys` for Linux and Windows instances. +- `ED25519 keys` for Linux instances (not supported for Windows). + +When you create a key pair using Amazon EC2: + +- The `public key` is stored in Amazon EC2. +- You store the `private key` securely on your local machine. + +Steps to Create a Key Pair Using Amazon EC2 +^^^^^^^^^^^^^^ + +- Open the Amazon EC2 console <https://console.aws.amazon.com/ec2/>. +- In the navigation pane, under `Network & Security`, choose `Key Pairs`. + +<figure> +<img src="/_static/images/cloud-aws-keypair-01.webp" /> +</figure> + +- Choose `Create key pair` and select `AWS region` at the top right corner of the windows where you plan to deploy the VyOS instance. + +<figure> +<img src="/_static/images/cloud-aws-keypair-02.webp" /> +</figure> + +\- Configure Key Pair: +"""""""""" + +> - **Name**: Enter a descriptive name for the key pair, e.g., `vyos-keypair`. +> +> > <div class="note"> +> > +> > <div class="title"> +> > +> > Note +> > +> > </div> +> > +> > The key name can include up to 255 ASCII characters. It cannot include leading or trailing spaces. +> > +> > </div> +> +> - **Select Key Pair Type**: +> - For **Linux instances**: Choose either **RSA** or **ED25519**. +> +> - For **Windows instances**: Choose **RSA**. +> +> <div class="note"> +> +> <div class="title"> +> +> Note +> +> </div> +> +> ED25519 keys are not supported for Windows instances. +> +> </div> +> - **Private Key File Format**: +> - **PEM**: Choose this format if using OpenSSH or other SSH clients (e.g., on Linux/macOS). +> - **PPK**: Choose this format if using PuTTY on Windows. + +- **Optional**: Add tags to the key pair. Choose **Add tag** and provide the **key** and **value** for each tag. + +- Choose **Create key pair**. + +- The private key file will automatically download to your browser. + - The file name will match the name you provided (e.g., <span class="title-ref">vyos-keypair.pem</span>), with the extension determined by the format you chose. + +<figure> +<img src="/_static/images/cloud-aws-keypair-03.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-aws-keypair-04.webp" alt="Important Notes" /> +<figcaption aria-hidden="true"><strong>Important Notes</strong></figcaption> +</figure> + +- **Save the private key file securely**: + This is your **only chance** to download the private key. If you lose it, you cannot connect to your instance. + +- If you are using SSH on a **macOS or Linux computer**, set the correct permissions for the private key file: + +``` none +chmod 400 vyos-keypair.pem +``` + +If permissions are not set to **400**, you will encounter an **"Unprotected private key file"** error when attempting to connect to the instance. + +> **Example Usage for SSH** + +``` none +ssh -i vyos-keypair.pem vyos@<Public/Elastic IP> +``` + +For more information, please visit the official AWS documentation: + +<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/create-key-pairs.html#having-ec2-create-your-key-pair> + +4\. VyOS Subscription +----------- +- Go to the AWS Marketplace <https://aws.amazon.com/marketplace> and search for **VyOS**. +- Subscribe to the VyOS AMI. + +For more information, please visit: + +<https://aws.amazon.com/marketplace/seller-profile?id=7636d180-1710-48bc-acd6-d323c4a0429f> + +Create required resources +======== + +Certain resources need to be created in the AWS infrastructure before creating a VyOS instance, such as a VPC, Subnets, Elastic IPs, Route Tables, Security Groups, and others. + +Step 1: Create Virtual Private Cloud (VPC) and Subnets +----------- + +1\. Create a VPC +^^^^^^^^^^^^^^ + +To create a VPC for your AWS environment: + +- Go to the **Amazon VPC Console** at <https://console.aws.amazon.com/vpc/>. +- In the navigation pane, choose **Your VPCs**. +- Choose **Create VPC**. + +<figure> +<img src="/_static/images/cloud-aws-vpc-01.webp" /> +</figure> + +- **Configure VPC Settings**: + - **Name tag - optional**: Enter a descriptive name for your VPC, e.g., `VyOS-VPC`. + - **IPv4 CIDR Block**: Enter `10.0.0.0/16`. + +- Choose **Create VPC**. + +<figure> +<img src="/_static/images/cloud-aws-vpc-02.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-aws-vpc-03.webp" /> +</figure> + +For more information, please visit the AWS documentation: + +<https://docs.aws.amazon.com/vpc/latest/userguide/create-vpc.html> + +2\. Create Subnets +^^^^^^^^^^^^^^ + +Subnets allow you to divide your VPC into smaller IP spaces. Follow these steps to create subnets for both **public** and **private** networks: + +- Go to the **Amazon VPC Console** at <https://console.aws.amazon.com/vpc/>. +- In the navigation pane, choose **Subnets**. +- Choose **Create Subnet**. + +<figure> +<img src="/_static/images/cloud-aws-subnet-01.webp" /> +</figure> + +\- Configure Subnet Settings: +"""""""""" + +> - **Public Subnet**: +> - **VPC**: Select `VyOS-VPC`. +> - **Name Tag**: `VyOS-Public-Subnet`. +> - **IPv4 CIDR Block**: `10.0.1.0/24`. +> - **Availability Zone**: Select an AZ, e.g., `us-east-1a`. +> - **Private Subnet**: +> - **VPC**: Select `VyOS-VPC`. +> - **Name Tag**: `VyOS-Private-Subnet`. +> - **IPv4 CIDR Block**: `10.0.2.0/24`. +> - **Availability Zone**: Select an AZ, e.g., `us-east-1a`. + +- Choose **Create Subnet**. + +<figure> +<img src="/_static/images/cloud-aws-subnet-02.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-aws-subnet-03.webp" /> +</figure> + +For additional information, please visit the AWS documentation: + +<https://docs.aws.amazon.com/vpc/latest/userguide/create-subnets.html> + +For additional details about IP addressing for your VPC and subnets, refer to the AWS documentation: + +<https://docs.aws.amazon.com/vpc/latest/userguide/vpc-ip-addressing.html> + +Step 2: Create and Configure Security Groups +----------- + +1\. Create Public Security Group +^^^^^^^^^^^^^^ + +The **Public Security Group** is used for **outbound connectivity**. All external resources, systems, or networks will connect via this security group. + +- Open the **Amazon EC2 Console** at <https://console.aws.amazon.com/ec2/>. +- In the navigation pane, choose **Security Groups**. +- Choose **Create Security Group**. + +<figure> +<img src="/_static/images/cloud-aws-sg-01.webp" /> +</figure> + +- **Configure the Security Group**: + + > - **Name**: `VyOS-Public-SG`. + > - **Description**: "Public security group for outbound connectivity" + > - **VPC**: Select the VPC in which your VyOS instance resides. + +\- Inbound Rules: +"""""""""" + +> - **SSH**: Port `22`, Source `0.0.0.0/0` (Restrict to your IP for security). +> - **ICMP**: Allow for ping testing purposes. +> - **IPSec**: Allow port `500` (UDP) for ISAKMP (Phase 1 negotiation). +> - **NAT Traversal**: Allow port `4500` (UDP) for NAT-T support in IPsec. +> - **WireGuard**: Allow port `51820` (UDP). +> - **OpenVPN**: Allow port `1194` (UDP or TCP). + +<figure> +<img src="/_static/images/cloud-aws-sg-02.webp" /> +</figure> + +- (Optional) Add tags to identify the security group: + - **Key**: <span class="title-ref">Name</span>, **Value**: <span class="title-ref">VyOS-Public-SG</span>. + +- Choose **Create Security Group**. + +<figure> +<img src="/_static/images/cloud-aws-sg-03.webp" /> +</figure> + +2\. Create Private Security Group +^^^^^^^^^^^^^^ + +The **Private Security Group** is used for **internal connectivity** from internal or VPC-based resources. + +- Open the **Amazon EC2 Console**. +- In the navigation pane, choose **Security Groups**. +- Choose **Create Security Group**. + +\- Configure the Security Group: +"""""""""" + +> - **Name**: `VyOS-Private-SG`. +> - **Description**: "Private security group for internal connectivity" +> - **VPC**: Select the VPC in which your VyOS instance resides. + +\- Inbound Rules: +"""""""""" + +> - Allow **All Traffic** (`0.0.0.0/0`) for internal connectivity between resources, VPCs, and other trusted networks. + +<figure> +<img src="/_static/images/cloud-aws-sg-04.webp" /> +</figure> + +- (Optional) Add tags to identify the security group: + - **Key**: `Name`, **Value**: `VyOS-Private-SG`. + +- Choose **Create Security Group**. + +<figure> +<img src="/_static/images/cloud-aws-sg-05.webp" /> +</figure> + +For detailed instructions on creating a security group, refer to the official AWS documentation: + +<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/creating-security-group.html> + +For more information, refer to the official AWS documentation: + +<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html> + +Step 3: Create ENIs (Elastic Network Interfaces) +----------- + +Network Interfaces (ENIs) are essential for connecting instances to subnets and managing network traffic. Follow the steps below to create **Public** and **Private** ENIs. + +- Open the **Amazon EC2 Console** at <https://console.aws.amazon.com/ec2/>. +- In the navigation pane, choose **Network Interfaces**. +- Choose **Create Network Interface**. +- **Configure Network Interface Settings**: + +# Public ENI + +> - **Name**: `VyOS-Public-ENI`. +> - **Description**: "Network Interface for Public Subnet." +> - **Subnet**: Select the `VyOS-Public-Subnet` you created earlier. +> - **Private IPv4 Address**: Choose **Auto-assign** to let AWS pick an IP address from the subnet. +> - **Security Group**: Select the `VyOS-Public-SG`. +> +> \- (Optional) Add tags to identify the ENIs: +> **Key**: `Name`, **Value**: `VyOS-Public-ENI`. +> +> - Choose **Create Network Interface**. +> +> <figure> +> <img src="/_static/images/cloud-aws-eni-01.webp" /> +> </figure> + +Private ENI +"""""""""" +- **Name**: `VyOS-Private-ENI`. + +> - **Description**: "Network Interface for Private Subnet." +> - **Subnet**: Select the `VyOS-Private-Subnet` you created earlier. +> - **Private IPv4 Address**: Choose **Auto-assign** to let AWS pick an IP address from the subnet. +> - **Security Group**: Select the `VyOS-Private-SG`. +> +> \- (Optional) Add tags to identify the ENIs: +> **Key**: `Name`, **Value**: `VyOS-Private-ENI`. +> +> - Choose **Create Network Interface**. +> +> <figure> +> <img src="/_static/images/cloud-aws-eni-02.webp" /> +> </figure> + +Step 4: Configure Internet Gateway +----------- + +An **Internet Gateway** allows communication between your VPC and the internet. Follow the steps below to create and attach an Internet Gateway to your VPC. + +1\. Create an Internet Gateway +^^^^^^^^^^^^^^ + +- Open the **Amazon VPC Console** at <https://console.aws.amazon.com/vpc/>. + +- In the navigation pane, choose **Internet Gateways**. + +- Choose **Create Internet Gateway**. + +- **Configure Internet Gateway**: + - (Optional) **Name**: Enter a descriptive name, e.g., `VyOS-IGW`. + +- (Optional) Add a tag to identify the Internet Gateway: + - **Key**: `Name`, **Value**: `VyOS-IGW`. + +- Choose **Create Internet Gateway**. + +<figure> +<img src="/_static/images/cloud-aws-igw-01.webp" /> +</figure> + +2\. Attach the Internet Gateway to Your VPC +^^^^^^^^^^^^^^ + +To enable your VPC to access the internet, attach the Internet Gateway to your VPC: + +- After creating the Internet Gateway, select it from the **Internet Gateways** list. + +- Choose **Actions \> Attach to VPC**. + +- Select the VPC where you want to attach the Internet Gateway: + - Choose <span class="title-ref">VyOS-VPC</span> (the VPC you created earlier). + +- Choose **Attach Internet Gateway**. + +<figure> +<img src="/_static/images/cloud-aws-igw-02.webp" /> +</figure> + +For more details, refer to the official AWS documentation: + +<https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Internet_Gateway.html>. + +Step 5: Configure Route Tables +----------- + +Route tables define the paths for network traffic within your VPC. In this step, we will configure **Public** and **Private** route tables to control traffic flow for their respective subnets. + +1\. Create and Configure the Public Route Table +^^^^^^^^^^^^^^ + +- **Go to the Route Tables Section:** + - Open the **Amazon VPC Console** at <https://console.aws.amazon.com/vpc/>. + - In the left navigation pane, choose **Route Tables**. + +- **Create a New Route Table:** + + > - In the **Route Tables** section, choose **Create Route Table**. + > - Configure the route table: + > - **Name**: `Public RT`. + > - **VPC**: Select the `VyOS-VPC`. + > - Click **Create Route Table**. + > + > <figure> + > <img src="/_static/images/cloud-aws-route-01.webp" /> + > </figure> + +- **Add a Route to the Internet Gateway:** + + > - Go to the **Routes** tab and click **Edit Routes**. + > - Click **Add Route** and enter: + > - **Destination**: `0.0.0.0/0` (Default route to all IPs). + > - **Target**: Select the **Internet Gateway** (`VyOS-IGW`) you created earlier. + > - Click **Save Routes**. + > + > <figure> + > <img src="/_static/images/cloud-aws-route-02.webp" /> + > </figure> + +- **Associate the Public Subnet:** + + > - Go to the **Subnet Associations** tab and click **Edit Subnet Associations**. + > - Select the **Public Subnet** (`VyOS-Public-Subnet`). + > - Click **Save associations**. + > + > <figure> + > <img src="/_static/images/cloud-aws-route-03.webp" /> + > </figure> + +Step 6: Allocate and Attach Elastic IP (EIP) +----------- + +An **Elastic IP (EIP)** is a static, public IPv4 address designed for dynamic cloud computing. Elastic IP addresses can help maintain consistent connectivity to instances, even if they are stopped, rebooted, or replaced. + +- Elastic IP addresses are **public IPv4 addresses** and are reachable from the internet. +- They can be quickly remapped to different instances or network interfaces within your AWS account to mask failures. + +For more details, refer to the official AWS documentation: + +<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html>. + +Steps to Allocate and Attach Elastic IP +^^^^^^^^^^^^^^ + +1\. Allocate Elastic IP +"""""""""" + +- Open the **Amazon EC2 Console** at <https://console.aws.amazon.com/ec2/>. + +- In the navigation pane, choose **Elastic IPs**. + +- Choose **Allocate Elastic IP address**. + +- **Elastic IP address settings**: + - For **Public IPv4 address pool**, select **Amazon's pool of IPv4 addresses**. + +- (Optional) Add a tag: + - **Key**: `Name`, **Value**: `VyOS-EIP`. + +- Choose **Allocate**. + +<figure> +<img src="/_static/images/cloud-aws-eip-01.webp" /> +</figure> + +2\. Attach Elastic IP to Public ENI +"""""""""" + +- Go to **EC2 \> Elastic IPs**. + +- Select the **Elastic IP** you just allocated. + +- Choose **Actions \> Associate Elastic IP address**. + +- **Configure Association**: + + > - **Resource type**: Choose **Network Interface**. + > - **Network Interface**: Select the **VyOS-Public-ENI** created earlier. + > - **Private IPv4 Address**: Ensure it is correctly selected. + +- (Optional) Select **Allow the Elastic IP address to be reassociated** if the EIP is already associated with another resource. + +- Choose **Associate**. + +<figure> +<img src="/_static/images/cloud-aws-eip-02.webp" /> +</figure> + +**Why Use Elastic IP?** + +- **Consistency**: The EIP remains static, even if the instance stops or is replaced. +- **Failover**: If an instance fails, you can remap the EIP to a new instance to restore services quickly. +- **DNS Integration**: You can point your domain to the Elastic IP for consistent public access. + +For additional details, refer to the AWS documentation: + +<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/working-with-eips.html> + +Launch VyOS Instance +======== + +Follow the detailed instructions below to launch a VyOS instance in your AWS environment with two ENIs (Public and Private). + +- Open the **Amazon EC2 Console** at <https://console.aws.amazon.com/ec2/>. + +- In the EC2 dashboard, choose **Launch Instance**. + +- **Configure Instance Details**: + + > - **Name and Tags**: + > + > - Under **Name and tags**, enter a descriptive name for your instance, e.g., `VyOS-Instance`. + > + > <figure> + > <img src="/_static/images/cloud-aws-vyos-01.webp" /> + > </figure> + > + > - **Application and OS Images (AMI)**: + > + > - Choose **Browse more AMIs**. + > - Go to the **AWS Marketplace** tab and search for **VyOS**. + > - Choose the VyOS AMI that matches your requirements and click **Select**. + > + > <figure> + > <img src="/_static/images/cloud-aws-vyos-02.webp" /> + > </figure> + > + > <figure> + > <img src="/_static/images/cloud-aws-vyos-03.webp" /> + > </figure> + > + > - **Instance Type**: + > + > - Select the instance type that fits your workload. For example: + > - `c5n.large` (or larger recommended for VyOS). + > + > > <figure> + > > <img src="/_static/images/cloud-aws-vyos-04.webp" /> + > > </figure> + > + > - **Key pair (login)**: + > + > - For **Key pair name**, select the key pair you created earlier (`vyos-keypair`). + > - If you do not have a key pair, create a new one and download the private key file. + > + > <figure> + > <img src="/_static/images/cloud-aws-vyos-05.webp" /> + > </figure> + > + > - **Network Settings**: + > + > - **VPC**: Select `VyOS-VPC`. + > - **Subnet**: Select the **Public Subnet** (`VyOS-Public-Subnet`). + > - **Auto-assign Public IP**: **Disable**. + > - **Firewall (security groups)**: Select the **Select existing security group**. + > - **Common security groups**: Live empty (Do not select any security groups). + > + > <figure> + > <img src="/_static/images/cloud-aws-vyos-09.webp" /> + > </figure> + > + > - **Advanced network configuration** + > + > > - **Network interface 1** select `VyOS-Public-ENI` + > > + > > <figure> + > > <img src="/_static/images/cloud-aws-vyos-07.webp" /> + > > </figure> + > > + > > - Click to the **Add network interface** button + > > - **Network interface 2** select `VyOS-Private-ENI` + > > + > > <figure> + > > <img src="/_static/images/cloud-aws-vyos-08.webp" /> + > > </figure> + > > + > > - In **Subnet** deselect subnet + > > + > > <figure> + > > <img src="/_static/images/cloud-aws-vyos-10.webp" /> + > > </figure> + +- Review the instance configuration in the **Summary** panel and choose **Launch Instance**. + +- Wait until the instance status changes to **Running**. + +<figure> +<img src="/_static/images/cloud-aws-vyos-11.webp" /> +</figure> + +Connect to the VyOS instance +----------- + +> You can only connect to the VyOS instance via **SSH** protocol. Use the default username **vyos**, **Elastic IP** and **SSH Key Pair** to connect to the VyOS instance via SSH: +> +> ``` none +> ssh -i vyos-keypair.pem vyos@35.152.131.62 +> ``` + +Deployment of VyOS Instance and Required Resources via CloudFormation Template +======== + +These CloudFormation templates automate the deployment of a VyOS instance on AWS, configuring essential components such as: + +- VPC +- Public and private subnets +- Internet Gateway +- Route Tables +- Elastic IPs +- Security Groups + +You can download or clone these templates from the GitHub repository and use them in your environment: + +<https://github.com/vyos/vyos-automation/tree/main/CloudFormation> + +Deployment of VyOS Instance and Required Resources via Terraform +======== + +These Terraform projects automate the deployment of a VyOS instance on AWS, configuring essential components such as: + +- VPC +- Public and private subnets +- Internet Gateway +- Route Tables +- Elastic IPs +- Security Groups + +You can download or clone these templates from the GitHub repository and use them in your environment: + +<https://github.com/vyos/vyos-automation/tree/main/Terraform/AWS/> + +## Amazon CloudWatch Agent Usage + +To use Amazon CloudWatch Agent, configure it within the Amazon SSM Parameter Store. If you don't have a configuration yet, do `configuration_creation`. + +1. Create an `IAM (Identity and Access Management)` role for the `EC2 (Elastic Compute Cloud)` instance to access CloudWatch service, and name it CloudWatchAgentServerRole. The role should contain two default policies: CloudWatchAgentServerPolicy and AmazonSSMManagedInstanceCore. +2. Attach the created role to your VyOS `EC2 (Elastic Compute Cloud)` instance. +3. Ensure that amazon-cloudwatch-agent package is installed. + +> ``` none +> $ sudo apt list --installed | grep amazon-cloudwatch-agent +> ``` +> +> <div class="note"> +> +> <div class="title"> +> +> Note +> +> </div> +> +> The amazon-cloudwatch-agent package is normally included in VyOS 1.3.3+ and 1.4+ +> +> </div> + +3. Retrieve an existing CloudWatch Agent configuration from the `SSM (Systems Manager)` Parameter Store. + +> ``` none +> $ sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -s -c ssm:<your-configuration-name> +> ``` +> +> This step also enables systemd service and runs it. +> +> <div class="note"> +> +> <div class="title"> +> +> Note +> +> </div> +> +> The VyOS platform-specific scripts feature is under development. Thus, this step should be repeated manually after changing system image (`/installation/update`) +> +> </div> + +### CloudWatch SSM Configuration creation + +Creating the Amazon Cloudwatch Agent Configuration in Amazon `SSM (Systems Manager)` Parameter Store. + +1. Create an `IAM (Identity and Access Management)` role for your `EC2 (Elastic Compute Cloud)` instance to access the CloudWatch service. Name it CloudWatchAgentAdminRole. The role should contain at two default policies: CloudWatchAgentAdminPolicy and AmazonSSMManagedInstanceCore. + +> <div class="note"> +> +> <div class="title"> +> +> Note +> +> </div> +> +> CloudWatchAgentServerRole is too permissive and should be used for single configuration creation and deployment. That's why after completion of step \#3 highly recommended to replace instance CloudWatchAgentAdminRole role with CloudWatchAgentServerRole. +> +> </div> + +2. Run Cloudwatch configuration wizard. + +> ``` none +> $ sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-config-wizard +> ``` + +3. When prompted, answer "yes" to the question "Do you want to store the config in the SSM parameter store?". + +## References + +- <https://console.aws.amazon.com/> +- <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/create-iam-roles-for-cloudwatch-agent.html> +- <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-on-EC2-Instance-fleet.html> diff --git a/docs/installation/cloud/md-azure-ha.md b/docs/installation/cloud/md-azure-ha.md new file mode 100644 index 00000000..4a77565d --- /dev/null +++ b/docs/installation/cloud/md-azure-ha.md @@ -0,0 +1,130 @@ +\########## +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> +<img src="/_static/images/cloud-azure-ha-architecture.webp" alt="VyOS HA topology diagram" /> +</figure> + +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..8489a532 --- /dev/null +++ b/docs/installation/cloud/md-azure.md @@ -0,0 +1,449 @@ +\########## +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> +<img src="/_static/images/cloud-azure-rg-01.webp" /> +</figure> + +- 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> +<img src="/_static/images/cloud-azure-rg-02.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-azure-vnet-01.webp" /> +</figure> + +**IP addresses**: + +- Address Space: `10.1.0.0/16` + +<figure> +<img src="/_static/images/cloud-azure-vnet-02.webp" /> +</figure> + +**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> +<img src="/_static/images/cloud-azure-vnet-03.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-azure-vnet-04.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-azure-vnet-05.webp" /> +</figure> + +- 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> +<img src="/_static/images/cloud-azure-sg-01.webp" /> +</figure> + +- 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> +<img src="/_static/images/cloud-azure-sg-02.webp" /> +</figure> + +**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> +<img src="/_static/images/cloud-azure-sg-03.webp" /> +</figure> + +**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> +<img src="/_static/images/cloud-azure-sg-04.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-azure-pub-ip-01.webp" /> +</figure> + +- **Name**: `VyOS-Pub-IP` +- **IP Version**: `IPv4` +- **SKU**: `Standard` +- **Availability zone**: Select Availability Zone + +<figure> +<img src="/_static/images/cloud-azure-pub-ip-02.webp" /> +</figure> + +- **IP address assignment**: `Static` +- **Idle timeout (minutes)** `30` (max) + +<figure> +<img src="/_static/images/cloud-azure-pub-ip-03.webp" /> +</figure> + +- 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> +<img src="/_static/images/cloud-azure-vm-01.webp" /> +</figure> + +- **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> +<img src="/_static/images/cloud-azure-vm-02.webp" /> +</figure> + +- **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> +<img src="/_static/images/cloud-azure-vm-03.webp" /> +</figure> + +- **Virtual network**: Select `VyOS-VirtualNetwork`. +- **Subnet**: Select `VyOS-Public-Subnet`. +- **Public IP**: Select public IP address which created before `VyOS-Pub-IP`. + +<figure> +<img src="/_static/images/cloud-azure-vm-04.webp" /> +</figure> + +- **Configure network security group**: Select existing Security Group `VyOS-SecurityGroup`. + +<figure> +<img src="/_static/images/cloud-azure-vm-05.webp" /> +</figure> + +- 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> +<img src="/_static/images/cloud-azure-vm-06.webp" /> +</figure> + +- Wait until deployment is complete. After the deployment complete navigate to **Virtual Machines** click new created Virtual Machine. Check **Public IP address**. + +<figure> +<img src="/_static/images/cloud-azure-vm-07.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-azure-vm-12.webp" /> +</figure> + +- Enable IP forwarding and click the **Apply** button. + +<figure> +<img src="/_static/images/cloud-azure-vm-13.webp" /> +</figure> + +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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Azure does not allow you attach interface when the instance in the +**Running** state. + +</div> + +Create network interface: +^^^^^^^^^^^^^^ + +- In the Azure Portal, search for and select **Network Interfaces**. +- On the **Network Interfaces** page, select **+ Create**. + +<figure> +<img src="/_static/images/cloud-azure-nic-01.webp" /> +</figure> + +- **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> +<img src="/_static/images/cloud-azure-nic-02.webp" /> +</figure> + +- Enable **IP Forwarding** +- Navigate to **Network Interfaces** select `VyOS-PRIV-NIC` + +<figure> +<img src="/_static/images/cloud-azure-nic-03.webp" /> +</figure> + +- Go to **Settings**, select **IP configurations**. Enable IP Forwarding and select **Apply**. + +<figure> +<img src="/_static/images/cloud-azure-nic-04.webp" /> +</figure> + +Attach reate network interface: +^^^^^^^^^^^^^^ + +- Navigate to **Virtual Machines**, click new created Virtual Machine and click the **Stop** button + +<figure> +<img src="/_static/images/cloud-azure-vm-08.webp" /> +</figure> + +- Go to **Networking** select **Network settings** and then select **Attach network interface** + +<figure> +<img src="/_static/images/cloud-azure-vm-09.webp" /> +</figure> + +- Select existing (before created) network interface `VyOS-PRIV-NIC` and click the **OK** button. + +<figure> +<img src="/_static/images/cloud-azure-vm-10.webp" /> +</figure> + +- Now you have attached second interface to your instance and you can start Virtual Machine. +- Go to **Overview** and click the **Start** button. + +<figure> +<img src="/_static/images/cloud-azure-vm-11.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-azure-route-01.webp" /> +</figure> + +- 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> +<img src="/_static/images/cloud-azure-route-02.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-azure-route-03.webp" /> +</figure> + +- 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> +<img src="/_static/images/cloud-azure-route-04.webp" /> +</figure> + +- **Virtual network**: Select `VyOS-VirtualNetwork`. +- **Subnet**: Select `VyOS-Public-Subnet`. + +<figure> +<img src="/_static/images/cloud-azure-route-05.webp" /> +</figure> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +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..b30d6494 --- /dev/null +++ b/docs/installation/cloud/md-gcp.md @@ -0,0 +1,298 @@ +\##################### +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" +> ``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +2. Open GCP console and navigate to the **Compute Engine** \> **Metadata** \> **SSH Keys**. Choose + **SSH Keys**. + +<figure> +<img src="/_static/images/cloud-gcp-01.webp" /> +</figure> + +3. Click **edit** and **Add item**. +4. Paste your public ssh key and **Save**. + +<figure> +<img src="/_static/images/cloud-gcp-02.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-gcp-proj.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-gcp-svc.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-gcp-proj.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-gcp-vpc-01.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-gcp-vpc-02.webp" alt="Private VPC:" /> +<figcaption><strong>Private VPC</strong>: +<ul> +<li>Name: <code>vyos-private-vpc</code></li> +<li>Subnet creation mode: <code>Custom</code></li> +<li>Subnet name: <code>vyos-private-subnet</code></li> +<li>Region: e.g., <code>europe-west1</code></li> +<li>IP range: <code>10.0.11.0/24</code></li> +<li>Leave all other settings at default, then click <strong>Create</strong>.</li> +</ul></figcaption> +</figure> + +<figure> +<img src="/_static/images/cloud-gcp-vpc-03.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-gcp-vpc-04.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-gcp-vpc-05.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-gcp-vpc-06.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-gcp-vpc-07.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-gcp-proj.webp" /> +</figure> + +3. In the search bar, type `vyos` to find the VyOS image in the Marketplace. + +<figure> +<img src="/_static/images/cloud-gcp-market-01.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-gcp-market-02.webp" /> +</figure> + +4. On the next page, review details such as support, pricing, and other details. + +<figure> +<img src="/_static/images/cloud-gcp-market-03.webp" /> +</figure> + +5. Click the `GET STARTED` button to start deployment process. + +<figure> +<img src="/_static/images/cloud-gcp-market-04.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-gcp-market-05.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-gcp-vm-01.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-gcp-vm-02.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-gcp-vm-03.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-gcp-vm-09.webp" /> +</figure> + +9. Click `Deploy` button. + +<figure> +<img src="/_static/images/cloud-gcp-vm-06.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-gcp-vm-07.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-gcp-vm-08.webp" /> +</figure> + +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..1c1e1ed6 --- /dev/null +++ b/docs/installation/cloud/md-index.md @@ -0,0 +1,13 @@ +# Running VyOS in Cloud Environments + +<div class="toctree" caption="Content"> + +aws +aws-ha +azure +azure-ha +aws-to-azure +gcp +oracle + +</div> 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..fb57d73f --- /dev/null +++ b/docs/installation/md-image.md @@ -0,0 +1,131 @@ +# 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. + +<div class="opcmd"> + +show system image + +List all available system images which can be booted on the current system. + +``` 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 +``` + +</div> + +<div class="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 `show system image`. + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show version + +Show current system image version. + +``` 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 +``` + +</div> + +## System rollback + +If you need to rollback to a previous image, you can easily do so. First +check the available images through the `show system image` +command and then select your image with the following command: + +<div class="opcmd"> + +set system image default-boot \[image-name\] + +Select the default boot image which will be started on the next boot +of the system. + +</div> + +Then reboot the system. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +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..2e8e93c9 --- /dev/null +++ b/docs/installation/md-index.md @@ -0,0 +1,34 @@ +# Installation and Image Management + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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`. + +</div> + +<div class="toctree" maxdepth="2" caption="Content"> + +install +virtual/index +cloud/index +vyos-on-baremetal +update +image +migrate-from-vyatta + +</div> diff --git a/docs/installation/md-install.md b/docs/installation/md-install.md new file mode 100644 index 00000000..947d71d7 --- /dev/null +++ b/docs/installation/md-install.md @@ -0,0 +1,504 @@ +# 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. + +<table style="width:98%;"> +<caption>Comparison of VyOS image releases</caption> +<colgroup> +<col style="width: 8%" /> +<col style="width: 29%" /> +<col style="width: 11%" /> +<col style="width: 22%" /> +<col style="width: 13%" /> +<col style="width: 10%" /> +</colgroup> +<thead> +<tr> +<th>Release Type</th> +<th>Description</th> +<th>Release Cycle</th> +<th>Intended Use</th> +<th>Access to Images</th> +<th>Access to Source</th> +</tr> +</thead> +<tbody> +<tr> +<td><strong>Nightly +(Current)</strong></td> +<td>Automatically built from the current branch. +Always up to date with cutting edge development +but guaranteed to contain bugs.</td> +<td>Every night</td> +<td>Developing VyOS, testing new +features, experimenting.</td> +<td>Everyone</td> +<td>Everyone</td> +</tr> +<tr> +<td><strong>Stream</strong></td> +<td>VyOS Stream serves as a technology preview and +a quality gate for the upcoming LTS release. +Allows everyone to try new features and check +if they work well or need improvements</td> +<td>Every quarter</td> +<td>Non-critical production environments, +preparing for the LTS release.</td> +<td>Everyone</td> +<td>Everyone</td> +</tr> +<tr> +<td><strong>Release +Candidate</strong></td> +<td>Rather stable. All development focuses on testing +and hunting down remaining bugs following the +feature freeze.</td> +<td>Irregularly until +EPA comes out</td> +<td>Labs, small offices and non-critical +production systems backed by a +high-availability setup.</td> +<td>Everyone</td> +<td>Everyone</td> +</tr> +<tr> +<td><strong>Early +Production +Access</strong></td> +<td>Highly stable with no known bugs. Needs to be +tested repeatedly under different conditions +before it can become the final release.</td> +<td>Irregularly until +LTS comes out</td> +<td>Non-critical production environments, +preparing for the LTS release.</td> +<td>Everyone</td> +<td>Everyone</td> +</tr> +<tr> +<td><strong>Long-Term +Support</strong></td> +<td>Guaranteed to be stable and carefully maintained +for several years after the release. No features +are introduced but security updates are released +in a timely manner.</td> +<td>Every major +version</td> +<td>Large-scale enterprise networks, +internet service providers, +critical production environments +that call for minimum downtime.</td> +<td>Subscribers, +contributors, +non-profits, +emergency services, +academic institutions</td> +<td>Everyone</td> +</tr> +</tbody> +</table> + +## 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](https://customers.support.vyos.com/servicedesk/customer/portal/1/article/159055913) for more information on downloads. + +<figure> +<img src="/_static/images/vyosnew-downloads.webp" /> +</figure> + +### Rolling Release + +Everyone can download bleeding-edge VyOS rolling images from: +<https://downloads.vyos.io/> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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 `bug_report`. We depend on your feedback +to improve VyOS! + +</div> + +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 + +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. + +`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 +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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(`T7301`). + +</div> + +## Live installation + +<div class="note"> + +<div class="title"> + +Note + +</div> + +A permanent VyOS installation always requires to go first +through a live installation. + +</div> + +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 `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](https://www.balena.io/etcher/) (for GNU/Linux, +macOS and Windows), [Rufus](https://rufus.ie/) (for Windows) and [many others](https://en.wikipedia.org/wiki/List_of_tools_to_create_Live_USB_systems). You can +follow their instructions to create a bootable USB drive from an .iso +file. + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +The default username and password for the live system is *vyos*. + +</div> + +## Permanent installation + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Before a permanent installation, VyOS requires a +`live_installation`. + +</div> + +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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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 +`image-mgmt` for further information). + +</div> + +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> +<img src="/_static/images/permanent_install.webp" alt="3. After the installation is completed, remove the live USB stick or CD." /> +<figcaption>3. After the installation is completed, remove the live USB stick or +CD. +<ol start="4" type="1"> +<li>Reboot the system.</li> +</ol> +<pre class="none"><code>vyos@vyos:~$ reboot +Proceed with reboot? (Yes/No) [No] Yes</code></pre> +<p>You will boot now into a permanent VyOS system.</p></figcaption> +</figure> + +## 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 +- `dhcp-server` +- `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 + } + } + } +``` + +#### 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](https://wiki.syslinux.org/wiki/index.php?title=Config) file shown below, which we named + [default](https://wiki.syslinux.org/wiki/index.php?title=PXELINUX#Configuration). + +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](https://docs.python.org/2/library/simplehttpserver.html) and start serving the <span class="title-ref">filesystem.squashfs</span> +file. The file can be found inside the <span class="title-ref">/live</span> directory of the +extracted contents of the ISO file. + +**Second**, edit the configuration file of the `install_from_tftp` +so that it shows the correct URL at +`fetch=http://<address_of_your_HTTP_server>/filesystem.squashfs`. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Do not change the name of the *filesystem.squashfs* file. If +you are working with different versions, you can create different +directories instead. + +</div> + +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`. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Make sure the available directories and files in both TFTP +and HTTP server have the right permissions to be accessed from the +booting clients. + +</div> + +### 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 +<span class="title-ref">Live system</span> option from the installation image. + +The workaround is to type <span class="title-ref">e</span> when the boot menu appears and edit the GRUB boot +options. Specifically, remove the: + +<span class="title-ref">console=ttyS0,115200</span> + +option, and type CTRL-X to boot. + +Installation can then continue as outlined above. diff --git a/docs/installation/md-update.md b/docs/installation/md-update.md new file mode 100644 index 00000000..cff79228 --- /dev/null +++ b/docs/installation/md-update.md @@ -0,0 +1,110 @@ +# Update VyOS + +New system images can be added using the `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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Only LTS releases are PGP-signed. + +</div> + +<div class="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 <span class="title-ref">add system image</span> 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. + +</div> + +If there is not enough **free disk space available**, the installation +will be canceled. To delete images use the `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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +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 `copy` command. So, for instance, in order +to copy `/config/config.boot` from VyOS 1.2.1 image, you would use the +following command: + +``` +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 +``` + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +The most up-do-date Rolling Release for AMD64 can be accessed using +the following URL: + +<https://vyos.net/get/nightly-builds/> + +</div> + +After reboot you might want to verify the version you are running with +the `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..aaf2c78d --- /dev/null +++ b/docs/installation/md-vyos-on-baremetal.md @@ -0,0 +1,609 @@ +# 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> +<img src="/_static/images/1u_vyos_back.webp" alt="CSE-505-203B Back" /> +</figure> + +<figure> +<img src="/_static/images/1u_vyos_front.webp" alt="CSE-505-203B Front" /> +</figure> + +<figure> +<img src="/_static/images/1u_vyos_front_open_1.webp" alt="CSE-505-203B Open 1" /> +</figure> + +<figure> +<img src="/_static/images/1u_vyos_front_open_2.webp" alt="CSE-505-203B Open 2" /> +</figure> + +<figure> +<img src="/_static/images/1u_vyos_front_open_3.webp" alt="CSE-505-203B Open 3" /> +</figure> + +<figure> +<img src="/_static/images/1u_vyos_front_10ge_open_1.webp" alt="CSE-505-203B w/ 10GE Open 1" /> +</figure> + +<figure> +<img src="/_static/images/1u_vyos_front_10ge_open_2.webp" alt="CSE-505-203B w/ 10GE Open 2" /> +</figure> + +<figure> +<img src="/_static/images/1u_vyos_front_10ge_open_3.webp" alt="CSE-505-203B w/ 10GE Open 3" /> +</figure> + +<figure> +<img src="/_static/images/1u_vyos_front_10ge_open_4.webp" alt="CSE-505-203B w/ 10GE Open" /> +</figure> + +## 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. + +### 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 `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 `wireless-interface-intel-ax200`) + +##### WWAN + +Refer to `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 (`T1327`). + +Create a bootable USB pendrive using e.g. [Rufus](https://rufus.ie/) 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 +`installation`. + +### Pictures + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Both device types operate without any moving parts and emit zero +noise. + +</div> + +#### Rack Mount + +<figure> +<img src="/_static/images/apu4_rack_1.webp" alt="APU4 rack closed" /> +</figure> + +<figure> +<img src="/_static/images/apu4_rack_2.webp" alt="APU4 rack front" /> +</figure> + +<figure> +<img src="/_static/images/apu4_rack_3.webp" alt="APU4 rack module #1" /> +</figure> + +<figure> +<img src="/_static/images/apu4_rack_4.webp" alt="APU4 rack module #2" /> +</figure> + +<figure> +<img src="/_static/images/apu4_rack_5.webp" alt="APU4 rack module #3 with PSU" /> +</figure> + +##### VyOS custom print + +<figure> +<img src="/_static/images/apu4_rack_vyos_print.webp" alt="APU4 custom VyOS powder coat" /> +</figure> + +#### Desktop / Bench Top + +<figure> +<img src="/_static/images/apu4_desk_1.webp" alt="APU4 desktop closed" /> +</figure> + +<figure> +<img src="/_static/images/apu4_desk_2.webp" alt="APU4 desktop closed" /> +</figure> + +<figure> +<img src="/_static/images/apu4_desk_3.webp" alt="APU4 desktop back" /> +</figure> + +<figure> +<img src="/_static/images/apu4_desk_4.webp" alt="APU4 desktop back" /> +</figure> + +## 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> +<img src="../_static/images/600px-Partaker-i5.webp" /> +</figure> + +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> +<img src="../_static/images/480px-Acrosser_ANDJ190N1_Front.webp" /> +</figure> + +<figure> +<img src="../_static/images/480px-Acrosser_ANDJ190N1_Back.webp" /> +</figure> + +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 <span class="title-ref">install image</span> CLI command. + +## 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> +<img src="../_static/images/gowin-01.webp" /> +</figure> + +<figure> +<img src="../_static/images/gowin-02.webp" /> +</figure> + +<figure> +<img src="../_static/images/gowin-03.webp" /> +</figure> + +<figure> +<img src="../_static/images/gowin-04.webp" /> +</figure> + +### 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 <span class="title-ref">install image</span> 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: `wwan-interface` diff --git a/docs/installation/virtual/md-docker.md b/docs/installation/virtual/md-docker.md new file mode 100644 index 00000000..964b9f64 --- /dev/null +++ b/docs/installation/virtual/md-docker.md @@ -0,0 +1,65 @@ +# 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..b1bb2a1d --- /dev/null +++ b/docs/installation/virtual/md-gns3.md @@ -0,0 +1,208 @@ +# 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 `installation` page +- A working GNS3 installation. For further information see the + [GNS3 documentation](https://docs.gns3.com/). + +## 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> +<img src="/_static/images/gns3-01.webp" /> +</figure> + +Select **Quemu VMs** and then click on the `New` button. + +<figure> +<img src="/_static/images/gns3-02.webp" /> +</figure> + +Write a name for your VM, for instance "VyOS", and click `Next`. + +<figure> +<img src="/_static/images/gns3-03.webp" /> +</figure> + +Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM +and click `Next`. + +<figure> +<img src="/_static/images/gns3-04.webp" /> +</figure> + +Select **telnet** as your console type and click `Next`. + +<figure> +<img src="/_static/images/gns3-05.webp" /> +</figure> + +Select **New image** for the base disk image of your VM and click +`Create`. + +<figure> +<img src="/_static/images/gns3-06.webp" /> +</figure> + +Use the defaults in the **Binary and format** window and click +`Next`. + +<figure> +<img src="/_static/images/gns3-07.webp" /> +</figure> + +Use the defaults in the **Qcow2 options** window and click `Next`. + +<figure> +<img src="/_static/images/gns3-08.webp" /> +</figure> + +Set the disk size to 2000 MiB, and click `Finish` to end the **Quemu +image creator**. + +<figure> +<img src="/_static/images/gns3-09.webp" /> +</figure> + +Click `Finish` to end the **New QEMU VM template** wizard. + +<figure> +<img src="/_static/images/gns3-10.webp" /> +</figure> + +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> +<img src="/_static/images/gns3-11.webp" /> +</figure> + +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> +<img src="/_static/images/gns3-12.webp" /> +</figure> + +At the **HDD** tab, change the Disk interface to **sata** to speed up +the boot process. + +<figure> +<img src="/_static/images/gns3-13.webp" /> +</figure> + +At the **CD/DVD** tab click on `Browse...` and locate the VyOS image +you want to install. + +<figure> +<img src="/_static/images/gns3-14.webp" /> +</figure> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +You probably will want to accept to copy the .iso file to your +default image directory when you are asked. + +</div> + +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> +<img src="/_static/images/gns3-15.webp" /> +</figure> + +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> +<img src="/_static/images/gns3-16.webp" /> +</figure> + +At the general **Preferences** window, click `OK` to save and close. + +<figure> +<img src="/_static/images/gns3-17.webp" /> +</figure> + +## 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. +- `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 + +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> +<img src="/_static/images/gns3-20.webp" /> +</figure> + +**CD/DVD** tab: Unmount the installation image file by clearing the +**Image** entry field. + +<figure> +<img src="/_static/images/gns3-21.webp" /> +</figure> + +Set the number of required network adapters, for example **4**. + +<figure> +<img src="/_static/images/gns3-215.webp" /> +</figure> + +**Advanced** settings tab: Mark the checkbox **Use as a linked +base VM** and click `OK` to save the changes. + +<figure> +<img src="/_static/images/gns3-22.webp" /> +</figure> + +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..7ed572e4 --- /dev/null +++ b/docs/installation/virtual/md-index.md @@ -0,0 +1,12 @@ +# Running VyOS in Virtual Environments + +<div class="toctree" caption="Content"> + +libvirt +proxmox +vmware +gns3 +eve-ng +docker + +</div> diff --git a/docs/installation/virtual/md-libvirt.md b/docs/installation/virtual/md-libvirt.md new file mode 100644 index 00000000..04a05ad0 --- /dev/null +++ b/docs/installation/virtual/md-libvirt.md @@ -0,0 +1,176 @@ +# 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 `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 +`VMM (Virtual Machine Manager)`. + +### Deploy from ISO + +1. Open `VMM (Virtual Machine Manager)` and Create a new + `VM (Virtual Machine)` +2. Choose `Local install media` (ISO) + +<figure> +<img src="/_static/images/virt-libvirt-01.webp" /> +</figure> + +3. Choose path to iso vyos.iso. Operating System can be any Debian based. + +<figure> +<img src="/_static/images/virt-libvirt-02.webp" /> +</figure> + +4. Choose Memory and CPU + +<figure> +<img src="/_static/images/virt-libvirt-03.webp" /> +</figure> + +5. Disk size + +<figure> +<img src="/_static/images/virt-libvirt-04.webp" /> +</figure> + +6. Name of VM and network selection + +<figure> +<img src="/_static/images/virt-libvirt-05.webp" /> +</figure> + +7. Then you will be taken to the console. + +<figure> +<img src="/_static/images/virt-libvirt-06.webp" /> +</figure> + +### 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 `VMM (Virtual Machine Manager)` and Create a new + `VM (Virtual Machine)` +2. Choose `Import existing disk` image + +<figure> +<img src="/_static/images/virt-libvirt-qc-01.webp" /> +</figure> + +3. Choose the path to the image `vyos_kvm.qcow2` that was previously + downloaded . Operation System can be any Debian based. + +<figure> +<img src="/_static/images/virt-libvirt-qc-02.webp" /> +</figure> + +4. Choose Memory and CPU + +<figure> +<img src="/_static/images/virt-libvirt-03.webp" /> +</figure> + +5. Name of VM and network selection + +<figure> +<img src="/_static/images/virt-libvirt-05.webp" /> +</figure> + +6. Then you will be taken to the console. + +<figure> +<img src="/_static/images/virt-libvirt-qc-03.webp" /> +</figure> diff --git a/docs/installation/virtual/md-proxmox.md b/docs/installation/virtual/md-proxmox.md new file mode 100644 index 00000000..da4bd03b --- /dev/null +++ b/docs/installation/virtual/md-proxmox.md @@ -0,0 +1,43 @@ +# 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 <span class="title-ref">local-lvm</span>. + +``` 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 <span class="title-ref">local</span> storage pool with the name <span class="title-ref">seed.iso</span>. + +``` 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 `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..6d693455 --- /dev/null +++ b/docs/installation/virtual/md-vmware.md @@ -0,0 +1,35 @@ +# 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 <span class="title-ref">install image</span>. + +:::{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..51e09857 --- /dev/null +++ b/docs/introducing/md-about.md @@ -0,0 +1,23 @@ +# 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..c97b59d4 --- /dev/null +++ b/docs/introducing/md-history.md @@ -0,0 +1,122 @@ +# History + +## In the beginning... + +There once was a network operating system based on Debian GNU/Linux, +called Vyatta.[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.[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".[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. + +[1] From the Sanskrit adjective "Vyātta" (व्यात्त), meaning opened. + +[2] A business model comparable to that of Redis, rather than that +of VyOS today. + +[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..102a00b9 --- /dev/null +++ b/docs/md-404.md @@ -0,0 +1,11 @@ +orphan + +# 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-cli.md b/docs/md-cli.md new file mode 100644 index 00000000..7a5af126 --- /dev/null +++ b/docs/md-cli.md @@ -0,0 +1,1178 @@ +# Command Line Interface + +The VyOS `CLI (Command-Line Interface)` comprises an operational and a +configuration mode. + +## Operational Mode + +Operational mode allows for commands to perform operational system tasks and +view system and service status, while configuration mode allows for the +modification of system configuration. + +The CLI provides a built-in help system. In the CLI the `?` key may be used +to display available commands. The `TAB` key can be used to auto-complete +commands and will present the help system upon a conflict or unknown value. + +For example typing `sh` followed by the `TAB` key will complete to +`show`. Pressing `TAB` a second time will display the possible +sub-commands of the `show` command. + +``` none +vyos@vyos:~$ s[tab] +set show +``` + +Example showing possible show commands: + +``` none +vyos@vyos:~$ show [tab] +Possible completions: + arp Show Address Resolution Protocol (ARP) information + bridge Show bridging information + cluster Show clustering information + configuration Show running configuration + conntrack Show conntrack entries in the conntrack table + conntrack-sync + Show connection syncing information + date Show system date and time + dhcp Show Dynamic Host Configuration Protocol (DHCP) information + dhcpv6 Show status related to DHCPv6 + disk Show status of disk device + dns Show Domain Name Server (DNS) information + file Show files for a particular image + firewall Show firewall information + flow-accounting + Show flow accounting statistics + hardware Show system hardware details + history show command history + host Show host information + incoming Show ethernet input-policy information +: q +``` + +You can scroll up with the keys `[Shift]+[PageUp]` and scroll down with +`[Shift]+[PageDown]`. + +When the output of a command results in more lines than can be displayed on the +terminal screen the output is paginated as indicated by a `:` prompt. + +When viewing in page mode the following commands are available: +- `q` key can be used to cancel output +- `space` will scroll down one page +- `b` will scroll back one page +- `return` will scroll down one line +- `up-arrow` and `down-arrow` will scroll up or down one line at a + time respectively +- `left-arrow` and `right-arrow` can be used to scroll left or right + in the event that the output has lines which exceed the terminal size. + +### Operational mode command families + +Many operational mode commands in VyOS are placed in families such as +`show`, `clear`, or `reset`. Every such family has a specific +meaning to allow the user to guess how the command is going to behave — +in particular, whether it will be disruptive to the system or not. + +Note that this convention was not always followed with perfect +consistency and some commands may still be in wrong families, so you +should always check the command help and documentation if you are not +sure what exactly it does. + +#### clear + +"Clear" commands are completely non-disruptive to any system operations. +Generally, they can be used freely without hesitation. + +Most often their purpose is to remove or reset various debug and +diagnostic information such as system logs and packet counters. + +Examples: + +- `clear console` — clears the screen. +- `clear interfaces ethernet eth0 counters` — zeroes packet counters + on `eth0`. +- `clear log` — deletes all system log entries. + +#### reset + +"Reset" commands can be locally-disruptive. They may, for example, +terminate a single user session or a session with a dynamic routing +protocol peer. + +They should be used with caution since they may have a significant +impact on a particular users in the network. + +- `reset pppoe-server username jsmith` — terminate all PPPoE sessions + from user `jsmith`. +- `reset bgp 192.0.2.54` — terminates the BGP session with neighbor + 192.0.2.54. +- `reset vpn ipsec site-to-site peer vpn.example.com` — terminates + IPsec tunnels to `vpn.example.com`. + +#### restart + +"Restart" operations may disrupt an entire subsystem. Most often they +initiate a restart of a server process, which causes it to be +unavailable for a brief period and resets all the process state. + +They should be used with extreme caution. + +- `restart dhcp server` — restarts the IPv4 DHCP server process (DHCP + requests are not served while it is restarting). +- `restart ipsec` — restarts the IPsec process (which forces all + sessions and all IPsec process state to reset). + +#### force + +"Force" commands force the system to perform an action that it might +perform by itself at a later point. + +Examples: + +- `force arp request interface eth1 address 10.3.0.2` — send a + gratuitious ARP request. +- `force root-partition-auto-resize` — grow the root filesystem to + the size of the system partition (this is also done on startup, but + this command can do it without a reboot). + +#### execute + +"Execute" commands are for executing various diagnostic and auxilliary +actions that the system would never perform by itself. + +Examples: + +- `execute wake-on-lan interface <intf> host <MAC>` — send a + Wake-On-LAN packet to a host. + +#### show + +"Show" commands display various system information. They may +occasionally use a pager for long outputs, that you can quit by pressing +the Q button. Their output is always finite, however. + +Examples: + +- `show system login` — displays current system users. +- `show ip route` — displays the IPv4 routing table. + +#### monitor + +"Monitor" commands initiate various monitoring operations that may +output information continuously, until terminated with `Ctrl-C` or +disabled. + +Examples: + +- `monitor log` — continuously outputs latest system logs. + +## Configuration Mode + +To enter configuration mode use the `configure` command: + +``` none +vyos@vyos:~$ configure +[edit] +vyos@vyos:~# +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Prompt changes from `$` to `#`. To exit configuration mode, +type `exit`. + +</div> + +``` none +vyos@vyos:~# exit +exit +vyos@vyos:~$ +``` + +See the configuration section of this document for more information on +configuration mode. + +# Configuration Overview + +VyOS makes use of a unified configuration file for the entire system's +configuration: `/config/config.boot`. This allows easy template +creation, backup, and replication of system configuration. A system can +thus also be easily cloned by simply copying the required configuration +files. + +## Terminology + +A VyOS system has three major types of configurations: + +- **Active** or **running configuration** is the system configuration + that is loaded and currently active (used by VyOS). Any change in + the configuration will have to be committed to belong to the + active/running configuration. +- **Working configuration** is the one that is currently being modified + in configuration mode. Changes made to the working configuration do + not go into effect until the changes are committed with the + `commit` command. At which time the working configuration will + become the active or running configuration. +- **Saved configuration** is the one saved to a file using the + `save` command. It allows you to keep safe a configuration for + future uses. There can be multiple configuration files. The default or + "boot" configuration is saved and loaded from the file + `/config/config.boot`. + +##### Seeing and navigating the configuration + +<div class="opcmd"> + +show configuration + +View the current active configuration, also known as the running +configuration, from the operational mode. + +``` none +vyos@vyos:~$ show configuration +interfaces { + ethernet eth0 { + address dhcp + hw-id 00:53:00:00:aa:01 + } + loopback lo { + } +} +service { + ssh { + port 22 + } +} +system { + config-management { + commit-revisions 20 + } + console { + device ttyS0 { + speed 9600 + } + } + login { + user vyos { + authentication { + encrypted-password **************** + } + level admin + } + } + ntp { + server 0.pool.ntp.org { + } + server 1.pool.ntp.org { + } + server 2.pool.ntp.org { + } + } + syslog { + global { + facility all { + level notice + } + facility protocols { + level debug + } + } + } +} +``` + +</div> + +By default, the configuration is displayed in a hierarchy like the above +example, this is only one of the possible ways to display the +configuration. When the configuration is generated and the device is +configured, changes are added through a collection of `set` and +`delete` commands. + +<div class="opcmd"> + +show configuration commands + +Get a collection of all the set commands required which led to the +running configuration. + +``` none +vyos@vyos:~$ show configuration commands +set interfaces ethernet eth0 address 'dhcp' +set interfaces ethernet eth0 hw-id '00:53:dd:44:3b:0f' +set interfaces loopback 'lo' +set service ssh port '22' +set system config-management commit-revisions '20' +set system console device ttyS0 speed '9600' +set system login user vyos authentication encrypted-password '$6$Vt68...QzF0' +set system login user vyos level 'admin' +set system ntp server '0.pool.ntp.org' +set system ntp server '1.pool.ntp.org' +set system ntp server '2.pool.ntp.org' +set system syslog global facility all level 'notice' +set system syslog global facility protocols level 'debug' +``` + +</div> + +Both these `show` commands should be executed when in operational +mode, they do not work directly in configuration mode. There is a +special way on how to `run_opmode_from_config_mode`. + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +Use the `show configuration commands | strip-private` +command when you want to hide private data. You may want to do so if +you want to share your configuration on the [forum](https://forum.vyos.io). + +</div> + +<div class="opcmd"> + +show configuration json + +View the current active configuration in JSON format. + +``` none +{"interfaces": {"ethernet": {"eth0": {"address": ["192.0.2.11/24", "192.0.2.35/24"], "hw-id": "52:54:00:48:a0:c6"}, "eth1": {"address": ["203.0.113.1/24"], "hw-id": "52:54:00:fc:50:0b"}}, "loopback": {"lo": {}}}, "protocols": {"static": {"route": {"0.0.0.0/0": {"next-hop": {"192.0.2.254": {}}}}}}, "service": {"ssh": {"disable-host-validation": {}}}, "system": {"config-management": {"commit-revisions": "100"}, "console": {"device": {"ttyS0": {"speed": "115200"}}}, "host-name": "r11-vyos", "login": {"user": {"vyos": {"authentication": {"encrypted-password": "$6$Vt68...F0", "plaintext-password": "", "public-keys": {"vyos@vyos": {"key": "AAAAxxx=", "type": "ssh-rsa"}}}}}}, "name-server": ["203.0.113.254"], "ntp": {"server": {"time1.vyos.net": {}, "time2.vyos.net": {}, "time3.vyos.net": {}}}, "syslog": {"global": {"facility": {"all": {"level": "info"}, "protocols": {"level": "debug"}}}}, "time-zone": "America/New_York"}} +``` + +</div> + +<div class="opcmd"> + +show configuration json pretty + +View the current active configuration in readable JSON format. + +``` none +{ + "interfaces": { + "ethernet": { + "eth0": { + "address": [ + "192.0.2.11/24", + "192.0.2.35/24" + ], + "hw-id": "52:54:00:48:a0:c6" + }, + "eth1": { + "address": [ + "203.0.113.1/24" + ], + "hw-id": "52:54:00:fc:50:0b" + } + }, + "loopback": { + "lo": {} + } + }, + "protocols": { + "static": { + "route": { + "0.0.0.0/0": { + "next-hop": { + "192.0.2.254": {} + } + } + } + } + }, + "service": { + "ssh": { + "disable-host-validation": {} + } + }, + "system": { + "config-management": { + "commit-revisions": "100" + }, + "console": { + "device": { + "ttyS0": { + "speed": "115200" + } + } + }, + "host-name": "r11-vyos", + "login": { + "user": { + "vyos": { + "authentication": { + "encrypted-password": "$6$Vt68...F0", + "plaintext-password": "", + "public-keys": { + "vyos@vyos": { + "key": "AAAAxxx=", + "type": "ssh-rsa" + } + } + } + } + } + }, + "name-server": [ + "203.0.113.254" + ], + "ntp": { + "server": { + "time1.vyos.net": {}, + "time2.vyos.net": {}, + "time3.vyos.net": {} + } + }, + "syslog": { + "global": { + "facility": { + "all": { + "level": "info" + }, + "protocols": { + "level": "debug" + } + } + } + }, + "time-zone": "America/New_York" + } +} +``` + +</div> + +###### The config mode + +When entering the configuration mode you are navigating inside a tree +structure, to enter configuration mode enter the command +`configure` when in operational mode. + +``` none +vyos@vyos$ configure +[edit] +vyos@vyos# +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +When going into configuration mode, prompt changes from +`$` to `#`. + +</div> + +All commands executed here are relative to the configuration level you +have entered. You can do everything from the top level, but commands +will be quite lengthy when manually typing them. + +The current hierarchy level can be changed by the `edit` +command. + +``` none +[edit] +vyos@vyos# edit interfaces ethernet eth0 + +[edit interfaces ethernet eth0] +vyos@vyos# +``` + +You are now in a sublevel relative to `interfaces ethernet eth0`, all +commands executed from this point on are relative to this sublevel. Use +either the `top` or `exit` command to go back to the top +of the hierarchy. You can also use the `up` command to move only +one level up at a time. + +<div class="cfgcmd"> + +show + +</div> + +The `show` command within configuration mode will show the +working configuration indicating line changes with `+` for additions, +`>` for replacements and `-` for deletions. + +**Example:** + +``` none +vyos@vyos:~$ configure +[edit] +vyos@vyos# show interfaces + ethernet eth0 { + description MY_OLD_DESCRIPTION + disable + hw-id 00:53:dd:44:3b:03 + } + loopback lo { + } +[edit] +vyos@vyos# set interfaces ethernet eth0 address dhcp +[edit] +vyos@vyos# set interfaces ethernet eth0 description MY_NEW_DESCRIPTION +[edit] +vyos@vyos# delete interfaces ethernet eth0 disable +[edit] +vyos@vyos# show interfaces + ethernet eth0 { ++ address dhcp +> description MY_NEW_DESCRIPTION +- disable + hw-id 00:53:dd:44:3b:03 + } + loopback lo { + } +``` + +It is also possible to display all `set` commands within configuration +mode using `show | commands` + +``` none +vyos@vyos# show interfaces ethernet eth0 | commands +set address dhcp +set hw-id 00:53:ad:44:3b:03 +``` + +These commands are also relative to the level you are inside and only +relevant configuration blocks will be displayed when entering a +sub-level. + +``` none +[edit interfaces ethernet eth0] +vyos@vyos# show + address dhcp + hw-id 00:53:ad:44:3b:03 +``` + +Exiting from the configuration mode is done via the `exit` +command from the top level, executing `exit` from within a +sub-level takes you back to the top level. + +``` none +[edit interfaces ethernet eth0] +vyos@vyos# exit +[edit] +vyos@vyos# exit +Warning: configuration changes have not been saved. +``` + +##### Editing the configuration + +The configuration can be edited by the use of `set` and +`delete` commands from within configuration mode. + +<div class="cfgcmd"> + +set + +Use this command to set the value of a parameter or to create a new +element. + +</div> + +Configuration commands are flattened from the tree into 'one-liner' +commands shown in `show configuration commands` from operation +mode. Commands are relative to the level where they are executed and all +redundant information from the current level is removed from the command +entered. + +``` none +[edit] +vyos@vyos# set interface ethernet eth0 address 192.0.2.100/24 +``` + +``` none +[edit interfaces ethernet eth0] +vyos@vyos# set address 203.0.113.6/24 +``` + +These two commands above are essentially the same, just executed from +different levels in the hierarchy. + +<div class="cfgcmd"> + +delete + +To delete a configuration entry use the `delete` command, +this also deletes all sub-levels under the current level you've +specified in the `delete` command. Deleting an entry will +also result in the element reverting back to its default value if one +exists. + +``` none +[edit interfaces ethernet eth0] +vyos@vyos# delete address 192.0.2.100/24 +``` + +</div> + +<div class="cfgcmd"> + +commit + +Any change you do on the configuration, will not take effect until +committed using the `commit` command in configuration mode. + +``` none +vyos@vyos# commit +[edit] +vyos@vyos# exit +Warning: configuration changes have not been saved. +vyos@vyos:~$ +``` + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +You can specify a commit message with +`commit comment <message>`. + +</div> + +<div id="save"> + +<div class="cfgcmd"> + +save + +Use this command to preserve configuration changes upon reboot. By +default it is stored at */config/config.boot*. In the case you want +to store the configuration file somewhere else, you can add a local +path, a SCP address, a FTP address or a TFTP address. + +``` none +vyos@vyos# save +Saving configuration to '/config/config.boot'... +Done +``` + +``` none +vyos@vyos# save [tab] +Possible completions: + <Enter> Save to system config file + <file> Save to file on local machine + scp://<user>:<passwd>@<host>:/<file> Save to file on remote machine + ftp://<user>:<passwd>@<host>/<file> Save to file on remote machine + tftp://<host>/<file> Save to file on remote machine +vyos@vyos# save tftp://192.168.0.100/vyos-test.config.boot +Saving configuration to 'tftp://192.168.0.100/vyos-test.config.boot'... +######################################################################## 100.0% +Done +``` + +</div> + +</div> + +<div class="cfgcmd"> + +exit \[discard\] + +Configuration mode can not be exited while uncommitted changes exist. +To exit configuration mode without applying changes, the +`exit discard` command must be used. + +All changes in the working config will thus be lost. + +``` none +vyos@vyos# exit +Cannot exit: configuration modified. +Use 'exit discard' to discard the changes and exit. +[edit] +vyos@vyos# exit discard +``` + +</div> + +<div class="cfgcmd"> + +commit-confirm \<minutes\> + +Use this command to temporarily commit your changes and set the +number of minutes available for validation. `confirm` must +be entered within those minutes, otherwise the system will reboot +into the previous configuration. The default value is 10 minutes. + +What if you are doing something dangerous? Suppose you want to setup +a firewall, and you are not sure there are no mistakes that will lock +you out of your system. You can use confirmed commit. If you issue +the `commit-confirm` command, your changes will be committed, and if +you don't issue the `confirm` command in 10 minutes, your +system will reboot into previous config revision. + +``` none +vyos@router# set firewall interface eth0 local name FromWorld +vyos@router# commit-confirm +commit confirm will be automatically reboot in 10 minutes unless confirmed +Proceed? [confirm]y +[edit] +vyos@router# confirm +[edit] +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +A reboot because you did not enter `confirm` will not +take you necessarily to the *saved configuration*, but to the +point before the unfortunate commit. + +</div> + +</div> + +<div class="cfgcmd"> + +copy + +Copy a configuration element. + +You can copy and remove configuration subtrees. Suppose you set up a +firewall ruleset `FromWorld` with one rule that allows traffic from +specific subnet. Now you want to setup a similar rule, but for +different subnet. Change your edit level to +`firewall name FromWorld` and use `copy rule 10 to rule 20`, then +modify rule 20. + +``` none +vyos@router# show firewall name FromWorld + default-action drop + rule 10 { + action accept + source { + address 203.0.113.0/24 + } + } +[edit] +vyos@router# edit firewall name FromWorld +[edit firewall name FromWorld] +vyos@router# copy rule 10 to rule 20 +[edit firewall name FromWorld] +vyos@router# set rule 20 source address 198.51.100.0/24 +[edit firewall name FromWorld] +vyos@router# commit +[edit firewall name FromWorld] +``` + +</div> + +<div class="cfgcmd"> + +rename + +Rename a configuration element. + +You can also rename config subtrees: + +``` none +vyos@router# rename rule 10 to rule 5 +[edit firewall name FromWorld] +vyos@router# commit +[edit firewall name FromWorld] +``` + +Note that `show` command respects your edit level and from this +level you can view the modified firewall ruleset with just `show` +with no parameters. + +``` none +vyos@router# show + default-action drop + rule 5 { + action accept + source { + address 203.0.113.0/24 + } + } + rule 20 { + action accept + source { + address 198.51.100.0/24 + } + } +``` + +</div> + +<div class="cfgcmd"> + +comment \<config node\> "comment text" + +Add comment as an annotation to a configuration node. + +The `comment` command allows you to insert a comment above the +`<config node>` configuration section. When shown, comments are +enclosed with `/*` and `*/` as open/close delimiters. Comments +need to be committed, just like other config changes. + +To remove an existing comment from your current configuration, +specify an empty string enclosed in double quote marks (`""`) as +the comment text. + +Example: + +``` none +vyos@vyos# comment firewall all-ping "Yes I know this VyOS is cool" +vyos@vyos# commit +vyos@vyos# show + firewall { + /* Yes I know this VyOS is cool */ + all-ping enable + broadcast-ping disable + ... + } +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +An important thing to note is that since the comment is +added on top of the section, it will not appear if the `show <section>` command is used. With the above example, the <span class="title-ref">show +firewall</span> command would return starting after the `firewall {` line, hiding the comment. + +</div> + +</div> + +##### Access opmode from config mode + +When inside configuration mode you are not directly able to execute +operational commands. + +<div class="cfgcmd"> + +run + +Access to these commands are possible through the use of the +`run [command]` command. From this command you will have access to +everything accessible from operational mode. + +Command completion and syntax help with `?` and `[tab]` will also +work. + +``` none +[edit] +vyos@vyos# run show interfaces +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +eth0 0.0.0.0/0 u/u +``` + +</div> + +##### Managing configurations + +VyOS comes with an integrated versioning system for the system +configuration. It automatically maintains a backup of every previous +configuration which has been committed to the system. The configurations +are versioned locally for rollback but they can also be stored on a +remote host for archiving/backup reasons. + +###### Local Archive + +Revisions are stored on disk. You can view, compare and rollback them to +any previous revisions if something goes wrong. + +<div class="opcmd"> + +show system commit + +View all existing revisions on the local system. + +``` none +vyos@vyos:~$ show system commit +0 2015-03-30 08:53:03 by vyos via cli +1 2015-03-30 08:52:20 by vyos via cli +2 2015-03-26 21:26:01 by root via boot-config-loader +3 2015-03-26 20:43:18 by root via boot-config-loader +4 2015-03-25 11:06:14 by root via boot-config-loader +5 2015-03-25 01:04:28 by root via boot-config-loader +6 2015-03-25 00:16:47 by vyos via cli +7 2015-03-24 23:43:45 by root via boot-config-loader +``` + +</div> + +<div class="cfgcmd"> + +set system config-management commit-revisions \<N\> + +You can specify the number of revisions stored on disk. N can be in +the range of 0 - 65535. When the number of revisions exceeds the +configured value, the oldest revision is removed. The default setting +for this value is to store 100 revisions locally. + +</div> + +###### Compare configurations + +VyOS lets you compare different configurations. + +<div class="cfgcmd"> + +compare \<saved | N\> \<M\> + +Use this command to spot what the differences are between different +configurations. + +``` none +vyos@vyos# compare [tab] +Possible completions: + <Enter> Compare working & active configurations + saved Compare working & saved configurations + <N> Compare working with revision N + <N> <M> Compare revision N with M + Revisions: + 0 2013-12-17 20:01:37 root by boot-config-loader + 1 2013-12-13 15:59:31 root by boot-config-loader + 2 2013-12-12 21:56:22 vyos by cli + 3 2013-12-12 21:55:11 vyos by cli + 4 2013-12-12 21:27:54 vyos by cli + 5 2013-12-12 21:23:29 vyos by cli + 6 2013-12-12 21:13:59 root by boot-config-loader + 7 2013-12-12 16:25:19 vyos by cli + 8 2013-12-12 15:44:36 vyos by cli + 9 2013-12-12 15:42:07 root by boot-config-loader + 10 2013-12-12 15:42:06 root by init +``` + +The command `compare` allows you to compare different type of +configurations. It also lets you compare different revisions through +the `compare N M` command, where N and M are revision +numbers. The output will describe how the configuration N is when +compared to M indicating with a plus sign (`+`) the additional +parts N has when compared to M, and indicating with a minus sign +(`-`) the lacking parts N misses when compared to M. + +``` none +vyos@vyos# compare 0 6 +[edit interfaces] ++dummy dum1 { ++ address 10.189.0.1/31 ++} +[edit interfaces ethernet eth0] ++vif 99 { ++ address 10.199.0.1/31 ++} +-vif 900 { +- address 192.0.2.4/24 +-} +``` + +</div> + +<div class="opcmd"> + +show system commit diff \<number\> + +Show commit revision difference. + +</div> + +The command above also lets you see the difference between two commits. +By default the difference with the running config is shown. + +``` none +vyos@router# run show system commit diff 4 +[edit system] ++ipv6 { ++ disable-forwarding ++} +``` + +This means four commits ago we did `set system ipv6 disable-forwarding`. + +###### Rollback Changes + +You can rollback configuration changes using the rollback command. This +will apply the selected revision and trigger a system reboot. + +<div class="cfgcmd"> + +rollback \<N\> + +Rollback to revision N (currently requires reboot) + +``` none +vyos@vyos# compare 1 +[edit system] +>host-name vyos-1 +[edit] + +vyos@vyos# rollback 1 +Proceed with reboot? [confirm][y] +Broadcast message from root@vyos-1 (pts/0) (Tue Dec 17 21:07:45 2013): +The system is going down for reboot NOW! +``` + +</div> + +###### Remote Archive + +VyOS can upload the configuration to a remote location after each call +to `commit`. You will have to set the commit-archive location. +TFTP, FTP, SCP and SFTP servers are supported. Every time a +`commit` is successful the `config.boot` file will be copied +to the defined destination(s). The filename used on the remote host will +be `config.boot-hostname.YYYYMMDD_HHMMSS`. + +<div class="cfgcmd"> + +set system config-management commit-archive location \<URI\> + +Specify remote location of commit archive as any of the below +`URI (Uniform Resource Identifier)` + +- `http://<user>:<passwd>@<host>:/<dir>` +- `https://<user>:<passwd>@<host>:/<dir>` +- `ftp://<user>:<passwd>@<host>/<dir>` +- `sftp://<user>:<passwd>@<host>/<dir>` +- `scp://<user>:<passwd>@<host>:/<dir>` +- `tftp://<host>/<dir>` +- `git+https://<user>:<passwd>@<host>/<path>` + +Since username and password are part of the URI, they need to be +properly url encoded if containing special characters. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The number of revisions don't affect the commit-archive. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +When using Git as destination for the commit archive the +`source-address` CLI option has no effect. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +You may find VyOS not allowing the secure connection because +it cannot verify the legitimacy of the remote server. You can use +the workaround below to quickly add the remote host's SSH +fingerprint to your `~/.ssh/known_hosts` file: + +</div> + +``` none +vyos@vyos# ssh-keyscan <host> >> ~/.ssh/known_hosts +``` + +</div> + +###### Saving and loading manually + +You can use the `save` and `load` commands if you want to manually +manage specific configuration files. + +When using the [save](#save) command, you can add a specific location where +to store your configuration file. And, when needed it, you will be able +to load it with the `load` command: + +<div class="cfgcmd"> + +load \<URI\> + +Use this command to load a configuration which will replace the +running configuration. Define the location of the configuration file +to be loaded. You can use a path to a local file, an SCP address, an +SFTP address, an FTP address, an HTTP address, an HTTPS address or a +TFTP address. + +``` none +vyos@vyos# load +Possible completions: + <Enter> Load from system config file + <file> Load from file on local machine + scp://<user>:<passwd>@<host>:/<file> Load from file on remote machine + sftp://<user>:<passwd>@<host>/<file> Load from file on remote machine + ftp://<user>:<passwd>@<host>/<file> Load from file on remote machine + http://<host>/<file> Load from file on remote machine + https://<host>/<file> Load from file on remote machine + tftp://<host>/<file> Load from file on remote machine +``` + +</div> + +###### Restore Default + +In the case you want to completely delete your configuration and restore +the default one, you can enter the following command in configuration +mode: + +``` none +load /opt/vyatta/etc/config.boot.default +``` + +You will be asked if you want to continue. If you accept, you will have +to use `commit` if you want to make the changes active. + +Then you may want to `save` in order to delete the saved +configuration too. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you are remotely connected, you will lose your connection. +You may want to copy first the config, edit it to ensure +connectivity, and load the edited config. + +</div> diff --git a/docs/md-coverage.md b/docs/md-coverage.md new file mode 100644 index 00000000..370f35ce --- /dev/null +++ b/docs/md-coverage.md @@ -0,0 +1,51 @@ +# 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 + +<div class="cfgcmdlist" show-coverage=""> + +</div> + +## Operational Commands + +<div class="opcmdlist" show-coverage=""> + +</div> diff --git a/docs/md-documentation.md b/docs/md-documentation.md new file mode 100644 index 00000000..4603a49b --- /dev/null +++ b/docs/md-documentation.md @@ -0,0 +1,430 @@ +lastproofread +2021-06-25 + +# 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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +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](https://github.com/vyos/vyos-documentation/blob/master/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](https://github.com/vyos/vyos-documentation/blob/master/docker/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 `/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](https://www.grammarly.com/). +- 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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Updates to our documentation should be delivered by a GitHub +pull-request. This requires you already have a GitHub account. + +</div> + +- 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 + (`prepare_commit`). This mainly applies to proper commit messages + describing your change (how and why). Please check out the documentation of + [Sphinx-doc](https://www.sphinx-doc.org) or [reStructuredText](http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html) 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](https://docutils.sourceforge.io/docs/ref/rst/directives.html). + +- 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](https://github.com/vyos/vyos-documentation/blob/master/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 (`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 <span class="title-ref">upstream</span> 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 (`5737`, `3849`, `5389` and +`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 +`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 `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. diff --git a/docs/md-index.md b/docs/md-index.md new file mode 100644 index 00000000..cc2067b3 --- /dev/null +++ b/docs/md-index.md @@ -0,0 +1,110 @@ +# VyOS User Guide + +<div class="grid" gutter="2"> + +3 + +<div class="grid-item-card"> + +Get / Build VyOS + +Quickly `Build<contributing/build-vyos:build vyos>` your own Image or take a look at how to `download<installation/install:download>` a free or supported version. + +</div> + +<div class="grid-item-card"> + +Install VyOS + +Read about how to install VyOS on `Bare Metal<installation/install:installation>` or in a +`Virtual Environment<installation/virtual/index:running vyos in virtual environments>` and +how to use an image with the usual `cloud<installation/cloud/index:running VyOS in Cloud Environments>` providers + +</div> + +<div class="grid-item-card"> + +Configuration and Operation + +Use the `Quickstart Guide<quick-start:Quick Start>`, to have a fast overview. Or go deeper and +set up `advanced routing<configuration/protocols/index:protocols>`, +`VRFs<configuration/vrf/index:vrf>`, or +`VPNs<configuration/vpn/index:vpn>` for example. + +</div> + +<div class="grid-item-card"> + +Automate + +Integrate VyOS in your automation Workflow with +`Ansible<vyos-ansible>`, +have your own `local scripts<command-scripting>`, or configure VyOS with the `HTTPS-API<vyosapi>`. + +</div> + +<div class="grid-item-card"> + +Examples + +Get some inspiration from the `Configuration Blueprints<configexamples/index:Configuration Blueprints>` +to build your infrastructure. + +</div> + +<div class="grid-item-card"> + +Contribute and Community + +There are many ways to contribute to the project.\ +Add missing parts or improve the `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 `code<contributing/development:development>`. + +</div> + +</div> + +<div class="toctree" hidden="" maxdepth="1"> + +introducing/about +introducing/history + +</div> + +<div class="toctree" maxdepth="2" hidden="" caption="First Steps"> + +installation/index +quick-start +cli + +</div> + +<div class="toctree" maxdepth="2" hidden="" caption="Adminguide"> + +configuration/index +operation/index +automation/index +troubleshooting/index +configexamples/index + +</div> + +<div class="toctree" maxdepth="2" hidden="" caption="Development"> + +contributing/build-vyos +contributing/development +contributing/issues-features +contributing/upstream-packages +contributing/debugging +contributing/testing + +</div> + +<div class="toctree" maxdepth="2" hidden="" caption="Misc"> + +documentation +coverage +copyright + +</div> diff --git a/docs/md-quick-start.md b/docs/md-quick-start.md new file mode 100644 index 00000000..36140bc5 --- /dev/null +++ b/docs/md-quick-start.md @@ -0,0 +1,362 @@ +# 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 `nat` gateway for a device with two network interfaces +(`eth0` and `eth1`). + +## 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 `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 `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 `ssh` chapter on how to listen +on specific addresses only. + +``` none +set service ssh port '22' +``` + +## 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 `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 `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 +`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..73a8f62f --- /dev/null +++ b/docs/operation/md-boot-options.md @@ -0,0 +1,56 @@ +# Boot Options + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +This function may be highly disruptive. +It may cause major service interruption, so make sure you really +need it and verify your input carefully. + +</div> + +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. + +<img src="/_static/images/boot-options.webp" class="align-center" style="width:80.0%" alt="image" /> + +## 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 +`boot process <boot-steps>` well before using them! + +<div class="glossary"> + +no-vyos-migrate +Do not perform config migration. + +no-vyos-firewall +Do not initialize default firewall chains, renders any firewall +configuration unusable. + +</div> diff --git a/docs/operation/md-index.md b/docs/operation/md-index.md new file mode 100644 index 00000000..eed21dcd --- /dev/null +++ b/docs/operation/md-index.md @@ -0,0 +1,10 @@ +# Operation Mode + +<div class="toctree" maxdepth="1" includehidden=""> + +information +boot-options +password-recovery +raid + +</div> diff --git a/docs/operation/md-information.md b/docs/operation/md-information.md new file mode 100644 index 00000000..c6f663a5 --- /dev/null +++ b/docs/operation/md-information.md @@ -0,0 +1,171 @@ +lastproofread +2021-07-07 + +# Information + +VyOS features a rich set of operational level commands to retrieve arbitrary +information about your running system. + +## Hardware + +### 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 `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>. + +<div class="opcmd"> + +show hardware usb + +Retrieve a tree like representation of all connected USB devices. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If a device is unplugged and re-plugged it will receive a new +Port, Dev, If identification. + +</div> + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show hardware usb serial + +Retrieve a list and description of all connected USB serial devices. The +device name displayed, e.g. <span class="title-ref">usb0b2.4p1.0</span> can be directly used when accessing +the serial console as console-server device. + +``` 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 +``` + +</div> + +## Version + +<div class="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. + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show version kernel + +Return version number of the Linux Kernel used in this release. + +``` none +vyos@vyos:~$ show version kernel +5.10.46-amd64-vyos +``` + +</div> + +<div class="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. + +> ``` none +> vyos@vyos:~$ show version frr +> FRRouting 7.5.1-20210625-00-gf07d935a2 (vyos). +> Copyright 1996-2005 Kunihiro Ishiguro, et al. +> ``` + +</div> diff --git a/docs/operation/md-password-recovery.md b/docs/operation/md-password-recovery.md new file mode 100644 index 00000000..295de05c --- /dev/null +++ b/docs/operation/md-password-recovery.md @@ -0,0 +1,22 @@ +# 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> +<img src="/_static/images/password-recovery-01.webp" width="600" /> +</figure> + +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..2009779d --- /dev/null +++ b/docs/operation/md-raid.md @@ -0,0 +1,265 @@ +# 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 + +## 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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Before a permanent installation, VyOS runs a live installation + +</div> + +## 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: + +<div class="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). + +</div> + +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: + +<div class="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). + +</div> + +5-Add the replacement disk to the RAID 1 set by issuing the following command: + +<div class="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). + +</div> + +## Operation + +This part introduces how to add a disk partition to a RAID-1 set initiates +mirror synchronization, check and display information. + +<div class="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. + +</div> + +<div class="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). + +</div> + +<div class="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. + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show raid \<RAID‐1‐device\> + +Use this command to display the formatting of a hard disk. + +``` 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 +``` + +</div> diff --git a/docs/troubleshooting/md-index.md b/docs/troubleshooting/md-index.md new file mode 100644 index 00000000..f3756c26 --- /dev/null +++ b/docs/troubleshooting/md-index.md @@ -0,0 +1,436 @@ +# 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 <span class="title-ref">ping</span> and <span class="title-ref">traceroute</span> +commands. The options for each are shown (the options for each command were +displayed using the built-in help as described in the `cli` +section and are omitted from the output here): + +<div class="opcmd"> + +ping \<destination\> + +Send ICMP echo requests to destination host. There are multiple options to +ping, inkl. VRF support. + +``` 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 +``` + +</div> + +<div class="opcmd"> + +traceroute \<destination\> + +Trace path to target. + +``` 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> +``` + +</div> + +### Advanced Connectivity Tests + +<div class="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: + +``` 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 +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The output consumes the screen and will replace your command +prompt. + +</div> + +Several options are available for changing the display output. Press <span class="title-ref">h</span> to +invoke the built in help system. To quit, just press <span class="title-ref">q</span> and you'll be +returned to the VyOS command prompt. + +</div> + +### IPv6 Topology Discovery + +IPv6 uses different techniques to discover its Neighbors/topology. + +#### Router Discovery + +<div class="opcmd"> + +force ipv6-rd interface \<interface\> \[address \<ipv6-address\>\] + +Discover routers via eth0. + +Example: + +``` 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 +``` + +</div> + +#### Neighbor Discovery + +<div class="opcmd"> + +force ipv6-nd interface \<interface\> address \<ipv6-address\> + +Example: + +``` 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 +``` + +</div> + +## 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 `monitor traffic interface <name>` +command, replacing <span class="title-ref">\<name\></span> 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 <span class="title-ref">Ctrl-c</span> 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 + +VyOS 1.2 uses [Debian Jessie](https://www.debian.org/releases/jessie/) as the base Linux operating system. Jessie was +the first version of Debian that uses [systemd](https://freedesktop.org/wiki/Software/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](https://github.com/vyos/vyatta-cfg) + Debian package + +> 1. Starts [FRR](https://frrouting.org/) - successor to [GNU Zebra](https://www.gnu.org/software/zebra/) and [Quagga](https://www.quagga.net/) +> 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` +> +> 9. 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` |
