diff options
| author | Daniil Baturin <daniil@vyos.io> | 2026-05-06 14:09:07 +0100 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2026-05-06 14:09:07 +0100 |
| commit | e066bb43eab070c58043f69efe87191b354b01e5 (patch) | |
| tree | a390c8fddb08a163feef6710818c10ffdc553733 /docs | |
| parent | 22e34ce5aee24d2fd11f8205522ab7ecdb3c4c5e (diff) | |
| download | vyos-documentation-e066bb43eab070c58043f69efe87191b354b01e5.tar.gz vyos-documentation-e066bb43eab070c58043f69efe87191b354b01e5.zip | |
Revert "Add incremental RST-to-MyST swap mechanism (sagitta) (#1868)" (#1894)
This reverts commit 22e34ce5aee24d2fd11f8205522ab7ecdb3c4c5e.
Diffstat (limited to 'docs')
446 files changed, 14 insertions, 64759 deletions
diff --git a/docs/Makefile b/docs/Makefile index b0068b1a..cb6226af 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -12,43 +12,22 @@ 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 swap restore html dirhtml pdf livehtml defaultvalue - -swap: - $(SWAP) --swap - -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: html +.PHONY: help Makefile # 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) + +livehtml: + sphinx-autobuild --host $(AUTOHOST) --port $(AUTOPORT) $(AUTOOPTS) \ + "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + + +defaultvalue: export VYOS_DEFAULT=True +defaultvalue: + @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file diff --git a/docs/_ext/vyos.py b/docs/_ext/vyos.py index ac5b8159..c1a96cd9 100644 --- a/docs/_ext/vyos.py +++ b/docs/_ext/vyos.py @@ -364,18 +364,8 @@ class CmdInclude(SphinxDirective): line = re.sub('{{\s?var' + str(i) + '\s?}}',value,line) new_include_lines.append(line) - 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 + self.state._renderer.nested_render_text(''.join(new_include_lines), self.lineno) + return [] class CfgcmdlistDirective(Directive): diff --git a/docs/_static/images/1u_vyos_back.webp b/docs/_static/images/1u_vyos_back.webp Binary files differdeleted file mode 100644 index b0dbab1d..00000000 --- a/docs/_static/images/1u_vyos_back.webp +++ /dev/null diff --git a/docs/_static/images/1u_vyos_front.webp b/docs/_static/images/1u_vyos_front.webp Binary files differdeleted file mode 100644 index a47e4f9e..00000000 --- a/docs/_static/images/1u_vyos_front.webp +++ /dev/null diff --git a/docs/_static/images/1u_vyos_front_10ge_open_1.webp b/docs/_static/images/1u_vyos_front_10ge_open_1.webp Binary files differdeleted file mode 100644 index 87f53ddd..00000000 --- a/docs/_static/images/1u_vyos_front_10ge_open_1.webp +++ /dev/null diff --git a/docs/_static/images/1u_vyos_front_10ge_open_2.webp b/docs/_static/images/1u_vyos_front_10ge_open_2.webp Binary files differdeleted file mode 100644 index 1fe5d4ca..00000000 --- a/docs/_static/images/1u_vyos_front_10ge_open_2.webp +++ /dev/null diff --git a/docs/_static/images/1u_vyos_front_10ge_open_3.webp b/docs/_static/images/1u_vyos_front_10ge_open_3.webp Binary files differdeleted file mode 100644 index 2200b448..00000000 --- a/docs/_static/images/1u_vyos_front_10ge_open_3.webp +++ /dev/null diff --git a/docs/_static/images/1u_vyos_front_10ge_open_4.webp b/docs/_static/images/1u_vyos_front_10ge_open_4.webp Binary files differdeleted file mode 100644 index fd4a43c7..00000000 --- a/docs/_static/images/1u_vyos_front_10ge_open_4.webp +++ /dev/null diff --git a/docs/_static/images/1u_vyos_front_open_1.webp b/docs/_static/images/1u_vyos_front_open_1.webp Binary files differdeleted file mode 100644 index 00006feb..00000000 --- a/docs/_static/images/1u_vyos_front_open_1.webp +++ /dev/null diff --git a/docs/_static/images/1u_vyos_front_open_2.webp b/docs/_static/images/1u_vyos_front_open_2.webp Binary files differdeleted file mode 100644 index ad6fa807..00000000 --- a/docs/_static/images/1u_vyos_front_open_2.webp +++ /dev/null diff --git a/docs/_static/images/1u_vyos_front_open_3.webp b/docs/_static/images/1u_vyos_front_open_3.webp Binary files differdeleted file mode 100644 index 15edf863..00000000 --- a/docs/_static/images/1u_vyos_front_open_3.webp +++ /dev/null diff --git a/docs/_static/images/480px-Acrosser_ANDJ190N1_Back.webp b/docs/_static/images/480px-Acrosser_ANDJ190N1_Back.webp Binary files differdeleted file mode 100644 index 10c350cc..00000000 --- a/docs/_static/images/480px-Acrosser_ANDJ190N1_Back.webp +++ /dev/null diff --git a/docs/_static/images/480px-Acrosser_ANDJ190N1_Front.webp b/docs/_static/images/480px-Acrosser_ANDJ190N1_Front.webp Binary files differdeleted file mode 100644 index 0ea695d4..00000000 --- a/docs/_static/images/480px-Acrosser_ANDJ190N1_Front.webp +++ /dev/null diff --git a/docs/_static/images/600px-Partaker-i5.webp b/docs/_static/images/600px-Partaker-i5.webp Binary files differdeleted file mode 100644 index d68d5afa..00000000 --- a/docs/_static/images/600px-Partaker-i5.webp +++ /dev/null diff --git a/docs/_static/images/ESP_AH.webp b/docs/_static/images/ESP_AH.webp Binary files differdeleted file mode 100644 index 1c70082e..00000000 --- a/docs/_static/images/ESP_AH.webp +++ /dev/null diff --git a/docs/_static/images/IPSec_close_action_settings.webp b/docs/_static/images/IPSec_close_action_settings.webp Binary files differdeleted file mode 100644 index 6510ba7c..00000000 --- a/docs/_static/images/IPSec_close_action_settings.webp +++ /dev/null diff --git a/docs/_static/images/L3VPN_hub_and_spoke.webp b/docs/_static/images/L3VPN_hub_and_spoke.webp Binary files differdeleted file mode 100644 index 2f3cafcd..00000000 --- a/docs/_static/images/L3VPN_hub_and_spoke.webp +++ /dev/null diff --git a/docs/_static/images/PA-ESP-group.webp b/docs/_static/images/PA-ESP-group.webp Binary files differdeleted file mode 100644 index 1802c511..00000000 --- a/docs/_static/images/PA-ESP-group.webp +++ /dev/null diff --git a/docs/_static/images/PA-IKE-GW-1.webp b/docs/_static/images/PA-IKE-GW-1.webp Binary files differdeleted file mode 100644 index ce0a123d..00000000 --- a/docs/_static/images/PA-IKE-GW-1.webp +++ /dev/null diff --git a/docs/_static/images/PA-IKE-GW-2.webp b/docs/_static/images/PA-IKE-GW-2.webp Binary files differdeleted file mode 100644 index 5facbc1e..00000000 --- a/docs/_static/images/PA-IKE-GW-2.webp +++ /dev/null diff --git a/docs/_static/images/PA-IKE-group.webp b/docs/_static/images/PA-IKE-group.webp Binary files differdeleted file mode 100644 index f244a3fa..00000000 --- a/docs/_static/images/PA-IKE-group.webp +++ /dev/null diff --git a/docs/_static/images/PA-IPsec-tunnel.webp b/docs/_static/images/PA-IPsec-tunnel.webp Binary files differdeleted file mode 100644 index f8aac9b8..00000000 --- a/docs/_static/images/PA-IPsec-tunnel.webp +++ /dev/null diff --git a/docs/_static/images/PA-tunnel-1.webp b/docs/_static/images/PA-tunnel-1.webp Binary files differdeleted file mode 100644 index b72c9364..00000000 --- a/docs/_static/images/PA-tunnel-1.webp +++ /dev/null diff --git a/docs/_static/images/PA-tunnel-2.webp b/docs/_static/images/PA-tunnel-2.webp Binary files differdeleted file mode 100644 index 8b1bfbf8..00000000 --- a/docs/_static/images/PA-tunnel-2.webp +++ /dev/null diff --git a/docs/_static/images/PA-tunnel-3.webp b/docs/_static/images/PA-tunnel-3.webp Binary files differdeleted file mode 100644 index 098c3c4d..00000000 --- a/docs/_static/images/PA-tunnel-3.webp +++ /dev/null diff --git a/docs/_static/images/Wan_load_balancing1.webp b/docs/_static/images/Wan_load_balancing1.webp Binary files differdeleted file mode 100644 index 7efb6ab7..00000000 --- a/docs/_static/images/Wan_load_balancing1.webp +++ /dev/null diff --git a/docs/_static/images/Wan_load_balancing_exclude1.webp b/docs/_static/images/Wan_load_balancing_exclude1.webp Binary files differdeleted file mode 100644 index cc5fc4d1..00000000 --- a/docs/_static/images/Wan_load_balancing_exclude1.webp +++ /dev/null diff --git a/docs/_static/images/apu4_desk_1.webp b/docs/_static/images/apu4_desk_1.webp Binary files differdeleted file mode 100644 index 8298c3f2..00000000 --- a/docs/_static/images/apu4_desk_1.webp +++ /dev/null diff --git a/docs/_static/images/apu4_desk_2.webp b/docs/_static/images/apu4_desk_2.webp Binary files differdeleted file mode 100644 index ccf54bb8..00000000 --- a/docs/_static/images/apu4_desk_2.webp +++ /dev/null diff --git a/docs/_static/images/apu4_desk_3.webp b/docs/_static/images/apu4_desk_3.webp Binary files differdeleted file mode 100644 index 965ff112..00000000 --- a/docs/_static/images/apu4_desk_3.webp +++ /dev/null diff --git a/docs/_static/images/apu4_desk_4.webp b/docs/_static/images/apu4_desk_4.webp Binary files differdeleted file mode 100644 index 2cbc2bd3..00000000 --- a/docs/_static/images/apu4_desk_4.webp +++ /dev/null diff --git a/docs/_static/images/apu4_rack_1.webp b/docs/_static/images/apu4_rack_1.webp Binary files differdeleted file mode 100644 index c6bd9229..00000000 --- a/docs/_static/images/apu4_rack_1.webp +++ /dev/null diff --git a/docs/_static/images/apu4_rack_2.webp b/docs/_static/images/apu4_rack_2.webp Binary files differdeleted file mode 100644 index f2673488..00000000 --- a/docs/_static/images/apu4_rack_2.webp +++ /dev/null diff --git a/docs/_static/images/apu4_rack_3.webp b/docs/_static/images/apu4_rack_3.webp Binary files differdeleted file mode 100644 index a12e7895..00000000 --- a/docs/_static/images/apu4_rack_3.webp +++ /dev/null diff --git a/docs/_static/images/apu4_rack_4.webp b/docs/_static/images/apu4_rack_4.webp Binary files differdeleted file mode 100644 index a3ea439c..00000000 --- a/docs/_static/images/apu4_rack_4.webp +++ /dev/null diff --git a/docs/_static/images/apu4_rack_5.webp b/docs/_static/images/apu4_rack_5.webp Binary files differdeleted file mode 100644 index 8310600e..00000000 --- a/docs/_static/images/apu4_rack_5.webp +++ /dev/null diff --git a/docs/_static/images/apu4_rack_vyos_print.webp b/docs/_static/images/apu4_rack_vyos_print.webp Binary files differdeleted file mode 100644 index 61b14f3f..00000000 --- a/docs/_static/images/apu4_rack_vyos_print.webp +++ /dev/null diff --git a/docs/_static/images/aws.webp b/docs/_static/images/aws.webp Binary files differdeleted file mode 100644 index 29fe0684..00000000 --- a/docs/_static/images/aws.webp +++ /dev/null diff --git a/docs/_static/images/blueprint-dmvpn.webp b/docs/_static/images/blueprint-dmvpn.webp Binary files differdeleted file mode 100644 index 8a3c38aa..00000000 --- a/docs/_static/images/blueprint-dmvpn.webp +++ /dev/null diff --git a/docs/_static/images/boot-options.webp b/docs/_static/images/boot-options.webp Binary files differdeleted file mode 100644 index 9616a336..00000000 --- a/docs/_static/images/boot-options.webp +++ /dev/null diff --git a/docs/_static/images/cisco-vpn-ipsec.webp b/docs/_static/images/cisco-vpn-ipsec.webp Binary files differdeleted file mode 100644 index 45c570f0..00000000 --- a/docs/_static/images/cisco-vpn-ipsec.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-eip-01.webp b/docs/_static/images/cloud-aws-eip-01.webp Binary files differdeleted file mode 100644 index a78758fd..00000000 --- a/docs/_static/images/cloud-aws-eip-01.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-eip-02.webp b/docs/_static/images/cloud-aws-eip-02.webp Binary files differdeleted file mode 100644 index 39c5c7b7..00000000 --- a/docs/_static/images/cloud-aws-eip-02.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-eni-01.webp b/docs/_static/images/cloud-aws-eni-01.webp Binary files differdeleted file mode 100644 index 51212929..00000000 --- a/docs/_static/images/cloud-aws-eni-01.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-eni-02.webp b/docs/_static/images/cloud-aws-eni-02.webp Binary files differdeleted file mode 100644 index 139313f6..00000000 --- a/docs/_static/images/cloud-aws-eni-02.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-ha-architecture.webp b/docs/_static/images/cloud-aws-ha-architecture.webp Binary files differdeleted file mode 100644 index 3021a6e0..00000000 --- a/docs/_static/images/cloud-aws-ha-architecture.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-igw-01.webp b/docs/_static/images/cloud-aws-igw-01.webp Binary files differdeleted file mode 100644 index 21a90f32..00000000 --- a/docs/_static/images/cloud-aws-igw-01.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-igw-02.webp b/docs/_static/images/cloud-aws-igw-02.webp Binary files differdeleted file mode 100644 index 7f43c4be..00000000 --- a/docs/_static/images/cloud-aws-igw-02.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-keypair-01.webp b/docs/_static/images/cloud-aws-keypair-01.webp Binary files differdeleted file mode 100644 index fdeff52c..00000000 --- a/docs/_static/images/cloud-aws-keypair-01.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-keypair-02.webp b/docs/_static/images/cloud-aws-keypair-02.webp Binary files differdeleted file mode 100644 index 89fac0f8..00000000 --- a/docs/_static/images/cloud-aws-keypair-02.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-keypair-03.webp b/docs/_static/images/cloud-aws-keypair-03.webp Binary files differdeleted file mode 100644 index c71c105c..00000000 --- a/docs/_static/images/cloud-aws-keypair-03.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-keypair-04.webp b/docs/_static/images/cloud-aws-keypair-04.webp Binary files differdeleted file mode 100644 index bcacb96e..00000000 --- a/docs/_static/images/cloud-aws-keypair-04.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-route-01.webp b/docs/_static/images/cloud-aws-route-01.webp Binary files differdeleted file mode 100644 index 5adda05a..00000000 --- a/docs/_static/images/cloud-aws-route-01.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-route-02.webp b/docs/_static/images/cloud-aws-route-02.webp Binary files differdeleted file mode 100644 index 7e670263..00000000 --- a/docs/_static/images/cloud-aws-route-02.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-route-03.webp b/docs/_static/images/cloud-aws-route-03.webp Binary files differdeleted file mode 100644 index 4b643b0d..00000000 --- a/docs/_static/images/cloud-aws-route-03.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-route-04.webp b/docs/_static/images/cloud-aws-route-04.webp Binary files differdeleted file mode 100644 index 1b67de77..00000000 --- a/docs/_static/images/cloud-aws-route-04.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-sg-01.webp b/docs/_static/images/cloud-aws-sg-01.webp Binary files differdeleted file mode 100644 index 9cf13f7b..00000000 --- a/docs/_static/images/cloud-aws-sg-01.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-sg-02.webp b/docs/_static/images/cloud-aws-sg-02.webp Binary files differdeleted file mode 100644 index 5b00ed91..00000000 --- a/docs/_static/images/cloud-aws-sg-02.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-sg-03.webp b/docs/_static/images/cloud-aws-sg-03.webp Binary files differdeleted file mode 100644 index 9cc462d6..00000000 --- a/docs/_static/images/cloud-aws-sg-03.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-sg-04.webp b/docs/_static/images/cloud-aws-sg-04.webp Binary files differdeleted file mode 100644 index 5577d2e6..00000000 --- a/docs/_static/images/cloud-aws-sg-04.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-sg-05.webp b/docs/_static/images/cloud-aws-sg-05.webp Binary files differdeleted file mode 100644 index 6bc4e12d..00000000 --- a/docs/_static/images/cloud-aws-sg-05.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-subnet-01.webp b/docs/_static/images/cloud-aws-subnet-01.webp Binary files differdeleted file mode 100644 index ab3ded81..00000000 --- a/docs/_static/images/cloud-aws-subnet-01.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-subnet-02.webp b/docs/_static/images/cloud-aws-subnet-02.webp Binary files differdeleted file mode 100644 index 8d28906f..00000000 --- a/docs/_static/images/cloud-aws-subnet-02.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-subnet-03.webp b/docs/_static/images/cloud-aws-subnet-03.webp Binary files differdeleted file mode 100644 index 0f1f14c9..00000000 --- a/docs/_static/images/cloud-aws-subnet-03.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-to-azure.webp b/docs/_static/images/cloud-aws-to-azure.webp Binary files differdeleted file mode 100644 index 535dfac9..00000000 --- a/docs/_static/images/cloud-aws-to-azure.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-vpc-01.webp b/docs/_static/images/cloud-aws-vpc-01.webp Binary files differdeleted file mode 100644 index 2b1ad120..00000000 --- a/docs/_static/images/cloud-aws-vpc-01.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-vpc-02.webp b/docs/_static/images/cloud-aws-vpc-02.webp Binary files differdeleted file mode 100644 index 78bd25e9..00000000 --- a/docs/_static/images/cloud-aws-vpc-02.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-vpc-03.webp b/docs/_static/images/cloud-aws-vpc-03.webp Binary files differdeleted file mode 100644 index 101a1924..00000000 --- a/docs/_static/images/cloud-aws-vpc-03.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-vyos-01.webp b/docs/_static/images/cloud-aws-vyos-01.webp Binary files differdeleted file mode 100644 index 4f594b16..00000000 --- a/docs/_static/images/cloud-aws-vyos-01.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-vyos-02.webp b/docs/_static/images/cloud-aws-vyos-02.webp Binary files differdeleted file mode 100644 index 70e37e49..00000000 --- a/docs/_static/images/cloud-aws-vyos-02.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-vyos-03.webp b/docs/_static/images/cloud-aws-vyos-03.webp Binary files differdeleted file mode 100644 index f526c28a..00000000 --- a/docs/_static/images/cloud-aws-vyos-03.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-vyos-04.webp b/docs/_static/images/cloud-aws-vyos-04.webp Binary files differdeleted file mode 100644 index a18e5aee..00000000 --- a/docs/_static/images/cloud-aws-vyos-04.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-vyos-05.webp b/docs/_static/images/cloud-aws-vyos-05.webp Binary files differdeleted file mode 100644 index f7699fe3..00000000 --- a/docs/_static/images/cloud-aws-vyos-05.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-vyos-06.webp b/docs/_static/images/cloud-aws-vyos-06.webp Binary files differdeleted file mode 100644 index 06e771d6..00000000 --- a/docs/_static/images/cloud-aws-vyos-06.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-vyos-07.webp b/docs/_static/images/cloud-aws-vyos-07.webp Binary files differdeleted file mode 100644 index 6b5efedc..00000000 --- a/docs/_static/images/cloud-aws-vyos-07.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-vyos-08.webp b/docs/_static/images/cloud-aws-vyos-08.webp Binary files differdeleted file mode 100644 index 3b6aa12b..00000000 --- a/docs/_static/images/cloud-aws-vyos-08.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-vyos-09.webp b/docs/_static/images/cloud-aws-vyos-09.webp Binary files differdeleted file mode 100644 index 06e771d6..00000000 --- a/docs/_static/images/cloud-aws-vyos-09.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-vyos-10.webp b/docs/_static/images/cloud-aws-vyos-10.webp Binary files differdeleted file mode 100644 index 772d8e80..00000000 --- a/docs/_static/images/cloud-aws-vyos-10.webp +++ /dev/null diff --git a/docs/_static/images/cloud-aws-vyos-11.webp b/docs/_static/images/cloud-aws-vyos-11.webp Binary files differdeleted file mode 100644 index 8893e3bd..00000000 --- a/docs/_static/images/cloud-aws-vyos-11.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-ha-architecture.webp b/docs/_static/images/cloud-azure-ha-architecture.webp Binary files differdeleted file mode 100644 index 20e3e6dc..00000000 --- a/docs/_static/images/cloud-azure-ha-architecture.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-nic-01.webp b/docs/_static/images/cloud-azure-nic-01.webp Binary files differdeleted file mode 100644 index 37c22a86..00000000 --- a/docs/_static/images/cloud-azure-nic-01.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-nic-02.webp b/docs/_static/images/cloud-azure-nic-02.webp Binary files differdeleted file mode 100644 index 5a348732..00000000 --- a/docs/_static/images/cloud-azure-nic-02.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-nic-03.webp b/docs/_static/images/cloud-azure-nic-03.webp Binary files differdeleted file mode 100644 index 9002fba3..00000000 --- a/docs/_static/images/cloud-azure-nic-03.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-nic-04.webp b/docs/_static/images/cloud-azure-nic-04.webp Binary files differdeleted file mode 100644 index c24b8cda..00000000 --- a/docs/_static/images/cloud-azure-nic-04.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-pub-ip-01.webp b/docs/_static/images/cloud-azure-pub-ip-01.webp Binary files differdeleted file mode 100644 index 648e97cc..00000000 --- a/docs/_static/images/cloud-azure-pub-ip-01.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-pub-ip-02.webp b/docs/_static/images/cloud-azure-pub-ip-02.webp Binary files differdeleted file mode 100644 index b79eb2d8..00000000 --- a/docs/_static/images/cloud-azure-pub-ip-02.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-pub-ip-03.webp b/docs/_static/images/cloud-azure-pub-ip-03.webp Binary files differdeleted file mode 100644 index e6ec5fa8..00000000 --- a/docs/_static/images/cloud-azure-pub-ip-03.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-rg-01.webp b/docs/_static/images/cloud-azure-rg-01.webp Binary files differdeleted file mode 100644 index 194b66ae..00000000 --- a/docs/_static/images/cloud-azure-rg-01.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-rg-02.webp b/docs/_static/images/cloud-azure-rg-02.webp Binary files differdeleted file mode 100644 index 6b1bcea5..00000000 --- a/docs/_static/images/cloud-azure-rg-02.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-route-01.webp b/docs/_static/images/cloud-azure-route-01.webp Binary files differdeleted file mode 100644 index 44036f0d..00000000 --- a/docs/_static/images/cloud-azure-route-01.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-route-02.webp b/docs/_static/images/cloud-azure-route-02.webp Binary files differdeleted file mode 100644 index 41159484..00000000 --- a/docs/_static/images/cloud-azure-route-02.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-route-03.webp b/docs/_static/images/cloud-azure-route-03.webp Binary files differdeleted file mode 100644 index d316c94f..00000000 --- a/docs/_static/images/cloud-azure-route-03.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-route-04.webp b/docs/_static/images/cloud-azure-route-04.webp Binary files differdeleted file mode 100644 index edfcb232..00000000 --- a/docs/_static/images/cloud-azure-route-04.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-route-05.webp b/docs/_static/images/cloud-azure-route-05.webp Binary files differdeleted file mode 100644 index ead3e73e..00000000 --- a/docs/_static/images/cloud-azure-route-05.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-sg-01.webp b/docs/_static/images/cloud-azure-sg-01.webp Binary files differdeleted file mode 100644 index d7c38a99..00000000 --- a/docs/_static/images/cloud-azure-sg-01.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-sg-02.webp b/docs/_static/images/cloud-azure-sg-02.webp Binary files differdeleted file mode 100644 index fd2ddc34..00000000 --- a/docs/_static/images/cloud-azure-sg-02.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-sg-03.webp b/docs/_static/images/cloud-azure-sg-03.webp Binary files differdeleted file mode 100644 index fa4a2b8f..00000000 --- a/docs/_static/images/cloud-azure-sg-03.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-sg-04.webp b/docs/_static/images/cloud-azure-sg-04.webp Binary files differdeleted file mode 100644 index 13078e17..00000000 --- a/docs/_static/images/cloud-azure-sg-04.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vm-01.webp b/docs/_static/images/cloud-azure-vm-01.webp Binary files differdeleted file mode 100644 index a305a263..00000000 --- a/docs/_static/images/cloud-azure-vm-01.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vm-02.webp b/docs/_static/images/cloud-azure-vm-02.webp Binary files differdeleted file mode 100644 index 3a629165..00000000 --- a/docs/_static/images/cloud-azure-vm-02.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vm-03.webp b/docs/_static/images/cloud-azure-vm-03.webp Binary files differdeleted file mode 100644 index e1f1b98d..00000000 --- a/docs/_static/images/cloud-azure-vm-03.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vm-04.webp b/docs/_static/images/cloud-azure-vm-04.webp Binary files differdeleted file mode 100644 index c28a10b5..00000000 --- a/docs/_static/images/cloud-azure-vm-04.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vm-05.webp b/docs/_static/images/cloud-azure-vm-05.webp Binary files differdeleted file mode 100644 index 1cfb2d56..00000000 --- a/docs/_static/images/cloud-azure-vm-05.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vm-06.webp b/docs/_static/images/cloud-azure-vm-06.webp Binary files differdeleted file mode 100644 index ce71b375..00000000 --- a/docs/_static/images/cloud-azure-vm-06.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vm-07.webp b/docs/_static/images/cloud-azure-vm-07.webp Binary files differdeleted file mode 100644 index d1ff8585..00000000 --- a/docs/_static/images/cloud-azure-vm-07.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vm-08.webp b/docs/_static/images/cloud-azure-vm-08.webp Binary files differdeleted file mode 100644 index 93b290fa..00000000 --- a/docs/_static/images/cloud-azure-vm-08.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vm-09.webp b/docs/_static/images/cloud-azure-vm-09.webp Binary files differdeleted file mode 100644 index 1a9ec0da..00000000 --- a/docs/_static/images/cloud-azure-vm-09.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vm-10.webp b/docs/_static/images/cloud-azure-vm-10.webp Binary files differdeleted file mode 100644 index feec6515..00000000 --- a/docs/_static/images/cloud-azure-vm-10.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vm-11.webp b/docs/_static/images/cloud-azure-vm-11.webp Binary files differdeleted file mode 100644 index 15c8149f..00000000 --- a/docs/_static/images/cloud-azure-vm-11.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vm-12.webp b/docs/_static/images/cloud-azure-vm-12.webp Binary files differdeleted file mode 100644 index f549f3e7..00000000 --- a/docs/_static/images/cloud-azure-vm-12.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vm-13.webp b/docs/_static/images/cloud-azure-vm-13.webp Binary files differdeleted file mode 100644 index 2d6964bf..00000000 --- a/docs/_static/images/cloud-azure-vm-13.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vnet-01.webp b/docs/_static/images/cloud-azure-vnet-01.webp Binary files differdeleted file mode 100644 index 0b24d59c..00000000 --- a/docs/_static/images/cloud-azure-vnet-01.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vnet-02.webp b/docs/_static/images/cloud-azure-vnet-02.webp Binary files differdeleted file mode 100644 index 033ac5a2..00000000 --- a/docs/_static/images/cloud-azure-vnet-02.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vnet-03.webp b/docs/_static/images/cloud-azure-vnet-03.webp Binary files differdeleted file mode 100644 index 7fbdd484..00000000 --- a/docs/_static/images/cloud-azure-vnet-03.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vnet-04.webp b/docs/_static/images/cloud-azure-vnet-04.webp Binary files differdeleted file mode 100644 index 49fe70d5..00000000 --- a/docs/_static/images/cloud-azure-vnet-04.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vnet-05.webp b/docs/_static/images/cloud-azure-vnet-05.webp Binary files differdeleted file mode 100644 index 2ac0bcd7..00000000 --- a/docs/_static/images/cloud-azure-vnet-05.webp +++ /dev/null diff --git a/docs/_static/images/cloud-azure-vnet-06.webp b/docs/_static/images/cloud-azure-vnet-06.webp Binary files differdeleted file mode 100644 index 0da36ab0..00000000 --- a/docs/_static/images/cloud-azure-vnet-06.webp +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-01.webp b/docs/_static/images/cloud-gcp-01.webp Binary files differdeleted file mode 100644 index d21fc5ff..00000000 --- a/docs/_static/images/cloud-gcp-01.webp +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-02.webp b/docs/_static/images/cloud-gcp-02.webp Binary files differdeleted file mode 100644 index 977f411f..00000000 --- a/docs/_static/images/cloud-gcp-02.webp +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-market-01.webp b/docs/_static/images/cloud-gcp-market-01.webp Binary files differdeleted file mode 100644 index ffe56746..00000000 --- a/docs/_static/images/cloud-gcp-market-01.webp +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-market-02.webp b/docs/_static/images/cloud-gcp-market-02.webp Binary files differdeleted file mode 100644 index 78aa7192..00000000 --- a/docs/_static/images/cloud-gcp-market-02.webp +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-market-03.webp b/docs/_static/images/cloud-gcp-market-03.webp Binary files differdeleted file mode 100644 index 617970a9..00000000 --- a/docs/_static/images/cloud-gcp-market-03.webp +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-market-04.webp b/docs/_static/images/cloud-gcp-market-04.webp Binary files differdeleted file mode 100644 index f6518aaa..00000000 --- a/docs/_static/images/cloud-gcp-market-04.webp +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-market-05.webp b/docs/_static/images/cloud-gcp-market-05.webp Binary files differdeleted file mode 100644 index 20089558..00000000 --- a/docs/_static/images/cloud-gcp-market-05.webp +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-proj.webp b/docs/_static/images/cloud-gcp-proj.webp Binary files differdeleted file mode 100644 index c7842b72..00000000 --- a/docs/_static/images/cloud-gcp-proj.webp +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-svc.webp b/docs/_static/images/cloud-gcp-svc.webp Binary files differdeleted file mode 100644 index 8f19d73a..00000000 --- a/docs/_static/images/cloud-gcp-svc.webp +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vm-01.webp b/docs/_static/images/cloud-gcp-vm-01.webp Binary files differdeleted file mode 100644 index be27a325..00000000 --- a/docs/_static/images/cloud-gcp-vm-01.webp +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vm-02.webp b/docs/_static/images/cloud-gcp-vm-02.webp Binary files differdeleted file mode 100644 index c72dcb51..00000000 --- a/docs/_static/images/cloud-gcp-vm-02.webp +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vm-03.webp b/docs/_static/images/cloud-gcp-vm-03.webp Binary files differdeleted file mode 100644 index 0e30aff7..00000000 --- a/docs/_static/images/cloud-gcp-vm-03.webp +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vm-04.webp b/docs/_static/images/cloud-gcp-vm-04.webp Binary files differdeleted file mode 100644 index 0dc2cb41..00000000 --- a/docs/_static/images/cloud-gcp-vm-04.webp +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vm-06.webp b/docs/_static/images/cloud-gcp-vm-06.webp Binary files differdeleted file mode 100644 index 36a33528..00000000 --- a/docs/_static/images/cloud-gcp-vm-06.webp +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vm-07.webp b/docs/_static/images/cloud-gcp-vm-07.webp Binary files differdeleted file mode 100644 index 5ba96ee3..00000000 --- a/docs/_static/images/cloud-gcp-vm-07.webp +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vm-08.webp b/docs/_static/images/cloud-gcp-vm-08.webp Binary files differdeleted file mode 100644 index 21524ec8..00000000 --- a/docs/_static/images/cloud-gcp-vm-08.webp +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vm-09.webp b/docs/_static/images/cloud-gcp-vm-09.webp Binary files differdeleted file mode 100644 index 1cfb2d56..00000000 --- a/docs/_static/images/cloud-gcp-vm-09.webp +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vpc-01.webp b/docs/_static/images/cloud-gcp-vpc-01.webp Binary files differdeleted file mode 100644 index 194fa272..00000000 --- a/docs/_static/images/cloud-gcp-vpc-01.webp +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vpc-02.webp b/docs/_static/images/cloud-gcp-vpc-02.webp Binary files differdeleted file mode 100644 index 02267cca..00000000 --- a/docs/_static/images/cloud-gcp-vpc-02.webp +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vpc-03.webp b/docs/_static/images/cloud-gcp-vpc-03.webp Binary files differdeleted file mode 100644 index f738729b..00000000 --- a/docs/_static/images/cloud-gcp-vpc-03.webp +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vpc-04.webp b/docs/_static/images/cloud-gcp-vpc-04.webp Binary files differdeleted file mode 100644 index 6cd6f63e..00000000 --- a/docs/_static/images/cloud-gcp-vpc-04.webp +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vpc-05.webp b/docs/_static/images/cloud-gcp-vpc-05.webp Binary files differdeleted file mode 100644 index a8dafebb..00000000 --- a/docs/_static/images/cloud-gcp-vpc-05.webp +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vpc-06.webp b/docs/_static/images/cloud-gcp-vpc-06.webp Binary files differdeleted file mode 100644 index 72fe8bbb..00000000 --- a/docs/_static/images/cloud-gcp-vpc-06.webp +++ /dev/null diff --git a/docs/_static/images/cloud-gcp-vpc-07.webp b/docs/_static/images/cloud-gcp-vpc-07.webp Binary files differdeleted file mode 100644 index 2225f55e..00000000 --- a/docs/_static/images/cloud-gcp-vpc-07.webp +++ /dev/null diff --git a/docs/_static/images/dhcp-relay-through-gre-bridge.webp b/docs/_static/images/dhcp-relay-through-gre-bridge.webp Binary files differdeleted file mode 100644 index 4b626e91..00000000 --- a/docs/_static/images/dhcp-relay-through-gre-bridge.webp +++ /dev/null diff --git a/docs/_static/images/eve-ng-vyos.webp b/docs/_static/images/eve-ng-vyos.webp Binary files differdeleted file mode 100644 index f68b2fba..00000000 --- a/docs/_static/images/eve-ng-vyos.webp +++ /dev/null diff --git a/docs/_static/images/firewall-and-vrf-blueprints.webp b/docs/_static/images/firewall-and-vrf-blueprints.webp Binary files differdeleted file mode 100644 index 17194880..00000000 --- a/docs/_static/images/firewall-and-vrf-blueprints.webp +++ /dev/null diff --git a/docs/_static/images/firewall-bridge-packet-flow.webp b/docs/_static/images/firewall-bridge-packet-flow.webp Binary files differdeleted file mode 100644 index 908eaee3..00000000 --- a/docs/_static/images/firewall-bridge-packet-flow.webp +++ /dev/null diff --git a/docs/_static/images/firewall-flowtable-packet-flow.webp b/docs/_static/images/firewall-flowtable-packet-flow.webp Binary files differdeleted file mode 100644 index 6d20ab7a..00000000 --- a/docs/_static/images/firewall-flowtable-packet-flow.webp +++ /dev/null diff --git a/docs/_static/images/firewall-fwd-packet-flow.webp b/docs/_static/images/firewall-fwd-packet-flow.webp Binary files differdeleted file mode 100644 index 31b155a9..00000000 --- a/docs/_static/images/firewall-fwd-packet-flow.webp +++ /dev/null diff --git a/docs/_static/images/firewall-gral-packet-flow.webp b/docs/_static/images/firewall-gral-packet-flow.webp Binary files differdeleted file mode 100644 index add21b1e..00000000 --- a/docs/_static/images/firewall-gral-packet-flow.webp +++ /dev/null diff --git a/docs/_static/images/firewall-input-packet-flow.webp b/docs/_static/images/firewall-input-packet-flow.webp Binary files differdeleted file mode 100644 index a5f207a1..00000000 --- a/docs/_static/images/firewall-input-packet-flow.webp +++ /dev/null diff --git a/docs/_static/images/firewall-traditional.webp b/docs/_static/images/firewall-traditional.webp Binary files differdeleted file mode 100644 index 2804393f..00000000 --- a/docs/_static/images/firewall-traditional.webp +++ /dev/null diff --git a/docs/_static/images/firewall-zonebased.webp b/docs/_static/images/firewall-zonebased.webp Binary files differdeleted file mode 100644 index 11394be0..00000000 --- a/docs/_static/images/firewall-zonebased.webp +++ /dev/null diff --git a/docs/_static/images/gns3-01.webp b/docs/_static/images/gns3-01.webp Binary files differdeleted file mode 100644 index d0d48d26..00000000 --- a/docs/_static/images/gns3-01.webp +++ /dev/null diff --git a/docs/_static/images/gns3-02.webp b/docs/_static/images/gns3-02.webp Binary files differdeleted file mode 100644 index 83ec7546..00000000 --- a/docs/_static/images/gns3-02.webp +++ /dev/null diff --git a/docs/_static/images/gns3-03.webp b/docs/_static/images/gns3-03.webp Binary files differdeleted file mode 100644 index aab36829..00000000 --- a/docs/_static/images/gns3-03.webp +++ /dev/null diff --git a/docs/_static/images/gns3-04.webp b/docs/_static/images/gns3-04.webp Binary files differdeleted file mode 100644 index 722789bb..00000000 --- a/docs/_static/images/gns3-04.webp +++ /dev/null diff --git a/docs/_static/images/gns3-05.webp b/docs/_static/images/gns3-05.webp Binary files differdeleted file mode 100644 index db42dd62..00000000 --- a/docs/_static/images/gns3-05.webp +++ /dev/null diff --git a/docs/_static/images/gns3-06.webp b/docs/_static/images/gns3-06.webp Binary files differdeleted file mode 100644 index b41d774c..00000000 --- a/docs/_static/images/gns3-06.webp +++ /dev/null diff --git a/docs/_static/images/gns3-07.webp b/docs/_static/images/gns3-07.webp Binary files differdeleted file mode 100644 index 360644f8..00000000 --- a/docs/_static/images/gns3-07.webp +++ /dev/null diff --git a/docs/_static/images/gns3-08.webp b/docs/_static/images/gns3-08.webp Binary files differdeleted file mode 100644 index d7a8f3c3..00000000 --- a/docs/_static/images/gns3-08.webp +++ /dev/null diff --git a/docs/_static/images/gns3-09.webp b/docs/_static/images/gns3-09.webp Binary files differdeleted file mode 100644 index b68dfdab..00000000 --- a/docs/_static/images/gns3-09.webp +++ /dev/null diff --git a/docs/_static/images/gns3-10.webp b/docs/_static/images/gns3-10.webp Binary files differdeleted file mode 100644 index 61ab6d4e..00000000 --- a/docs/_static/images/gns3-10.webp +++ /dev/null diff --git a/docs/_static/images/gns3-11.webp b/docs/_static/images/gns3-11.webp Binary files differdeleted file mode 100644 index efac5bb7..00000000 --- a/docs/_static/images/gns3-11.webp +++ /dev/null diff --git a/docs/_static/images/gns3-12.webp b/docs/_static/images/gns3-12.webp Binary files differdeleted file mode 100644 index f0760510..00000000 --- a/docs/_static/images/gns3-12.webp +++ /dev/null diff --git a/docs/_static/images/gns3-13.webp b/docs/_static/images/gns3-13.webp Binary files differdeleted file mode 100644 index a246380e..00000000 --- a/docs/_static/images/gns3-13.webp +++ /dev/null diff --git a/docs/_static/images/gns3-14.webp b/docs/_static/images/gns3-14.webp Binary files differdeleted file mode 100644 index 7e111c58..00000000 --- a/docs/_static/images/gns3-14.webp +++ /dev/null diff --git a/docs/_static/images/gns3-15.webp b/docs/_static/images/gns3-15.webp Binary files differdeleted file mode 100644 index 79e7e6db..00000000 --- a/docs/_static/images/gns3-15.webp +++ /dev/null diff --git a/docs/_static/images/gns3-16.webp b/docs/_static/images/gns3-16.webp Binary files differdeleted file mode 100644 index 423503ed..00000000 --- a/docs/_static/images/gns3-16.webp +++ /dev/null diff --git a/docs/_static/images/gns3-17.webp b/docs/_static/images/gns3-17.webp Binary files differdeleted file mode 100644 index 8b7e5c01..00000000 --- a/docs/_static/images/gns3-17.webp +++ /dev/null diff --git a/docs/_static/images/gns3-20.webp b/docs/_static/images/gns3-20.webp Binary files differdeleted file mode 100644 index a65c47b4..00000000 --- a/docs/_static/images/gns3-20.webp +++ /dev/null diff --git a/docs/_static/images/gns3-21.webp b/docs/_static/images/gns3-21.webp Binary files differdeleted file mode 100644 index adc71baa..00000000 --- a/docs/_static/images/gns3-21.webp +++ /dev/null diff --git a/docs/_static/images/gns3-215.webp b/docs/_static/images/gns3-215.webp Binary files differdeleted file mode 100644 index 49755246..00000000 --- a/docs/_static/images/gns3-215.webp +++ /dev/null diff --git a/docs/_static/images/gns3-22.webp b/docs/_static/images/gns3-22.webp Binary files differdeleted file mode 100644 index 90bc4fa4..00000000 --- a/docs/_static/images/gns3-22.webp +++ /dev/null diff --git a/docs/_static/images/gowin-01.webp b/docs/_static/images/gowin-01.webp Binary files differdeleted file mode 100644 index 048252d3..00000000 --- a/docs/_static/images/gowin-01.webp +++ /dev/null diff --git a/docs/_static/images/gowin-02.webp b/docs/_static/images/gowin-02.webp Binary files differdeleted file mode 100644 index 816c178c..00000000 --- a/docs/_static/images/gowin-02.webp +++ /dev/null diff --git a/docs/_static/images/gowin-03.webp b/docs/_static/images/gowin-03.webp Binary files differdeleted file mode 100644 index ebf67368..00000000 --- a/docs/_static/images/gowin-03.webp +++ /dev/null diff --git a/docs/_static/images/gowin-04.webp b/docs/_static/images/gowin-04.webp Binary files differdeleted file mode 100644 index b5e94a84..00000000 --- a/docs/_static/images/gowin-04.webp +++ /dev/null diff --git a/docs/_static/images/inter-vrf-routing-vrf-lite.webp b/docs/_static/images/inter-vrf-routing-vrf-lite.webp Binary files differdeleted file mode 100644 index 43394ec5..00000000 --- a/docs/_static/images/inter-vrf-routing-vrf-lite.webp +++ /dev/null diff --git a/docs/_static/images/ipsec-vyos-pa.webp b/docs/_static/images/ipsec-vyos-pa.webp Binary files differdeleted file mode 100644 index 1758d65c..00000000 --- a/docs/_static/images/ipsec-vyos-pa.webp +++ /dev/null diff --git a/docs/_static/images/keypairs.webp b/docs/_static/images/keypairs.webp Binary files differdeleted file mode 100644 index 14df4da3..00000000 --- a/docs/_static/images/keypairs.webp +++ /dev/null diff --git a/docs/_static/images/lac-lns-diagram.webp b/docs/_static/images/lac-lns-diagram.webp Binary files differdeleted file mode 100644 index 0ce052c2..00000000 --- a/docs/_static/images/lac-lns-diagram.webp +++ /dev/null diff --git a/docs/_static/images/lac-lns-winclient.webp b/docs/_static/images/lac-lns-winclient.webp Binary files differdeleted file mode 100644 index 95792cad..00000000 --- a/docs/_static/images/lac-lns-winclient.webp +++ /dev/null diff --git a/docs/_static/images/ldapone.webp b/docs/_static/images/ldapone.webp Binary files differdeleted file mode 100644 index 0f070454..00000000 --- a/docs/_static/images/ldapone.webp +++ /dev/null diff --git a/docs/_static/images/ldaptwo.webp b/docs/_static/images/ldaptwo.webp Binary files differdeleted file mode 100644 index 9ee636df..00000000 --- a/docs/_static/images/ldaptwo.webp +++ /dev/null diff --git a/docs/_static/images/mainschema.webp b/docs/_static/images/mainschema.webp Binary files differdeleted file mode 100644 index c9db82ca..00000000 --- a/docs/_static/images/mainschema.webp +++ /dev/null diff --git a/docs/_static/images/multicast-basic.webp b/docs/_static/images/multicast-basic.webp Binary files differdeleted file mode 100644 index 8e963421..00000000 --- a/docs/_static/images/multicast-basic.webp +++ /dev/null diff --git a/docs/_static/images/nat_before_vpn_topology.webp b/docs/_static/images/nat_before_vpn_topology.webp Binary files differdeleted file mode 100644 index 7f93a3d8..00000000 --- a/docs/_static/images/nat_before_vpn_topology.webp +++ /dev/null diff --git a/docs/_static/images/nmp1.webp b/docs/_static/images/nmp1.webp Binary files differdeleted file mode 100644 index 60035421..00000000 --- a/docs/_static/images/nmp1.webp +++ /dev/null diff --git a/docs/_static/images/nmp2.webp b/docs/_static/images/nmp2.webp Binary files differdeleted file mode 100644 index 6dbf4d42..00000000 --- a/docs/_static/images/nmp2.webp +++ /dev/null diff --git a/docs/_static/images/nmp3.webp b/docs/_static/images/nmp3.webp Binary files differdeleted file mode 100644 index 72ab7050..00000000 --- a/docs/_static/images/nmp3.webp +++ /dev/null diff --git a/docs/_static/images/nmp4.webp b/docs/_static/images/nmp4.webp Binary files differdeleted file mode 100644 index d7684b38..00000000 --- a/docs/_static/images/nmp4.webp +++ /dev/null diff --git a/docs/_static/images/nmp5.webp b/docs/_static/images/nmp5.webp Binary files differdeleted file mode 100644 index 6c64707c..00000000 --- a/docs/_static/images/nmp5.webp +++ /dev/null diff --git a/docs/_static/images/nmp6.webp b/docs/_static/images/nmp6.webp Binary files differdeleted file mode 100644 index 85141b11..00000000 --- a/docs/_static/images/nmp6.webp +++ /dev/null diff --git a/docs/_static/images/nmp7.webp b/docs/_static/images/nmp7.webp Binary files differdeleted file mode 100644 index 6f64df83..00000000 --- a/docs/_static/images/nmp7.webp +++ /dev/null diff --git a/docs/_static/images/openvpn_site2site_diagram.webp b/docs/_static/images/openvpn_site2site_diagram.webp Binary files differdeleted file mode 100644 index 97d4df3f..00000000 --- a/docs/_static/images/openvpn_site2site_diagram.webp +++ /dev/null diff --git a/docs/_static/images/password-recovery-01.webp b/docs/_static/images/password-recovery-01.webp Binary files differdeleted file mode 100644 index 26427ecb..00000000 --- a/docs/_static/images/password-recovery-01.webp +++ /dev/null diff --git a/docs/_static/images/pbr_example_1.webp b/docs/_static/images/pbr_example_1.webp Binary files differdeleted file mode 100644 index 4e8ba882..00000000 --- a/docs/_static/images/pbr_example_1.webp +++ /dev/null diff --git a/docs/_static/images/permanent_install.webp b/docs/_static/images/permanent_install.webp Binary files differdeleted file mode 100644 index 6ab06b0a..00000000 --- a/docs/_static/images/permanent_install.webp +++ /dev/null diff --git a/docs/_static/images/pppoe-ipv6-pd-diagram.webp b/docs/_static/images/pppoe-ipv6-pd-diagram.webp Binary files differdeleted file mode 100644 index 344bbf21..00000000 --- a/docs/_static/images/pppoe-ipv6-pd-diagram.webp +++ /dev/null diff --git a/docs/_static/images/qos1.webp b/docs/_static/images/qos1.webp Binary files differdeleted file mode 100644 index fe9264a6..00000000 --- a/docs/_static/images/qos1.webp +++ /dev/null diff --git a/docs/_static/images/qos10.webp b/docs/_static/images/qos10.webp Binary files differdeleted file mode 100644 index 646ae67b..00000000 --- a/docs/_static/images/qos10.webp +++ /dev/null diff --git a/docs/_static/images/qos2.webp b/docs/_static/images/qos2.webp Binary files differdeleted file mode 100644 index 7c8a1336..00000000 --- a/docs/_static/images/qos2.webp +++ /dev/null diff --git a/docs/_static/images/qos3.webp b/docs/_static/images/qos3.webp Binary files differdeleted file mode 100644 index 3cf2dd32..00000000 --- a/docs/_static/images/qos3.webp +++ /dev/null diff --git a/docs/_static/images/qos4.webp b/docs/_static/images/qos4.webp Binary files differdeleted file mode 100644 index cc108ee8..00000000 --- a/docs/_static/images/qos4.webp +++ /dev/null diff --git a/docs/_static/images/qos5.webp b/docs/_static/images/qos5.webp Binary files differdeleted file mode 100644 index d41ae04d..00000000 --- a/docs/_static/images/qos5.webp +++ /dev/null diff --git a/docs/_static/images/qos6.webp b/docs/_static/images/qos6.webp Binary files differdeleted file mode 100644 index 7d238851..00000000 --- a/docs/_static/images/qos6.webp +++ /dev/null diff --git a/docs/_static/images/qos7.webp b/docs/_static/images/qos7.webp Binary files differdeleted file mode 100644 index 026452c2..00000000 --- a/docs/_static/images/qos7.webp +++ /dev/null diff --git a/docs/_static/images/qos8.webp b/docs/_static/images/qos8.webp Binary files differdeleted file mode 100644 index e1706ce2..00000000 --- a/docs/_static/images/qos8.webp +++ /dev/null diff --git a/docs/_static/images/qos9.webp b/docs/_static/images/qos9.webp Binary files differdeleted file mode 100644 index 2cc6fdaa..00000000 --- a/docs/_static/images/qos9.webp +++ /dev/null diff --git a/docs/_static/images/service_conntrack_sync-schema.webp b/docs/_static/images/service_conntrack_sync-schema.webp Binary files differdeleted file mode 100644 index e347aa19..00000000 --- a/docs/_static/images/service_conntrack_sync-schema.webp +++ /dev/null diff --git a/docs/_static/images/service_dhcp-relay01.webp b/docs/_static/images/service_dhcp-relay01.webp Binary files differdeleted file mode 100644 index 5fbfad3e..00000000 --- a/docs/_static/images/service_dhcp-relay01.webp +++ /dev/null diff --git a/docs/_static/images/service_dhcpv6-relay01.webp b/docs/_static/images/service_dhcpv6-relay01.webp Binary files differdeleted file mode 100644 index 1f72f51f..00000000 --- a/docs/_static/images/service_dhcpv6-relay01.webp +++ /dev/null diff --git a/docs/_static/images/service_snmp_communication_principles_diagram.webp b/docs/_static/images/service_snmp_communication_principles_diagram.webp Binary files differdeleted file mode 100644 index abb18133..00000000 --- a/docs/_static/images/service_snmp_communication_principles_diagram.webp +++ /dev/null diff --git a/docs/_static/images/sg.webp b/docs/_static/images/sg.webp Binary files differdeleted file mode 100644 index 5ee77e0d..00000000 --- a/docs/_static/images/sg.webp +++ /dev/null diff --git a/docs/_static/images/sticky-connections.webp b/docs/_static/images/sticky-connections.webp Binary files differdeleted file mode 100644 index 92e5b769..00000000 --- a/docs/_static/images/sticky-connections.webp +++ /dev/null diff --git a/docs/_static/images/traffic.webp b/docs/_static/images/traffic.webp Binary files differdeleted file mode 100644 index f6f9e183..00000000 --- a/docs/_static/images/traffic.webp +++ /dev/null diff --git a/docs/_static/images/virt-libvirt-01.webp b/docs/_static/images/virt-libvirt-01.webp Binary files differdeleted file mode 100644 index 02498c96..00000000 --- a/docs/_static/images/virt-libvirt-01.webp +++ /dev/null diff --git a/docs/_static/images/virt-libvirt-02.webp b/docs/_static/images/virt-libvirt-02.webp Binary files differdeleted file mode 100644 index 06ad10aa..00000000 --- a/docs/_static/images/virt-libvirt-02.webp +++ /dev/null diff --git a/docs/_static/images/virt-libvirt-03.webp b/docs/_static/images/virt-libvirt-03.webp Binary files differdeleted file mode 100644 index e8beae0c..00000000 --- a/docs/_static/images/virt-libvirt-03.webp +++ /dev/null diff --git a/docs/_static/images/virt-libvirt-04.webp b/docs/_static/images/virt-libvirt-04.webp Binary files differdeleted file mode 100644 index 586cdedb..00000000 --- a/docs/_static/images/virt-libvirt-04.webp +++ /dev/null diff --git a/docs/_static/images/virt-libvirt-05.webp b/docs/_static/images/virt-libvirt-05.webp Binary files differdeleted file mode 100644 index 65c57a3d..00000000 --- a/docs/_static/images/virt-libvirt-05.webp +++ /dev/null diff --git a/docs/_static/images/virt-libvirt-06.webp b/docs/_static/images/virt-libvirt-06.webp Binary files differdeleted file mode 100644 index da7a41a9..00000000 --- a/docs/_static/images/virt-libvirt-06.webp +++ /dev/null diff --git a/docs/_static/images/virt-libvirt-qc-01.webp b/docs/_static/images/virt-libvirt-qc-01.webp Binary files differdeleted file mode 100644 index 1b19ca60..00000000 --- a/docs/_static/images/virt-libvirt-qc-01.webp +++ /dev/null diff --git a/docs/_static/images/virt-libvirt-qc-02.webp b/docs/_static/images/virt-libvirt-qc-02.webp Binary files differdeleted file mode 100644 index 8281ebfb..00000000 --- a/docs/_static/images/virt-libvirt-qc-02.webp +++ /dev/null diff --git a/docs/_static/images/virt-libvirt-qc-03.webp b/docs/_static/images/virt-libvirt-qc-03.webp Binary files differdeleted file mode 100644 index 7dc4e7e8..00000000 --- a/docs/_static/images/virt-libvirt-qc-03.webp +++ /dev/null diff --git a/docs/_static/images/vpn_dmvpn_topology01.webp b/docs/_static/images/vpn_dmvpn_topology01.webp Binary files differdeleted file mode 100644 index 3da35995..00000000 --- a/docs/_static/images/vpn_dmvpn_topology01.webp +++ /dev/null diff --git a/docs/_static/images/vpn_s2s_ikev2.webp b/docs/_static/images/vpn_s2s_ikev2.webp Binary files differdeleted file mode 100644 index 615f689c..00000000 --- a/docs/_static/images/vpn_s2s_ikev2.webp +++ /dev/null diff --git a/docs/_static/images/vpn_s2s_ikev2_c.webp b/docs/_static/images/vpn_s2s_ikev2_c.webp Binary files differdeleted file mode 100644 index f572fc29..00000000 --- a/docs/_static/images/vpn_s2s_ikev2_c.webp +++ /dev/null diff --git a/docs/_static/images/vrf-example-topology-01.webp b/docs/_static/images/vrf-example-topology-01.webp Binary files differdeleted file mode 100644 index 696abad1..00000000 --- a/docs/_static/images/vrf-example-topology-01.webp +++ /dev/null diff --git a/docs/_static/images/vyos-downloads.webp b/docs/_static/images/vyos-downloads.webp Binary files differdeleted file mode 100644 index 9d446701..00000000 --- a/docs/_static/images/vyos-downloads.webp +++ /dev/null diff --git a/docs/_static/images/vyos-sr-isis.webp b/docs/_static/images/vyos-sr-isis.webp Binary files differdeleted file mode 100644 index 8ecad813..00000000 --- a/docs/_static/images/vyos-sr-isis.webp +++ /dev/null diff --git a/docs/_static/images/vyos_1_4_nat66_simple.webp b/docs/_static/images/vyos_1_4_nat66_simple.webp Binary files differdeleted file mode 100644 index 6dedc08c..00000000 --- a/docs/_static/images/vyos_1_4_nat66_simple.webp +++ /dev/null diff --git a/docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.webp b/docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.webp Binary files differdeleted file mode 100644 index 352d1f08..00000000 --- a/docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.webp +++ /dev/null diff --git a/docs/_static/images/vyos_arista_bond_lacp.webp b/docs/_static/images/vyos_arista_bond_lacp.webp Binary files differdeleted file mode 100644 index 6ac71379..00000000 --- a/docs/_static/images/vyos_arista_bond_lacp.webp +++ /dev/null diff --git a/docs/_static/images/vyosnew-downloads.webp b/docs/_static/images/vyosnew-downloads.webp Binary files differdeleted file mode 100644 index fbbb21c8..00000000 --- a/docs/_static/images/vyosnew-downloads.webp +++ /dev/null diff --git a/docs/_static/images/wireguard_qrcode.webp b/docs/_static/images/wireguard_qrcode.webp Binary files differdeleted file mode 100644 index 7eb02d79..00000000 --- a/docs/_static/images/wireguard_qrcode.webp +++ /dev/null diff --git a/docs/_static/images/wireguard_site2site_diagram.webp b/docs/_static/images/wireguard_site2site_diagram.webp Binary files differdeleted file mode 100644 index 9f73ad4e..00000000 --- a/docs/_static/images/wireguard_site2site_diagram.webp +++ /dev/null diff --git a/docs/_static/images/zone-policy-diagram.webp b/docs/_static/images/zone-policy-diagram.webp Binary files differdeleted file mode 100644 index 850df285..00000000 --- a/docs/_static/images/zone-policy-diagram.webp +++ /dev/null diff --git a/docs/_swap.txt b/docs/_swap.txt deleted file mode 100644 index 9e18a829..00000000 --- a/docs/_swap.txt +++ /dev/null @@ -1,210 +0,0 @@ -# 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 deleted file mode 100644 index 446d0f64..00000000 --- a/docs/automation/md-cloud-init.md +++ /dev/null @@ -1,376 +0,0 @@ -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 deleted file mode 100644 index 5c2d8f19..00000000 --- a/docs/automation/md-command-scripting.md +++ /dev/null @@ -1,219 +0,0 @@ -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 deleted file mode 100644 index bf456f0d..00000000 --- a/docs/automation/md-index.md +++ /dev/null @@ -1,14 +0,0 @@ -# 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 deleted file mode 100644 index ba348ca1..00000000 --- a/docs/automation/md-vyos-ansible.md +++ /dev/null @@ -1,86 +0,0 @@ -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 deleted file mode 100644 index 7618e262..00000000 --- a/docs/automation/md-vyos-api.md +++ /dev/null @@ -1,380 +0,0 @@ -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 deleted file mode 100644 index ca3fd97c..00000000 --- a/docs/automation/md-vyos-napalm.md +++ /dev/null @@ -1,137 +0,0 @@ -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 deleted file mode 100644 index 84622a0d..00000000 --- a/docs/automation/md-vyos-netmiko.md +++ /dev/null @@ -1,67 +0,0 @@ -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 deleted file mode 100644 index 8b770a8f..00000000 --- a/docs/automation/md-vyos-salt.md +++ /dev/null @@ -1,204 +0,0 @@ -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 deleted file mode 100644 index 9d02b913..00000000 --- a/docs/automation/terraform/md-index.md +++ /dev/null @@ -1,11 +0,0 @@ -# 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 deleted file mode 100644 index 7485b3eb..00000000 --- a/docs/automation/terraform/md-terraformAWS.md +++ /dev/null @@ -1,493 +0,0 @@ -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 deleted file mode 100644 index e4ed9de9..00000000 --- a/docs/automation/terraform/md-terraformAZ.md +++ /dev/null @@ -1,466 +0,0 @@ -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 deleted file mode 100644 index 8b137891..00000000 --- a/docs/automation/terraform/md-terraformGoogle.md +++ /dev/null @@ -1 +0,0 @@ - diff --git a/docs/automation/terraform/md-terraformvSphere.md b/docs/automation/terraform/md-terraformvSphere.md deleted file mode 100644 index 2e5d3927..00000000 --- a/docs/automation/terraform/md-terraformvSphere.md +++ /dev/null @@ -1,372 +0,0 @@ -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 deleted file mode 100644 index 78606cba..00000000 --- a/docs/automation/terraform/md-terraformvyos.md +++ /dev/null @@ -1,31 +0,0 @@ -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 bbc74ea8..7d933306 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -13,7 +13,6 @@ # 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")) @@ -84,23 +83,7 @@ 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', - '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 - ) +exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store', '_include/vyos-1x'] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' @@ -210,32 +193,5 @@ 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): - app.connect('builder-inited', _prefer_webp) - app.connect('build-finished', _copy_md_sources) + pass diff --git a/docs/configexamples/autotest/DHCPRelay_through_GRE/_include/topology.webp b/docs/configexamples/autotest/DHCPRelay_through_GRE/_include/topology.webp Binary files differdeleted file mode 100644 index 592484cb..00000000 --- a/docs/configexamples/autotest/DHCPRelay_through_GRE/_include/topology.webp +++ /dev/null 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 deleted file mode 100644 index 179f7885..00000000 --- a/docs/configexamples/autotest/DHCPRelay_through_GRE/md-DHCPRelay_through_GRE.md +++ /dev/null @@ -1,89 +0,0 @@ -# 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 differdeleted file mode 100644 index f3218799..00000000 --- a/docs/configexamples/autotest/L3VPN_EVPN/_include/topology.webp +++ /dev/null diff --git a/docs/configexamples/autotest/L3VPN_EVPN/md-L3VPN_EVPN.md b/docs/configexamples/autotest/L3VPN_EVPN/md-L3VPN_EVPN.md deleted file mode 100644 index c090c16e..00000000 --- a/docs/configexamples/autotest/L3VPN_EVPN/md-L3VPN_EVPN.md +++ /dev/null @@ -1,245 +0,0 @@ -# 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 differdeleted file mode 100644 index 13bf2d73..00000000 --- a/docs/configexamples/autotest/OpenVPN_with_LDAP/_include/topology.webp +++ /dev/null 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 deleted file mode 100644 index 7e662cfd..00000000 --- a/docs/configexamples/autotest/OpenVPN_with_LDAP/md-OpenVPN_with_LDAP.md +++ /dev/null @@ -1,226 +0,0 @@ -# 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 differdeleted file mode 100644 index 3cc5e992..00000000 --- a/docs/configexamples/autotest/Wireguard/_include/topology.webp +++ /dev/null diff --git a/docs/configexamples/autotest/Wireguard/md-Wireguard.md b/docs/configexamples/autotest/Wireguard/md-Wireguard.md deleted file mode 100644 index ea0ca8e3..00000000 --- a/docs/configexamples/autotest/Wireguard/md-Wireguard.md +++ /dev/null @@ -1,108 +0,0 @@ -# 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 differdeleted file mode 100644 index c3a812ab..00000000 --- a/docs/configexamples/autotest/tunnelbroker/_include/topology.webp +++ /dev/null diff --git a/docs/configexamples/autotest/tunnelbroker/md-tunnelbroker.md b/docs/configexamples/autotest/tunnelbroker/md-tunnelbroker.md deleted file mode 100644 index 8c8eaf78..00000000 --- a/docs/configexamples/autotest/tunnelbroker/md-tunnelbroker.md +++ /dev/null @@ -1,195 +0,0 @@ -# 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 deleted file mode 100644 index d6ac6552..00000000 --- a/docs/configexamples/md-azure-vpn-bgp.md +++ /dev/null @@ -1,162 +0,0 @@ -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 deleted file mode 100644 index e1b69fc3..00000000 --- a/docs/configexamples/md-azure-vpn-dual-bgp.md +++ /dev/null @@ -1,192 +0,0 @@ -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 deleted file mode 100644 index 89a0da8b..00000000 --- a/docs/configexamples/md-bgp-ipv6-unnumbered.md +++ /dev/null @@ -1,170 +0,0 @@ -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 deleted file mode 100644 index 2849a66c..00000000 --- a/docs/configexamples/md-firewall.md +++ /dev/null @@ -1,13 +0,0 @@ -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 deleted file mode 100644 index c7320902..00000000 --- a/docs/configexamples/md-fwall-and-vrf.md +++ /dev/null @@ -1,118 +0,0 @@ -# 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 deleted file mode 100644 index 1a4589dd..00000000 --- a/docs/configexamples/md-ha.md +++ /dev/null @@ -1,572 +0,0 @@ -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 deleted file mode 100644 index ec0a5077..00000000 --- a/docs/configexamples/md-index.md +++ /dev/null @@ -1,54 +0,0 @@ -# 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 deleted file mode 100644 index 62eec937..00000000 --- a/docs/configexamples/md-inter-vrf-routing-vrf-lite.md +++ /dev/null @@ -1,910 +0,0 @@ -# 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 deleted file mode 100644 index 7410a43f..00000000 --- a/docs/configexamples/md-ipsec-cisco-policy-based.md +++ /dev/null @@ -1,423 +0,0 @@ -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 deleted file mode 100644 index 181a9d56..00000000 --- a/docs/configexamples/md-ipsec-cisco-route-based.md +++ /dev/null @@ -1,469 +0,0 @@ -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 deleted file mode 100644 index 191d59f9..00000000 --- a/docs/configexamples/md-ipsec-pa-route-based.md +++ /dev/null @@ -1,462 +0,0 @@ -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 deleted file mode 100644 index 02269386..00000000 --- a/docs/configexamples/md-l3vpn-hub-and-spoke.md +++ /dev/null @@ -1,1135 +0,0 @@ -# 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 deleted file mode 100644 index 125f5ab6..00000000 --- a/docs/configexamples/md-lac-lns.md +++ /dev/null @@ -1,167 +0,0 @@ -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 deleted file mode 100644 index 79b096ce..00000000 --- a/docs/configexamples/md-nmp.md +++ /dev/null @@ -1,42 +0,0 @@ -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 deleted file mode 100644 index 8fe92b39..00000000 --- a/docs/configexamples/md-ospf-unnumbered.md +++ /dev/null @@ -1,114 +0,0 @@ -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 deleted file mode 100644 index 7d158031..00000000 --- a/docs/configexamples/md-pppoe-ipv6-basic.md +++ /dev/null @@ -1,104 +0,0 @@ -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 deleted file mode 100644 index 520200c5..00000000 --- a/docs/configexamples/md-qos.md +++ /dev/null @@ -1,144 +0,0 @@ -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 deleted file mode 100644 index 707d4f4b..00000000 --- a/docs/configexamples/md-segment-routing-isis.md +++ /dev/null @@ -1,273 +0,0 @@ -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 deleted file mode 100644 index 4e146838..00000000 --- a/docs/configexamples/md-wan-load-balancing.md +++ /dev/null @@ -1,164 +0,0 @@ -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 deleted file mode 100644 index afa8c940..00000000 --- a/docs/configexamples/md-zone-policy.md +++ /dev/null @@ -1,416 +0,0 @@ -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 deleted file mode 100644 index 1cd322f9..00000000 --- a/docs/configuration/container/md-index.md +++ /dev/null @@ -1,512 +0,0 @@ -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 deleted file mode 100644 index fad81412..00000000 --- a/docs/configuration/firewall/md-bridge.md +++ /dev/null @@ -1,683 +0,0 @@ -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 deleted file mode 100644 index e423eb59..00000000 --- a/docs/configuration/firewall/md-flowtables.md +++ /dev/null @@ -1,229 +0,0 @@ -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 deleted file mode 100644 index dc860894..00000000 --- a/docs/configuration/firewall/md-global-options.md +++ /dev/null @@ -1,236 +0,0 @@ -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 deleted file mode 100644 index 926b503d..00000000 --- a/docs/configuration/firewall/md-groups.md +++ /dev/null @@ -1,561 +0,0 @@ -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 deleted file mode 100644 index a7511536..00000000 --- a/docs/configuration/firewall/md-index.md +++ /dev/null @@ -1,181 +0,0 @@ -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 deleted file mode 100644 index 7ac0ff49..00000000 --- a/docs/configuration/firewall/md-ipv4.md +++ /dev/null @@ -1,2657 +0,0 @@ -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 deleted file mode 100644 index a6c2aabf..00000000 --- a/docs/configuration/firewall/md-ipv6.md +++ /dev/null @@ -1,2638 +0,0 @@ -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 deleted file mode 100644 index 6eb27b6c..00000000 --- a/docs/configuration/firewall/md-zone.md +++ /dev/null @@ -1,209 +0,0 @@ -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 deleted file mode 100644 index 6d66603e..00000000 --- a/docs/configuration/highavailability/md-index.md +++ /dev/null @@ -1,525 +0,0 @@ -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 deleted file mode 100644 index 837b61c5..00000000 --- a/docs/configuration/interfaces/md-bonding.md +++ /dev/null @@ -1,731 +0,0 @@ -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 deleted file mode 100644 index 732ea8e9..00000000 --- a/docs/configuration/interfaces/md-bridge.md +++ /dev/null @@ -1,405 +0,0 @@ -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 deleted file mode 100644 index ec79579e..00000000 --- a/docs/configuration/interfaces/md-dummy.md +++ /dev/null @@ -1,110 +0,0 @@ -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 deleted file mode 100644 index 4b0ee7f5..00000000 --- a/docs/configuration/interfaces/md-ethernet.md +++ /dev/null @@ -1,357 +0,0 @@ -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 deleted file mode 100644 index 8bb145df..00000000 --- a/docs/configuration/interfaces/md-geneve.md +++ /dev/null @@ -1,102 +0,0 @@ -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 deleted file mode 100644 index 5d66b2d0..00000000 --- a/docs/configuration/interfaces/md-index.md +++ /dev/null @@ -1,25 +0,0 @@ -# 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 deleted file mode 100644 index 84e190f5..00000000 --- a/docs/configuration/interfaces/md-l2tpv3.md +++ /dev/null @@ -1,206 +0,0 @@ -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 deleted file mode 100644 index 1d8d6766..00000000 --- a/docs/configuration/interfaces/md-loopback.md +++ /dev/null @@ -1,97 +0,0 @@ -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 deleted file mode 100644 index 17dfff1c..00000000 --- a/docs/configuration/interfaces/md-macsec.md +++ /dev/null @@ -1,332 +0,0 @@ -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 deleted file mode 100644 index b9df5971..00000000 --- a/docs/configuration/interfaces/md-openvpn.md +++ /dev/null @@ -1,924 +0,0 @@ -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 deleted file mode 100644 index f228aab2..00000000 --- a/docs/configuration/interfaces/md-pppoe.md +++ /dev/null @@ -1,562 +0,0 @@ -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 deleted file mode 100644 index a58ccfc6..00000000 --- a/docs/configuration/interfaces/md-pseudo-ethernet.md +++ /dev/null @@ -1,67 +0,0 @@ -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 deleted file mode 100644 index d5c19d8f..00000000 --- a/docs/configuration/interfaces/md-sstp-client.md +++ /dev/null @@ -1,225 +0,0 @@ -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 deleted file mode 100644 index 53ba1a3e..00000000 --- a/docs/configuration/interfaces/md-tunnel.md +++ /dev/null @@ -1,283 +0,0 @@ -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 deleted file mode 100644 index 2d3f4c63..00000000 --- a/docs/configuration/interfaces/md-virtual-ethernet.md +++ /dev/null @@ -1,127 +0,0 @@ -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 deleted file mode 100644 index 0d924f65..00000000 --- a/docs/configuration/interfaces/md-vti.md +++ /dev/null @@ -1,46 +0,0 @@ -# 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 deleted file mode 100644 index 9a991c08..00000000 --- a/docs/configuration/interfaces/md-vxlan.md +++ /dev/null @@ -1,396 +0,0 @@ -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 deleted file mode 100644 index 4e2689f5..00000000 --- a/docs/configuration/interfaces/md-wireguard.md +++ /dev/null @@ -1,480 +0,0 @@ -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 deleted file mode 100644 index 4a09b78b..00000000 --- a/docs/configuration/interfaces/md-wireless.md +++ /dev/null @@ -1,823 +0,0 @@ -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 deleted file mode 100644 index 2475e809..00000000 --- a/docs/configuration/interfaces/md-wwan.md +++ /dev/null @@ -1,390 +0,0 @@ -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 deleted file mode 100644 index 5526c11d..00000000 --- a/docs/configuration/loadbalancing/md-index.md +++ /dev/null @@ -1,8 +0,0 @@ -# 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 deleted file mode 100644 index 0e4ebe77..00000000 --- a/docs/configuration/loadbalancing/md-reverse-proxy.md +++ /dev/null @@ -1,552 +0,0 @@ -# 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 deleted file mode 100644 index f82c7e4b..00000000 --- a/docs/configuration/loadbalancing/md-wan.md +++ /dev/null @@ -1,320 +0,0 @@ -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 deleted file mode 100644 index 8371199f..00000000 --- a/docs/configuration/md-index.md +++ /dev/null @@ -1,22 +0,0 @@ -# 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 deleted file mode 100644 index ef73db30..00000000 --- a/docs/configuration/nat/md-index.md +++ /dev/null @@ -1,9 +0,0 @@ -# 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 deleted file mode 100644 index 627f84c1..00000000 --- a/docs/configuration/nat/md-nat44.md +++ /dev/null @@ -1,844 +0,0 @@ -# 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 deleted file mode 100644 index 3cc9b34d..00000000 --- a/docs/configuration/nat/md-nat64.md +++ /dev/null @@ -1,68 +0,0 @@ -# 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 deleted file mode 100644 index 619bbd49..00000000 --- a/docs/configuration/nat/md-nat66.md +++ /dev/null @@ -1,221 +0,0 @@ -# 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 deleted file mode 100644 index 15efb7a2..00000000 --- a/docs/configuration/pki/md-index.md +++ /dev/null @@ -1,662 +0,0 @@ -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 deleted file mode 100644 index 4a1468b0..00000000 --- a/docs/configuration/policy/md-access-list.md +++ /dev/null @@ -1,96 +0,0 @@ -# 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 deleted file mode 100644 index 5fdebe29..00000000 --- a/docs/configuration/policy/md-as-path-list.md +++ /dev/null @@ -1,48 +0,0 @@ -# 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 deleted file mode 100644 index 943d59ca..00000000 --- a/docs/configuration/policy/md-community-list.md +++ /dev/null @@ -1,50 +0,0 @@ -# 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 deleted file mode 100644 index 9b2717cb..00000000 --- a/docs/configuration/policy/md-examples.md +++ /dev/null @@ -1,201 +0,0 @@ -# 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 deleted file mode 100644 index d05315dd..00000000 --- a/docs/configuration/policy/md-extcommunity-list.md +++ /dev/null @@ -1,55 +0,0 @@ -# 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 deleted file mode 100644 index 91e20aa7..00000000 --- a/docs/configuration/policy/md-index.md +++ /dev/null @@ -1,46 +0,0 @@ -: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 deleted file mode 100644 index 00888140..00000000 --- a/docs/configuration/policy/md-large-community-list.md +++ /dev/null @@ -1,51 +0,0 @@ -# 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 deleted file mode 100644 index 17afb7f8..00000000 --- a/docs/configuration/policy/md-local-route.md +++ /dev/null @@ -1,73 +0,0 @@ -# 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 deleted file mode 100644 index d0490249..00000000 --- a/docs/configuration/policy/md-prefix-list.md +++ /dev/null @@ -1,190 +0,0 @@ -# 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 deleted file mode 100644 index 4c356e5d..00000000 --- a/docs/configuration/policy/md-route-map.md +++ /dev/null @@ -1,651 +0,0 @@ -# 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 deleted file mode 100644 index efd0eedf..00000000 --- a/docs/configuration/policy/md-route.md +++ /dev/null @@ -1,647 +0,0 @@ -# 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 deleted file mode 100644 index 8bca4a71..00000000 --- a/docs/configuration/protocols/md-babel.md +++ /dev/null @@ -1,294 +0,0 @@ -# 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 deleted file mode 100644 index 58582008..00000000 --- a/docs/configuration/protocols/md-bfd.md +++ /dev/null @@ -1,259 +0,0 @@ -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 deleted file mode 100644 index b5a91b3f..00000000 --- a/docs/configuration/protocols/md-bgp.md +++ /dev/null @@ -1,1683 +0,0 @@ -# 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 deleted file mode 100644 index 06ce402d..00000000 --- a/docs/configuration/protocols/md-failover.md +++ /dev/null @@ -1,131 +0,0 @@ -# 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 deleted file mode 100644 index f35f1747..00000000 --- a/docs/configuration/protocols/md-igmp-proxy.md +++ /dev/null @@ -1,88 +0,0 @@ -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 deleted file mode 100644 index 60e20bc9..00000000 --- a/docs/configuration/protocols/md-index.md +++ /dev/null @@ -1,20 +0,0 @@ -# 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 deleted file mode 100644 index 8081860a..00000000 --- a/docs/configuration/protocols/md-isis.md +++ /dev/null @@ -1,662 +0,0 @@ -# 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 deleted file mode 100644 index 8b729d8c..00000000 --- a/docs/configuration/protocols/md-mpls.md +++ /dev/null @@ -1,419 +0,0 @@ -# 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 deleted file mode 100644 index a70bd840..00000000 --- a/docs/configuration/protocols/md-ospf.md +++ /dev/null @@ -1,1772 +0,0 @@ -# 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 deleted file mode 100644 index 2f31de95..00000000 --- a/docs/configuration/protocols/md-pim.md +++ /dev/null @@ -1,345 +0,0 @@ -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 deleted file mode 100644 index 6b3c00fc..00000000 --- a/docs/configuration/protocols/md-pim6.md +++ /dev/null @@ -1,122 +0,0 @@ -# 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 deleted file mode 100644 index 1bd580ab..00000000 --- a/docs/configuration/protocols/md-rip.md +++ /dev/null @@ -1,361 +0,0 @@ -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 deleted file mode 100644 index f41e4d59..00000000 --- a/docs/configuration/protocols/md-rpki.md +++ /dev/null @@ -1,238 +0,0 @@ -# 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 deleted file mode 100644 index 24516103..00000000 --- a/docs/configuration/protocols/md-segment-routing.md +++ /dev/null @@ -1,442 +0,0 @@ -# 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 deleted file mode 100644 index dca76d53..00000000 --- a/docs/configuration/protocols/md-static.md +++ /dev/null @@ -1,322 +0,0 @@ -# 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 deleted file mode 100644 index 2214ade3..00000000 --- a/docs/configuration/service/md-broadcast-relay.md +++ /dev/null @@ -1,94 +0,0 @@ -# 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 deleted file mode 100644 index db803cb4..00000000 --- a/docs/configuration/service/md-config-sync.md +++ /dev/null @@ -1,121 +0,0 @@ -# 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 deleted file mode 100644 index 011080a5..00000000 --- a/docs/configuration/service/md-conntrack-sync.md +++ /dev/null @@ -1,380 +0,0 @@ -# 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 deleted file mode 100644 index 2e28b85d..00000000 --- a/docs/configuration/service/md-console-server.md +++ /dev/null @@ -1,206 +0,0 @@ -# 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 deleted file mode 100644 index 2cf304bf..00000000 --- a/docs/configuration/service/md-dhcp-relay.md +++ /dev/null @@ -1,242 +0,0 @@ -# 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 deleted file mode 100644 index f77daec3..00000000 --- a/docs/configuration/service/md-dhcp-server.md +++ /dev/null @@ -1,1128 +0,0 @@ -# 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 deleted file mode 100644 index 08a24b48..00000000 --- a/docs/configuration/service/md-dns.md +++ /dev/null @@ -1,574 +0,0 @@ -# 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 deleted file mode 100644 index 5280c43a..00000000 --- a/docs/configuration/service/md-eventhandler.md +++ /dev/null @@ -1,150 +0,0 @@ -# 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 deleted file mode 100644 index e68bcd50..00000000 --- a/docs/configuration/service/md-https.md +++ /dev/null @@ -1,122 +0,0 @@ -# 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 deleted file mode 100644 index b22c93dd..00000000 --- a/docs/configuration/service/md-ids.md +++ /dev/null @@ -1,228 +0,0 @@ -# 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 deleted file mode 100644 index 420efc6d..00000000 --- a/docs/configuration/service/md-index.md +++ /dev/null @@ -1,28 +0,0 @@ -# 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 deleted file mode 100644 index dc66163d..00000000 --- a/docs/configuration/service/md-ipoe-server.md +++ /dev/null @@ -1,656 +0,0 @@ -# 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 deleted file mode 100644 index 84d734a0..00000000 --- a/docs/configuration/service/md-lldp.md +++ /dev/null @@ -1,176 +0,0 @@ -# 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 deleted file mode 100644 index 504843d4..00000000 --- a/docs/configuration/service/md-mdns.md +++ /dev/null @@ -1,162 +0,0 @@ -# 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 deleted file mode 100644 index 8dff341a..00000000 --- a/docs/configuration/service/md-monitoring.md +++ /dev/null @@ -1,230 +0,0 @@ -# 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 deleted file mode 100644 index 871f5fec..00000000 --- a/docs/configuration/service/md-ntp.md +++ /dev/null @@ -1,136 +0,0 @@ -# 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 deleted file mode 100644 index 3c77e425..00000000 --- a/docs/configuration/service/md-pppoe-server.md +++ /dev/null @@ -1,957 +0,0 @@ -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 deleted file mode 100644 index 3367e7aa..00000000 --- a/docs/configuration/service/md-router-advert.md +++ /dev/null @@ -1,241 +0,0 @@ -# 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 deleted file mode 100644 index 8783d0b4..00000000 --- a/docs/configuration/service/md-salt-minion.md +++ /dev/null @@ -1,58 +0,0 @@ -# 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 deleted file mode 100644 index 84877df3..00000000 --- a/docs/configuration/service/md-snmp.md +++ /dev/null @@ -1,252 +0,0 @@ -# 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 deleted file mode 100644 index 12384878..00000000 --- a/docs/configuration/service/md-ssh.md +++ /dev/null @@ -1,374 +0,0 @@ -# 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 deleted file mode 100644 index 1d8e6e15..00000000 --- a/docs/configuration/service/md-tftp-server.md +++ /dev/null @@ -1,105 +0,0 @@ -# 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 deleted file mode 100644 index 4a881cea..00000000 --- a/docs/configuration/service/md-webproxy.md +++ /dev/null @@ -1,536 +0,0 @@ -# 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 deleted file mode 100644 index 21096988..00000000 --- a/docs/configuration/system/md-acceleration.md +++ /dev/null @@ -1,168 +0,0 @@ -# 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 deleted file mode 100644 index 2d5afdfd..00000000 --- a/docs/configuration/system/md-conntrack.md +++ /dev/null @@ -1,473 +0,0 @@ -# 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 deleted file mode 100644 index 3a58301d..00000000 --- a/docs/configuration/system/md-console.md +++ /dev/null @@ -1,59 +0,0 @@ -# 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 deleted file mode 100644 index c973dc09..00000000 --- a/docs/configuration/system/md-default-route.md +++ /dev/null @@ -1,48 +0,0 @@ -# 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 deleted file mode 100644 index 3a66fce5..00000000 --- a/docs/configuration/system/md-flow-accounting.md +++ /dev/null @@ -1,312 +0,0 @@ -# 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 deleted file mode 100644 index 7116d1de..00000000 --- a/docs/configuration/system/md-frr.md +++ /dev/null @@ -1,50 +0,0 @@ -# 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 deleted file mode 100644 index ebb83a5f..00000000 --- a/docs/configuration/system/md-host-name.md +++ /dev/null @@ -1,86 +0,0 @@ -# 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 deleted file mode 100644 index ea77a2c6..00000000 --- a/docs/configuration/system/md-index.md +++ /dev/null @@ -1,31 +0,0 @@ -# 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 deleted file mode 100644 index cbdc53c4..00000000 --- a/docs/configuration/system/md-ip.md +++ /dev/null @@ -1,132 +0,0 @@ -# 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 deleted file mode 100644 index 47b775e6..00000000 --- a/docs/configuration/system/md-ipv6.md +++ /dev/null @@ -1,278 +0,0 @@ -# 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 deleted file mode 100644 index b5a50b3c..00000000 --- a/docs/configuration/system/md-lcd.md +++ /dev/null @@ -1,52 +0,0 @@ -# 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 deleted file mode 100644 index 253e3673..00000000 --- a/docs/configuration/system/md-login.md +++ /dev/null @@ -1,549 +0,0 @@ -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 deleted file mode 100644 index ea544b16..00000000 --- a/docs/configuration/system/md-name-server.md +++ /dev/null @@ -1,81 +0,0 @@ -# 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 deleted file mode 100644 index 8ad69d76..00000000 --- a/docs/configuration/system/md-option.md +++ /dev/null @@ -1,262 +0,0 @@ -# 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 deleted file mode 100644 index 911392ad..00000000 --- a/docs/configuration/system/md-proxy.md +++ /dev/null @@ -1,40 +0,0 @@ -# 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 deleted file mode 100644 index b64de63f..00000000 --- a/docs/configuration/system/md-sflow.md +++ /dev/null @@ -1,81 +0,0 @@ -# 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 deleted file mode 100644 index 2786ceea..00000000 --- a/docs/configuration/system/md-sysctl.md +++ /dev/null @@ -1,12 +0,0 @@ -# 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 deleted file mode 100644 index fc4d5eef..00000000 --- a/docs/configuration/system/md-syslog.md +++ /dev/null @@ -1,606 +0,0 @@ -# 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 deleted file mode 100644 index 9a43b430..00000000 --- a/docs/configuration/system/md-task-scheduler.md +++ /dev/null @@ -1,70 +0,0 @@ -# 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 deleted file mode 100644 index 20f24b41..00000000 --- a/docs/configuration/system/md-time-zone.md +++ /dev/null @@ -1,18 +0,0 @@ -# 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 deleted file mode 100644 index 4e0460ac..00000000 --- a/docs/configuration/system/md-updates.md +++ /dev/null @@ -1,39 +0,0 @@ -# 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 deleted file mode 100644 index de67ee11..00000000 --- a/docs/configuration/trafficpolicy/md-index.md +++ /dev/null @@ -1,1738 +0,0 @@ -# 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 deleted file mode 100644 index f8ef0e17..00000000 --- a/docs/configuration/vpn/ipsec/md-index.md +++ /dev/null @@ -1,15 +0,0 @@ -# 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 deleted file mode 100644 index 1fbb5974..00000000 --- a/docs/configuration/vpn/ipsec/md-ipsec_general.md +++ /dev/null @@ -1,399 +0,0 @@ -# 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 deleted file mode 100644 index 356ae23a..00000000 --- a/docs/configuration/vpn/ipsec/md-remoteaccess_ipsec.md +++ /dev/null @@ -1,185 +0,0 @@ -# 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 deleted file mode 100644 index 451ea1be..00000000 --- a/docs/configuration/vpn/ipsec/md-site2site_ipsec.md +++ /dev/null @@ -1,944 +0,0 @@ -# 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 deleted file mode 100644 index 14161e7f..00000000 --- a/docs/configuration/vpn/ipsec/md-troubleshooting_ipsec.md +++ /dev/null @@ -1,303 +0,0 @@ -# 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 deleted file mode 100644 index c335d306..00000000 --- a/docs/configuration/vpn/md-dmvpn.md +++ /dev/null @@ -1,406 +0,0 @@ -# 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 deleted file mode 100644 index b9aa768e..00000000 --- a/docs/configuration/vpn/md-index.md +++ /dev/null @@ -1,20 +0,0 @@ -# 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 deleted file mode 100644 index 1b71c71f..00000000 --- a/docs/configuration/vpn/md-l2tp.md +++ /dev/null @@ -1,837 +0,0 @@ -# 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 deleted file mode 100644 index 91310cdd..00000000 --- a/docs/configuration/vpn/md-openconnect.md +++ /dev/null @@ -1,329 +0,0 @@ -# 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 deleted file mode 100644 index 2f973da2..00000000 --- a/docs/configuration/vpn/md-pptp.md +++ /dev/null @@ -1,808 +0,0 @@ -# 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 deleted file mode 100644 index 7d54126f..00000000 --- a/docs/configuration/vpn/md-rsa-keys.md +++ /dev/null @@ -1,105 +0,0 @@ -# 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 deleted file mode 100644 index 8ac7d665..00000000 --- a/docs/configuration/vpn/md-sstp.md +++ /dev/null @@ -1,919 +0,0 @@ -# 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 deleted file mode 100644 index 7ab24fc2..00000000 --- a/docs/configuration/vrf/md-index.md +++ /dev/null @@ -1,694 +0,0 @@ -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 deleted file mode 100644 index c8074bd7..00000000 --- a/docs/contributing/md-build-vyos.md +++ /dev/null @@ -1,876 +0,0 @@ -# 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 deleted file mode 100644 index b7e66470..00000000 --- a/docs/contributing/md-debugging.md +++ /dev/null @@ -1,189 +0,0 @@ -# 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 deleted file mode 100644 index cc9fae00..00000000 --- a/docs/contributing/md-development.md +++ /dev/null @@ -1,708 +0,0 @@ -# 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 deleted file mode 100644 index c481fec5..00000000 --- a/docs/contributing/md-issues-features.md +++ /dev/null @@ -1,60 +0,0 @@ -# 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 deleted file mode 100644 index 4f406e05..00000000 --- a/docs/contributing/md-testing.md +++ /dev/null @@ -1,225 +0,0 @@ -# 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 deleted file mode 100644 index bc0eeed1..00000000 --- a/docs/contributing/md-upstream-packages.md +++ /dev/null @@ -1,77 +0,0 @@ -# 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 deleted file mode 100644 index 8cdfda44..00000000 --- a/docs/installation/cloud/md-aws-ha.md +++ /dev/null @@ -1,132 +0,0 @@ -\########## -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 deleted file mode 100644 index 87effb97..00000000 --- a/docs/installation/cloud/md-aws-to-azure.md +++ /dev/null @@ -1,177 +0,0 @@ -\########## -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 deleted file mode 100644 index 523fd280..00000000 --- a/docs/installation/cloud/md-aws.md +++ /dev/null @@ -1,722 +0,0 @@ -\########## -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 deleted file mode 100644 index 4a77565d..00000000 --- a/docs/installation/cloud/md-azure-ha.md +++ /dev/null @@ -1,130 +0,0 @@ -\########## -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 deleted file mode 100644 index 8489a532..00000000 --- a/docs/installation/cloud/md-azure.md +++ /dev/null @@ -1,449 +0,0 @@ -\########## -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 deleted file mode 100644 index b30d6494..00000000 --- a/docs/installation/cloud/md-gcp.md +++ /dev/null @@ -1,298 +0,0 @@ -\##################### -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 deleted file mode 100644 index 1c1e1ed6..00000000 --- a/docs/installation/cloud/md-index.md +++ /dev/null @@ -1,13 +0,0 @@ -# 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 deleted file mode 100644 index 9ed07ff9..00000000 --- a/docs/installation/cloud/md-oracel.md +++ /dev/null @@ -1,5 +0,0 @@ -# Oracle - -## References - -<https://www.oracle.com/cloud/> diff --git a/docs/installation/md-image.md b/docs/installation/md-image.md deleted file mode 100644 index fb57d73f..00000000 --- a/docs/installation/md-image.md +++ /dev/null @@ -1,131 +0,0 @@ -# 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 deleted file mode 100644 index 2e8e93c9..00000000 --- a/docs/installation/md-index.md +++ /dev/null @@ -1,34 +0,0 @@ -# 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 deleted file mode 100644 index 947d71d7..00000000 --- a/docs/installation/md-install.md +++ /dev/null @@ -1,504 +0,0 @@ -# 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 deleted file mode 100644 index cff79228..00000000 --- a/docs/installation/md-update.md +++ /dev/null @@ -1,110 +0,0 @@ -# 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 deleted file mode 100644 index aaf2c78d..00000000 --- a/docs/installation/md-vyos-on-baremetal.md +++ /dev/null @@ -1,609 +0,0 @@ -# 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 deleted file mode 100644 index 964b9f64..00000000 --- a/docs/installation/virtual/md-docker.md +++ /dev/null @@ -1,65 +0,0 @@ -# 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 deleted file mode 100644 index 3e32e61f..00000000 --- a/docs/installation/virtual/md-eve-ng.md +++ /dev/null @@ -1,5 +0,0 @@ -# EVE-NG - -## References - -<https://www.eve-ng.net/> diff --git a/docs/installation/virtual/md-gns3.md b/docs/installation/virtual/md-gns3.md deleted file mode 100644 index b1bb2a1d..00000000 --- a/docs/installation/virtual/md-gns3.md +++ /dev/null @@ -1,208 +0,0 @@ -# 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 deleted file mode 100644 index 7ed572e4..00000000 --- a/docs/installation/virtual/md-index.md +++ /dev/null @@ -1,12 +0,0 @@ -# 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 deleted file mode 100644 index 04a05ad0..00000000 --- a/docs/installation/virtual/md-libvirt.md +++ /dev/null @@ -1,176 +0,0 @@ -# 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 deleted file mode 100644 index da4bd03b..00000000 --- a/docs/installation/virtual/md-proxmox.md +++ /dev/null @@ -1,43 +0,0 @@ -# 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 deleted file mode 100644 index 6d693455..00000000 --- a/docs/installation/virtual/md-vmware.md +++ /dev/null @@ -1,35 +0,0 @@ -# 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 deleted file mode 100644 index 51e09857..00000000 --- a/docs/introducing/md-about.md +++ /dev/null @@ -1,23 +0,0 @@ -# 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 deleted file mode 100644 index c97b59d4..00000000 --- a/docs/introducing/md-history.md +++ /dev/null @@ -1,122 +0,0 @@ -# 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 deleted file mode 100644 index 102a00b9..00000000 --- a/docs/md-404.md +++ /dev/null @@ -1,11 +0,0 @@ -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 deleted file mode 100644 index 7a5af126..00000000 --- a/docs/md-cli.md +++ /dev/null @@ -1,1178 +0,0 @@ -# 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 deleted file mode 100644 index 370f35ce..00000000 --- a/docs/md-coverage.md +++ /dev/null @@ -1,51 +0,0 @@ -# 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 deleted file mode 100644 index 4603a49b..00000000 --- a/docs/md-documentation.md +++ /dev/null @@ -1,430 +0,0 @@ -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 deleted file mode 100644 index cc2067b3..00000000 --- a/docs/md-index.md +++ /dev/null @@ -1,110 +0,0 @@ -# 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 deleted file mode 100644 index 36140bc5..00000000 --- a/docs/md-quick-start.md +++ /dev/null @@ -1,362 +0,0 @@ -# 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 deleted file mode 100644 index 73a8f62f..00000000 --- a/docs/operation/md-boot-options.md +++ /dev/null @@ -1,56 +0,0 @@ -# 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 deleted file mode 100644 index eed21dcd..00000000 --- a/docs/operation/md-index.md +++ /dev/null @@ -1,10 +0,0 @@ -# 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 deleted file mode 100644 index c6f663a5..00000000 --- a/docs/operation/md-information.md +++ /dev/null @@ -1,171 +0,0 @@ -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 deleted file mode 100644 index 295de05c..00000000 --- a/docs/operation/md-password-recovery.md +++ /dev/null @@ -1,22 +0,0 @@ -# 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 deleted file mode 100644 index 2009779d..00000000 --- a/docs/operation/md-raid.md +++ /dev/null @@ -1,265 +0,0 @@ -# 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 deleted file mode 100644 index f3756c26..00000000 --- a/docs/troubleshooting/md-index.md +++ /dev/null @@ -1,436 +0,0 @@ -# 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` |
