diff options
| author | Yuriy Andamasov <yuriy@vyos.io> | 2026-05-06 14:41:08 +0300 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2026-05-06 12:41:08 +0100 |
| commit | 22e34ce5aee24d2fd11f8205522ab7ecdb3c4c5e (patch) | |
| tree | 8d97f7766d9bbd2d0e3a55e5643a60b387308675 | |
| parent | c21b38dbe24088eaca73dbc8030cfebc898d2186 (diff) | |
| download | vyos-documentation-22e34ce5aee24d2fd11f8205522ab7ecdb3c4c5e.tar.gz vyos-documentation-22e34ce5aee24d2fd11f8205522ab7ecdb3c4c5e.zip | |
Add incremental RST-to-MyST swap mechanism (sagitta) (#1868)
* feat(swap-sagitta): add incremental RST-to-MyST swap mechanism
Backport of the swap mechanism from feat/incremental-myst-swap onto
the sagitta release branch. Built directly on top of origin/sagitta,
so the underlying RST tree is sagitta's (not current's).
Mechanism:
- scripts/import_myst.py — import md from myst/* with md- prefix
- scripts/swap_sources.py — rename md-{name}.md → {name}.md before
Sphinx builds, restore after; writes _build/_swap_state.json and
_build/_swap_exclude.txt
- docs/Makefile — html/dirhtml/pdf/livehtml all run swap → build →
trap restore; explicit `swap` and `restore` targets too
- docs/conf.py — MyST extensions enabled; swap exclude_patterns
loader; _prefer_webp builder hook so html prefers webp over png
Content:
- 202 md-prefixed pages from origin/myst/sagitta (md-{name}.md
alongside each {name}.rst counterpart)
- 1 plain MyST-only page from myst/sagitta where no .rst exists
(already at canonical name on sagitta: docs/copyright.md)
- 240 .webp images from myst/sagitta (added alongside the existing
PNG/JPG so RST builds keep their assets)
- docs/_swap.txt populated with all 202 stems → MyST is served by
default, revert a page by removing its stem from _swap.txt
🤖 Generated by [robots](https://vyos.io)
* feat(conf): copy .md sources into HTML output for plain-text serving
Adds a build-finished hook that mirrors every .md file from the Sphinx
source tree into the HTML output directory verbatim, making unrendered
MyST sources accessible alongside HTML renders at the same URL path.
🤖 Generated by [robots](https://vyos.io)
* docs: address review feedback (backport from PR #1857)
Fix conversion artifacts, typos, and technical inaccuracies applicable
to the sagitta branch: curly quotes, typos (deamonless, cammans,
amdifferent, trough), incorrect firewall command paths, missing closing
brace in zone-policy, peer name inconsistencies, hardcoded passwords
replaced with vault references, and md-*.md exclusion in conf.py.
🤖 Generated by [robots](https://vyos.io)
* docs: port .readthedocs.yml jobs, _ext/vyos.py fallback and swap-script tests from PR #1857
Parity backport from PR #1857 (current) — three pieces were missing on
sagitta.
- .readthedocs.yml: add build.jobs.pre_build / post_build hooks that run
scripts/swap_sources.py --swap before the Sphinx build and --restore
after. Without this, the swap mechanism ships but never runs on RTD
builds for this branch — the swap is a silent no-op.
- docs/_ext/vyos.py: CmdInclude.run() now falls back to nested_parse()
when self.state._renderer is not present. Required for cfgcmd /
opcmd / cmdincludemd directives to render correctly when included
from MyST pages (the swap mechanism's whole point). Sagitta-only
delta on _ext/vyos.py (the path = str(path) line on 224) is
intentionally untouched.
- tests/test_import_myst.py, tests/test_swap_sources.py: tests for the
swap scripts. The scripts on this branch are byte-identical to
current's, so the same tests apply. Travels with the branch so CI
catches per-branch regressions if the scripts ever drift.
🤖 Generated by [robots](https://vyos.io)
* fix(conf): skip md-*.md staging files in _copy_md_sources
Agent-Logs-Url: https://github.com/vyos/vyos-documentation/sessions/919695a7-688d-41b9-89f0-540684625dbc
Co-authored-by: andamasov <12631358+andamasov@users.noreply.github.com>
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: andamasov <12631358+andamasov@users.noreply.github.com>
451 files changed, 65700 insertions, 14 deletions
diff --git a/.readthedocs.yml b/.readthedocs.yml index f0ea8c49..6539873e 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -8,6 +8,11 @@ build: os: ubuntu-22.04 tools: python: "3.10" + jobs: + pre_build: + - python3 scripts/swap_sources.py --swap + post_build: + - python3 scripts/swap_sources.py --restore # Build documentation in the docs/ directory with Sphinx sphinx: diff --git a/docs/Makefile b/docs/Makefile index cb6226af..b0068b1a 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -12,22 +12,43 @@ AUTOHOST = 0.0.0.0 AUTOPORT = 8000 AUTOOPTS = --watch . +SWAP = python3 ../scripts/swap_sources.py + # Put it first so that "make" without argument is like "make help". help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -.PHONY: help Makefile +.PHONY: help Makefile swap restore html dirhtml pdf livehtml defaultvalue -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) +swap: + $(SWAP) --swap -livehtml: - sphinx-autobuild --host $(AUTOHOST) --port $(AUTOPORT) $(AUTOOPTS) \ - "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) +restore: + $(SWAP) --restore + +html: swap + @trap '$(SWAP) --restore' EXIT; \ + $(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +dirhtml: swap + @trap '$(SWAP) --restore' EXIT; \ + $(SPHINXBUILD) -M dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) +pdf: swap + @trap '$(SWAP) --restore' EXIT; \ + $(SPHINXBUILD) -M latexpdf "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +livehtml: swap + @trap '$(SWAP) --restore' EXIT; \ + sphinx-autobuild --host $(AUTOHOST) --port $(AUTOPORT) \ + --ignore '$(BUILDDIR)/**' \ + --ignore '**/md-*' \ + "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) defaultvalue: export VYOS_DEFAULT=True -defaultvalue: - @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file +defaultvalue: html + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_ext/vyos.py b/docs/_ext/vyos.py index c1a96cd9..ac5b8159 100644 --- a/docs/_ext/vyos.py +++ b/docs/_ext/vyos.py @@ -364,8 +364,18 @@ class CmdInclude(SphinxDirective): line = re.sub('{{\s?var' + str(i) + '\s?}}',value,line) new_include_lines.append(line) - self.state._renderer.nested_render_text(''.join(new_include_lines), self.lineno) - return [] + if hasattr(self.state, '_renderer'): + self.state._renderer.nested_render_text(''.join(new_include_lines), self.lineno) + return [] + from docutils.statemachine import ViewList + from docutils import nodes + content = ''.join(new_include_lines) + vl = ViewList() + for i, line in enumerate(content.splitlines(keepends=False)): + vl.append(line, include_file[1], i) + node = nodes.Element() + self.state.nested_parse(vl, self.content_offset, node, match_titles=True) + return node.children class CfgcmdlistDirective(Directive): diff --git a/docs/_static/images/1u_vyos_back.webp b/docs/_static/images/1u_vyos_back.webp Binary files differnew file mode 100644 index 00000000..b0dbab1d --- /dev/null +++ b/docs/_static/images/1u_vyos_back.webp diff --git a/docs/_static/images/1u_vyos_front.webp b/docs/_static/images/1u_vyos_front.webp Binary files differnew file mode 100644 index 00000000..a47e4f9e --- /dev/null +++ b/docs/_static/images/1u_vyos_front.webp diff --git a/docs/_static/images/1u_vyos_front_10ge_open_1.webp b/docs/_static/images/1u_vyos_front_10ge_open_1.webp Binary files differnew file mode 100644 index 00000000..87f53ddd --- /dev/null +++ b/docs/_static/images/1u_vyos_front_10ge_open_1.webp diff --git a/docs/_static/images/1u_vyos_front_10ge_open_2.webp b/docs/_static/images/1u_vyos_front_10ge_open_2.webp Binary files differnew file mode 100644 index 00000000..1fe5d4ca --- /dev/null +++ b/docs/_static/images/1u_vyos_front_10ge_open_2.webp diff --git a/docs/_static/images/1u_vyos_front_10ge_open_3.webp b/docs/_static/images/1u_vyos_front_10ge_open_3.webp Binary files differnew file mode 100644 index 00000000..2200b448 --- /dev/null +++ b/docs/_static/images/1u_vyos_front_10ge_open_3.webp diff --git a/docs/_static/images/1u_vyos_front_10ge_open_4.webp b/docs/_static/images/1u_vyos_front_10ge_open_4.webp Binary files differnew file mode 100644 index 00000000..fd4a43c7 --- /dev/null +++ b/docs/_static/images/1u_vyos_front_10ge_open_4.webp diff --git a/docs/_static/images/1u_vyos_front_open_1.webp b/docs/_static/images/1u_vyos_front_open_1.webp Binary files differnew file mode 100644 index 00000000..00006feb --- /dev/null +++ b/docs/_static/images/1u_vyos_front_open_1.webp diff --git a/docs/_static/images/1u_vyos_front_open_2.webp b/docs/_static/images/1u_vyos_front_open_2.webp Binary files differnew file mode 100644 index 00000000..ad6fa807 --- /dev/null +++ b/docs/_static/images/1u_vyos_front_open_2.webp diff --git a/docs/_static/images/1u_vyos_front_open_3.webp b/docs/_static/images/1u_vyos_front_open_3.webp Binary files differnew file mode 100644 index 00000000..15edf863 --- /dev/null +++ b/docs/_static/images/1u_vyos_front_open_3.webp diff --git a/docs/_static/images/480px-Acrosser_ANDJ190N1_Back.webp b/docs/_static/images/480px-Acrosser_ANDJ190N1_Back.webp Binary files differnew file mode 100644 index 00000000..10c350cc --- /dev/null +++ b/docs/_static/images/480px-Acrosser_ANDJ190N1_Back.webp diff --git a/docs/_static/images/480px-Acrosser_ANDJ190N1_Front.webp b/docs/_static/images/480px-Acrosser_ANDJ190N1_Front.webp Binary files differnew file mode 100644 index 00000000..0ea695d4 --- /dev/null +++ b/docs/_static/images/480px-Acrosser_ANDJ190N1_Front.webp diff --git a/docs/_static/images/600px-Partaker-i5.webp b/docs/_static/images/600px-Partaker-i5.webp Binary files differnew file mode 100644 index 00000000..d68d5afa --- /dev/null +++ b/docs/_static/images/600px-Partaker-i5.webp diff --git a/docs/_static/images/ESP_AH.webp b/docs/_static/images/ESP_AH.webp Binary files differnew file mode 100644 index 00000000..1c70082e --- /dev/null +++ b/docs/_static/images/ESP_AH.webp diff --git a/docs/_static/images/IPSec_close_action_settings.webp b/docs/_static/images/IPSec_close_action_settings.webp Binary files differnew file mode 100644 index 00000000..6510ba7c --- /dev/null +++ b/docs/_static/images/IPSec_close_action_settings.webp diff --git a/docs/_static/images/L3VPN_hub_and_spoke.webp b/docs/_static/images/L3VPN_hub_and_spoke.webp Binary files differnew file mode 100644 index 00000000..2f3cafcd --- /dev/null +++ b/docs/_static/images/L3VPN_hub_and_spoke.webp diff --git a/docs/_static/images/PA-ESP-group.webp b/docs/_static/images/PA-ESP-group.webp Binary files differnew file mode 100644 index 00000000..1802c511 --- /dev/null +++ b/docs/_static/images/PA-ESP-group.webp diff --git a/docs/_static/images/PA-IKE-GW-1.webp b/docs/_static/images/PA-IKE-GW-1.webp Binary files differnew file mode 100644 index 00000000..ce0a123d --- /dev/null +++ b/docs/_static/images/PA-IKE-GW-1.webp diff --git a/docs/_static/images/PA-IKE-GW-2.webp b/docs/_static/images/PA-IKE-GW-2.webp Binary files differnew file mode 100644 index 00000000..5facbc1e --- /dev/null +++ b/docs/_static/images/PA-IKE-GW-2.webp diff --git a/docs/_static/images/PA-IKE-group.webp b/docs/_static/images/PA-IKE-group.webp Binary files differnew file mode 100644 index 00000000..f244a3fa --- /dev/null +++ b/docs/_static/images/PA-IKE-group.webp diff --git a/docs/_static/images/PA-IPsec-tunnel.webp b/docs/_static/images/PA-IPsec-tunnel.webp Binary files differnew file mode 100644 index 00000000..f8aac9b8 --- /dev/null +++ b/docs/_static/images/PA-IPsec-tunnel.webp diff --git a/docs/_static/images/PA-tunnel-1.webp b/docs/_static/images/PA-tunnel-1.webp Binary files differnew file mode 100644 index 00000000..b72c9364 --- /dev/null +++ b/docs/_static/images/PA-tunnel-1.webp diff --git a/docs/_static/images/PA-tunnel-2.webp b/docs/_static/images/PA-tunnel-2.webp Binary files differnew file mode 100644 index 00000000..8b1bfbf8 --- /dev/null +++ b/docs/_static/images/PA-tunnel-2.webp diff --git a/docs/_static/images/PA-tunnel-3.webp b/docs/_static/images/PA-tunnel-3.webp Binary files differnew file mode 100644 index 00000000..098c3c4d --- /dev/null +++ b/docs/_static/images/PA-tunnel-3.webp diff --git a/docs/_static/images/Wan_load_balancing1.webp b/docs/_static/images/Wan_load_balancing1.webp Binary files differnew file mode 100644 index 00000000..7efb6ab7 --- /dev/null +++ b/docs/_static/images/Wan_load_balancing1.webp diff --git a/docs/_static/images/Wan_load_balancing_exclude1.webp b/docs/_static/images/Wan_load_balancing_exclude1.webp Binary files differnew file mode 100644 index 00000000..cc5fc4d1 --- /dev/null +++ b/docs/_static/images/Wan_load_balancing_exclude1.webp diff --git a/docs/_static/images/apu4_desk_1.webp b/docs/_static/images/apu4_desk_1.webp Binary files differnew file mode 100644 index 00000000..8298c3f2 --- /dev/null +++ b/docs/_static/images/apu4_desk_1.webp diff --git a/docs/_static/images/apu4_desk_2.webp b/docs/_static/images/apu4_desk_2.webp Binary files differnew file mode 100644 index 00000000..ccf54bb8 --- /dev/null +++ b/docs/_static/images/apu4_desk_2.webp diff --git a/docs/_static/images/apu4_desk_3.webp b/docs/_static/images/apu4_desk_3.webp Binary files differnew file mode 100644 index 00000000..965ff112 --- /dev/null +++ b/docs/_static/images/apu4_desk_3.webp diff --git a/docs/_static/images/apu4_desk_4.webp b/docs/_static/images/apu4_desk_4.webp Binary files differnew file mode 100644 index 00000000..2cbc2bd3 --- /dev/null +++ b/docs/_static/images/apu4_desk_4.webp diff --git a/docs/_static/images/apu4_rack_1.webp b/docs/_static/images/apu4_rack_1.webp Binary files differnew file mode 100644 index 00000000..c6bd9229 --- /dev/null +++ b/docs/_static/images/apu4_rack_1.webp diff --git a/docs/_static/images/apu4_rack_2.webp b/docs/_static/images/apu4_rack_2.webp Binary files differnew file mode 100644 index 00000000..f2673488 --- /dev/null +++ b/docs/_static/images/apu4_rack_2.webp diff --git a/docs/_static/images/apu4_rack_3.webp b/docs/_static/images/apu4_rack_3.webp Binary files differnew file mode 100644 index 00000000..a12e7895 --- /dev/null +++ b/docs/_static/images/apu4_rack_3.webp diff --git a/docs/_static/images/apu4_rack_4.webp b/docs/_static/images/apu4_rack_4.webp Binary files differnew file mode 100644 index 00000000..a3ea439c --- /dev/null +++ b/docs/_static/images/apu4_rack_4.webp diff --git a/docs/_static/images/apu4_rack_5.webp b/docs/_static/images/apu4_rack_5.webp Binary files differnew file mode 100644 index 00000000..8310600e --- /dev/null +++ b/docs/_static/images/apu4_rack_5.webp diff --git a/docs/_static/images/apu4_rack_vyos_print.webp b/docs/_static/images/apu4_rack_vyos_print.webp Binary files differnew file mode 100644 index 00000000..61b14f3f --- /dev/null +++ b/docs/_static/images/apu4_rack_vyos_print.webp diff --git a/docs/_static/images/aws.webp b/docs/_static/images/aws.webp Binary files differnew file mode 100644 index 00000000..29fe0684 --- /dev/null +++ b/docs/_static/images/aws.webp diff --git a/docs/_static/images/blueprint-dmvpn.webp b/docs/_static/images/blueprint-dmvpn.webp Binary files differnew file mode 100644 index 00000000..8a3c38aa --- /dev/null +++ b/docs/_static/images/blueprint-dmvpn.webp diff --git a/docs/_static/images/boot-options.webp b/docs/_static/images/boot-options.webp Binary files differnew file mode 100644 index 00000000..9616a336 --- /dev/null +++ b/docs/_static/images/boot-options.webp diff --git a/docs/_static/images/cisco-vpn-ipsec.webp b/docs/_static/images/cisco-vpn-ipsec.webp Binary files differnew file mode 100644 index 00000000..45c570f0 --- /dev/null +++ b/docs/_static/images/cisco-vpn-ipsec.webp diff --git a/docs/_static/images/cloud-aws-eip-01.webp b/docs/_static/images/cloud-aws-eip-01.webp Binary files differnew file mode 100644 index 00000000..a78758fd --- /dev/null +++ b/docs/_static/images/cloud-aws-eip-01.webp diff --git a/docs/_static/images/cloud-aws-eip-02.webp b/docs/_static/images/cloud-aws-eip-02.webp Binary files differnew file mode 100644 index 00000000..39c5c7b7 --- /dev/null +++ b/docs/_static/images/cloud-aws-eip-02.webp diff --git a/docs/_static/images/cloud-aws-eni-01.webp b/docs/_static/images/cloud-aws-eni-01.webp Binary files differnew file mode 100644 index 00000000..51212929 --- /dev/null +++ b/docs/_static/images/cloud-aws-eni-01.webp diff --git a/docs/_static/images/cloud-aws-eni-02.webp b/docs/_static/images/cloud-aws-eni-02.webp Binary files differnew file mode 100644 index 00000000..139313f6 --- /dev/null +++ b/docs/_static/images/cloud-aws-eni-02.webp diff --git a/docs/_static/images/cloud-aws-ha-architecture.webp b/docs/_static/images/cloud-aws-ha-architecture.webp Binary files differnew file mode 100644 index 00000000..3021a6e0 --- /dev/null +++ b/docs/_static/images/cloud-aws-ha-architecture.webp diff --git a/docs/_static/images/cloud-aws-igw-01.webp b/docs/_static/images/cloud-aws-igw-01.webp Binary files differnew file mode 100644 index 00000000..21a90f32 --- /dev/null +++ b/docs/_static/images/cloud-aws-igw-01.webp diff --git a/docs/_static/images/cloud-aws-igw-02.webp b/docs/_static/images/cloud-aws-igw-02.webp Binary files differnew file mode 100644 index 00000000..7f43c4be --- /dev/null +++ b/docs/_static/images/cloud-aws-igw-02.webp diff --git a/docs/_static/images/cloud-aws-keypair-01.webp b/docs/_static/images/cloud-aws-keypair-01.webp Binary files differnew file mode 100644 index 00000000..fdeff52c --- /dev/null +++ b/docs/_static/images/cloud-aws-keypair-01.webp diff --git a/docs/_static/images/cloud-aws-keypair-02.webp b/docs/_static/images/cloud-aws-keypair-02.webp Binary files differnew file mode 100644 index 00000000..89fac0f8 --- /dev/null +++ b/docs/_static/images/cloud-aws-keypair-02.webp diff --git a/docs/_static/images/cloud-aws-keypair-03.webp b/docs/_static/images/cloud-aws-keypair-03.webp Binary files differnew file mode 100644 index 00000000..c71c105c --- /dev/null +++ b/docs/_static/images/cloud-aws-keypair-03.webp diff --git a/docs/_static/images/cloud-aws-keypair-04.webp b/docs/_static/images/cloud-aws-keypair-04.webp Binary files differnew file mode 100644 index 00000000..bcacb96e --- /dev/null +++ b/docs/_static/images/cloud-aws-keypair-04.webp diff --git a/docs/_static/images/cloud-aws-route-01.webp b/docs/_static/images/cloud-aws-route-01.webp Binary files differnew file mode 100644 index 00000000..5adda05a --- /dev/null +++ b/docs/_static/images/cloud-aws-route-01.webp diff --git a/docs/_static/images/cloud-aws-route-02.webp b/docs/_static/images/cloud-aws-route-02.webp Binary files differnew file mode 100644 index 00000000..7e670263 --- /dev/null +++ b/docs/_static/images/cloud-aws-route-02.webp diff --git a/docs/_static/images/cloud-aws-route-03.webp b/docs/_static/images/cloud-aws-route-03.webp Binary files differnew file mode 100644 index 00000000..4b643b0d --- /dev/null +++ b/docs/_static/images/cloud-aws-route-03.webp diff --git a/docs/_static/images/cloud-aws-route-04.webp b/docs/_static/images/cloud-aws-route-04.webp Binary files differnew file mode 100644 index 00000000..1b67de77 --- /dev/null +++ b/docs/_static/images/cloud-aws-route-04.webp diff --git a/docs/_static/images/cloud-aws-sg-01.webp b/docs/_static/images/cloud-aws-sg-01.webp Binary files differnew file mode 100644 index 00000000..9cf13f7b --- /dev/null +++ b/docs/_static/images/cloud-aws-sg-01.webp diff --git a/docs/_static/images/cloud-aws-sg-02.webp b/docs/_static/images/cloud-aws-sg-02.webp Binary files differnew file mode 100644 index 00000000..5b00ed91 --- /dev/null +++ b/docs/_static/images/cloud-aws-sg-02.webp diff --git a/docs/_static/images/cloud-aws-sg-03.webp b/docs/_static/images/cloud-aws-sg-03.webp Binary files differnew file mode 100644 index 00000000..9cc462d6 --- /dev/null +++ b/docs/_static/images/cloud-aws-sg-03.webp diff --git a/docs/_static/images/cloud-aws-sg-04.webp b/docs/_static/images/cloud-aws-sg-04.webp Binary files differnew file mode 100644 index 00000000..5577d2e6 --- /dev/null +++ b/docs/_static/images/cloud-aws-sg-04.webp diff --git a/docs/_static/images/cloud-aws-sg-05.webp b/docs/_static/images/cloud-aws-sg-05.webp Binary files differnew file mode 100644 index 00000000..6bc4e12d --- /dev/null +++ b/docs/_static/images/cloud-aws-sg-05.webp diff --git a/docs/_static/images/cloud-aws-subnet-01.webp b/docs/_static/images/cloud-aws-subnet-01.webp Binary files differnew file mode 100644 index 00000000..ab3ded81 --- /dev/null +++ b/docs/_static/images/cloud-aws-subnet-01.webp diff --git a/docs/_static/images/cloud-aws-subnet-02.webp b/docs/_static/images/cloud-aws-subnet-02.webp Binary files differnew file mode 100644 index 00000000..8d28906f --- /dev/null +++ b/docs/_static/images/cloud-aws-subnet-02.webp diff --git a/docs/_static/images/cloud-aws-subnet-03.webp b/docs/_static/images/cloud-aws-subnet-03.webp Binary files differnew file mode 100644 index 00000000..0f1f14c9 --- /dev/null +++ b/docs/_static/images/cloud-aws-subnet-03.webp diff --git a/docs/_static/images/cloud-aws-to-azure.webp b/docs/_static/images/cloud-aws-to-azure.webp Binary files differnew file mode 100644 index 00000000..535dfac9 --- /dev/null +++ b/docs/_static/images/cloud-aws-to-azure.webp diff --git a/docs/_static/images/cloud-aws-vpc-01.webp b/docs/_static/images/cloud-aws-vpc-01.webp Binary files differnew file mode 100644 index 00000000..2b1ad120 --- /dev/null +++ b/docs/_static/images/cloud-aws-vpc-01.webp diff --git a/docs/_static/images/cloud-aws-vpc-02.webp b/docs/_static/images/cloud-aws-vpc-02.webp Binary files differnew file mode 100644 index 00000000..78bd25e9 --- /dev/null +++ b/docs/_static/images/cloud-aws-vpc-02.webp diff --git a/docs/_static/images/cloud-aws-vpc-03.webp b/docs/_static/images/cloud-aws-vpc-03.webp Binary files differnew file mode 100644 index 00000000..101a1924 --- /dev/null +++ b/docs/_static/images/cloud-aws-vpc-03.webp diff --git a/docs/_static/images/cloud-aws-vyos-01.webp b/docs/_static/images/cloud-aws-vyos-01.webp Binary files differnew file mode 100644 index 00000000..4f594b16 --- /dev/null +++ b/docs/_static/images/cloud-aws-vyos-01.webp diff --git a/docs/_static/images/cloud-aws-vyos-02.webp b/docs/_static/images/cloud-aws-vyos-02.webp Binary files differnew file mode 100644 index 00000000..70e37e49 --- /dev/null +++ b/docs/_static/images/cloud-aws-vyos-02.webp diff --git a/docs/_static/images/cloud-aws-vyos-03.webp b/docs/_static/images/cloud-aws-vyos-03.webp Binary files differnew file mode 100644 index 00000000..f526c28a --- /dev/null +++ b/docs/_static/images/cloud-aws-vyos-03.webp diff --git a/docs/_static/images/cloud-aws-vyos-04.webp b/docs/_static/images/cloud-aws-vyos-04.webp Binary files differnew file mode 100644 index 00000000..a18e5aee --- /dev/null +++ b/docs/_static/images/cloud-aws-vyos-04.webp diff --git a/docs/_static/images/cloud-aws-vyos-05.webp b/docs/_static/images/cloud-aws-vyos-05.webp Binary files differnew file mode 100644 index 00000000..f7699fe3 --- /dev/null +++ b/docs/_static/images/cloud-aws-vyos-05.webp diff --git a/docs/_static/images/cloud-aws-vyos-06.webp b/docs/_static/images/cloud-aws-vyos-06.webp Binary files differnew file mode 100644 index 00000000..06e771d6 --- /dev/null +++ b/docs/_static/images/cloud-aws-vyos-06.webp diff --git a/docs/_static/images/cloud-aws-vyos-07.webp b/docs/_static/images/cloud-aws-vyos-07.webp Binary files differnew file mode 100644 index 00000000..6b5efedc --- /dev/null +++ b/docs/_static/images/cloud-aws-vyos-07.webp diff --git a/docs/_static/images/cloud-aws-vyos-08.webp b/docs/_static/images/cloud-aws-vyos-08.webp Binary files differnew file mode 100644 index 00000000..3b6aa12b --- /dev/null +++ b/docs/_static/images/cloud-aws-vyos-08.webp diff --git a/docs/_static/images/cloud-aws-vyos-09.webp b/docs/_static/images/cloud-aws-vyos-09.webp Binary files differnew file mode 100644 index 00000000..06e771d6 --- /dev/null +++ b/docs/_static/images/cloud-aws-vyos-09.webp diff --git a/docs/_static/images/cloud-aws-vyos-10.webp b/docs/_static/images/cloud-aws-vyos-10.webp Binary files differnew file mode 100644 index 00000000..772d8e80 --- /dev/null +++ b/docs/_static/images/cloud-aws-vyos-10.webp diff --git a/docs/_static/images/cloud-aws-vyos-11.webp b/docs/_static/images/cloud-aws-vyos-11.webp Binary files differnew file mode 100644 index 00000000..8893e3bd --- /dev/null +++ b/docs/_static/images/cloud-aws-vyos-11.webp diff --git a/docs/_static/images/cloud-azure-ha-architecture.webp b/docs/_static/images/cloud-azure-ha-architecture.webp Binary files differnew file mode 100644 index 00000000..20e3e6dc --- /dev/null +++ b/docs/_static/images/cloud-azure-ha-architecture.webp diff --git a/docs/_static/images/cloud-azure-nic-01.webp b/docs/_static/images/cloud-azure-nic-01.webp Binary files differnew file mode 100644 index 00000000..37c22a86 --- /dev/null +++ b/docs/_static/images/cloud-azure-nic-01.webp diff --git a/docs/_static/images/cloud-azure-nic-02.webp b/docs/_static/images/cloud-azure-nic-02.webp Binary files differnew file mode 100644 index 00000000..5a348732 --- /dev/null +++ b/docs/_static/images/cloud-azure-nic-02.webp diff --git a/docs/_static/images/cloud-azure-nic-03.webp b/docs/_static/images/cloud-azure-nic-03.webp Binary files differnew file mode 100644 index 00000000..9002fba3 --- /dev/null +++ b/docs/_static/images/cloud-azure-nic-03.webp diff --git a/docs/_static/images/cloud-azure-nic-04.webp b/docs/_static/images/cloud-azure-nic-04.webp Binary files differnew file mode 100644 index 00000000..c24b8cda --- /dev/null +++ b/docs/_static/images/cloud-azure-nic-04.webp diff --git a/docs/_static/images/cloud-azure-pub-ip-01.webp b/docs/_static/images/cloud-azure-pub-ip-01.webp Binary files differnew file mode 100644 index 00000000..648e97cc --- /dev/null +++ b/docs/_static/images/cloud-azure-pub-ip-01.webp diff --git a/docs/_static/images/cloud-azure-pub-ip-02.webp b/docs/_static/images/cloud-azure-pub-ip-02.webp Binary files differnew file mode 100644 index 00000000..b79eb2d8 --- /dev/null +++ b/docs/_static/images/cloud-azure-pub-ip-02.webp diff --git a/docs/_static/images/cloud-azure-pub-ip-03.webp b/docs/_static/images/cloud-azure-pub-ip-03.webp Binary files differnew file mode 100644 index 00000000..e6ec5fa8 --- /dev/null +++ b/docs/_static/images/cloud-azure-pub-ip-03.webp diff --git a/docs/_static/images/cloud-azure-rg-01.webp b/docs/_static/images/cloud-azure-rg-01.webp Binary files differnew file mode 100644 index 00000000..194b66ae --- /dev/null +++ b/docs/_static/images/cloud-azure-rg-01.webp diff --git a/docs/_static/images/cloud-azure-rg-02.webp b/docs/_static/images/cloud-azure-rg-02.webp Binary files differnew file mode 100644 index 00000000..6b1bcea5 --- /dev/null +++ b/docs/_static/images/cloud-azure-rg-02.webp diff --git a/docs/_static/images/cloud-azure-route-01.webp b/docs/_static/images/cloud-azure-route-01.webp Binary files differnew file mode 100644 index 00000000..44036f0d --- /dev/null +++ b/docs/_static/images/cloud-azure-route-01.webp diff --git a/docs/_static/images/cloud-azure-route-02.webp b/docs/_static/images/cloud-azure-route-02.webp Binary files differnew file mode 100644 index 00000000..41159484 --- /dev/null +++ b/docs/_static/images/cloud-azure-route-02.webp diff --git a/docs/_static/images/cloud-azure-route-03.webp b/docs/_static/images/cloud-azure-route-03.webp Binary files differnew file mode 100644 index 00000000..d316c94f --- /dev/null +++ b/docs/_static/images/cloud-azure-route-03.webp diff --git a/docs/_static/images/cloud-azure-route-04.webp b/docs/_static/images/cloud-azure-route-04.webp Binary files differnew file mode 100644 index 00000000..edfcb232 --- /dev/null +++ b/docs/_static/images/cloud-azure-route-04.webp diff --git a/docs/_static/images/cloud-azure-route-05.webp b/docs/_static/images/cloud-azure-route-05.webp Binary files differnew file mode 100644 index 00000000..ead3e73e --- /dev/null +++ b/docs/_static/images/cloud-azure-route-05.webp diff --git a/docs/_static/images/cloud-azure-sg-01.webp b/docs/_static/images/cloud-azure-sg-01.webp Binary files differnew file mode 100644 index 00000000..d7c38a99 --- /dev/null +++ b/docs/_static/images/cloud-azure-sg-01.webp diff --git a/docs/_static/images/cloud-azure-sg-02.webp b/docs/_static/images/cloud-azure-sg-02.webp Binary files differnew file mode 100644 index 00000000..fd2ddc34 --- /dev/null +++ b/docs/_static/images/cloud-azure-sg-02.webp diff --git a/docs/_static/images/cloud-azure-sg-03.webp b/docs/_static/images/cloud-azure-sg-03.webp Binary files differnew file mode 100644 index 00000000..fa4a2b8f --- /dev/null +++ b/docs/_static/images/cloud-azure-sg-03.webp diff --git a/docs/_static/images/cloud-azure-sg-04.webp b/docs/_static/images/cloud-azure-sg-04.webp Binary files differnew file mode 100644 index 00000000..13078e17 --- /dev/null +++ b/docs/_static/images/cloud-azure-sg-04.webp diff --git a/docs/_static/images/cloud-azure-vm-01.webp b/docs/_static/images/cloud-azure-vm-01.webp Binary files differnew file mode 100644 index 00000000..a305a263 --- /dev/null +++ b/docs/_static/images/cloud-azure-vm-01.webp diff --git a/docs/_static/images/cloud-azure-vm-02.webp b/docs/_static/images/cloud-azure-vm-02.webp Binary files differnew file mode 100644 index 00000000..3a629165 --- /dev/null +++ b/docs/_static/images/cloud-azure-vm-02.webp diff --git a/docs/_static/images/cloud-azure-vm-03.webp b/docs/_static/images/cloud-azure-vm-03.webp Binary files differnew file mode 100644 index 00000000..e1f1b98d --- /dev/null +++ b/docs/_static/images/cloud-azure-vm-03.webp diff --git a/docs/_static/images/cloud-azure-vm-04.webp b/docs/_static/images/cloud-azure-vm-04.webp Binary files differnew file mode 100644 index 00000000..c28a10b5 --- /dev/null +++ b/docs/_static/images/cloud-azure-vm-04.webp diff --git a/docs/_static/images/cloud-azure-vm-05.webp b/docs/_static/images/cloud-azure-vm-05.webp Binary files differnew file mode 100644 index 00000000..1cfb2d56 --- /dev/null +++ b/docs/_static/images/cloud-azure-vm-05.webp diff --git a/docs/_static/images/cloud-azure-vm-06.webp b/docs/_static/images/cloud-azure-vm-06.webp Binary files differnew file mode 100644 index 00000000..ce71b375 --- /dev/null +++ b/docs/_static/images/cloud-azure-vm-06.webp diff --git a/docs/_static/images/cloud-azure-vm-07.webp b/docs/_static/images/cloud-azure-vm-07.webp Binary files differnew file mode 100644 index 00000000..d1ff8585 --- /dev/null +++ b/docs/_static/images/cloud-azure-vm-07.webp diff --git a/docs/_static/images/cloud-azure-vm-08.webp b/docs/_static/images/cloud-azure-vm-08.webp Binary files differnew file mode 100644 index 00000000..93b290fa --- /dev/null +++ b/docs/_static/images/cloud-azure-vm-08.webp diff --git a/docs/_static/images/cloud-azure-vm-09.webp b/docs/_static/images/cloud-azure-vm-09.webp Binary files differnew file mode 100644 index 00000000..1a9ec0da --- /dev/null +++ b/docs/_static/images/cloud-azure-vm-09.webp diff --git a/docs/_static/images/cloud-azure-vm-10.webp b/docs/_static/images/cloud-azure-vm-10.webp Binary files differnew file mode 100644 index 00000000..feec6515 --- /dev/null +++ b/docs/_static/images/cloud-azure-vm-10.webp diff --git a/docs/_static/images/cloud-azure-vm-11.webp b/docs/_static/images/cloud-azure-vm-11.webp Binary files differnew file mode 100644 index 00000000..15c8149f --- /dev/null +++ b/docs/_static/images/cloud-azure-vm-11.webp diff --git a/docs/_static/images/cloud-azure-vm-12.webp b/docs/_static/images/cloud-azure-vm-12.webp Binary files differnew file mode 100644 index 00000000..f549f3e7 --- /dev/null +++ b/docs/_static/images/cloud-azure-vm-12.webp diff --git a/docs/_static/images/cloud-azure-vm-13.webp b/docs/_static/images/cloud-azure-vm-13.webp Binary files differnew file mode 100644 index 00000000..2d6964bf --- /dev/null +++ b/docs/_static/images/cloud-azure-vm-13.webp diff --git a/docs/_static/images/cloud-azure-vnet-01.webp b/docs/_static/images/cloud-azure-vnet-01.webp Binary files differnew file mode 100644 index 00000000..0b24d59c --- /dev/null +++ b/docs/_static/images/cloud-azure-vnet-01.webp diff --git a/docs/_static/images/cloud-azure-vnet-02.webp b/docs/_static/images/cloud-azure-vnet-02.webp Binary files differnew file mode 100644 index 00000000..033ac5a2 --- /dev/null +++ b/docs/_static/images/cloud-azure-vnet-02.webp diff --git a/docs/_static/images/cloud-azure-vnet-03.webp b/docs/_static/images/cloud-azure-vnet-03.webp Binary files differnew file mode 100644 index 00000000..7fbdd484 --- /dev/null +++ b/docs/_static/images/cloud-azure-vnet-03.webp diff --git a/docs/_static/images/cloud-azure-vnet-04.webp b/docs/_static/images/cloud-azure-vnet-04.webp Binary files differnew file mode 100644 index 00000000..49fe70d5 --- /dev/null +++ b/docs/_static/images/cloud-azure-vnet-04.webp diff --git a/docs/_static/images/cloud-azure-vnet-05.webp b/docs/_static/images/cloud-azure-vnet-05.webp Binary files differnew file mode 100644 index 00000000..2ac0bcd7 --- /dev/null +++ b/docs/_static/images/cloud-azure-vnet-05.webp diff --git a/docs/_static/images/cloud-azure-vnet-06.webp b/docs/_static/images/cloud-azure-vnet-06.webp Binary files differnew file mode 100644 index 00000000..0da36ab0 --- /dev/null +++ b/docs/_static/images/cloud-azure-vnet-06.webp diff --git a/docs/_static/images/cloud-gcp-01.webp b/docs/_static/images/cloud-gcp-01.webp Binary files differnew file mode 100644 index 00000000..d21fc5ff --- /dev/null +++ b/docs/_static/images/cloud-gcp-01.webp diff --git a/docs/_static/images/cloud-gcp-02.webp b/docs/_static/images/cloud-gcp-02.webp Binary files differnew file mode 100644 index 00000000..977f411f --- /dev/null +++ b/docs/_static/images/cloud-gcp-02.webp diff --git a/docs/_static/images/cloud-gcp-market-01.webp b/docs/_static/images/cloud-gcp-market-01.webp Binary files differnew file mode 100644 index 00000000..ffe56746 --- /dev/null +++ b/docs/_static/images/cloud-gcp-market-01.webp diff --git a/docs/_static/images/cloud-gcp-market-02.webp b/docs/_static/images/cloud-gcp-market-02.webp Binary files differnew file mode 100644 index 00000000..78aa7192 --- /dev/null +++ b/docs/_static/images/cloud-gcp-market-02.webp diff --git a/docs/_static/images/cloud-gcp-market-03.webp b/docs/_static/images/cloud-gcp-market-03.webp Binary files differnew file mode 100644 index 00000000..617970a9 --- /dev/null +++ b/docs/_static/images/cloud-gcp-market-03.webp diff --git a/docs/_static/images/cloud-gcp-market-04.webp b/docs/_static/images/cloud-gcp-market-04.webp Binary files differnew file mode 100644 index 00000000..f6518aaa --- /dev/null +++ b/docs/_static/images/cloud-gcp-market-04.webp diff --git a/docs/_static/images/cloud-gcp-market-05.webp b/docs/_static/images/cloud-gcp-market-05.webp Binary files differnew file mode 100644 index 00000000..20089558 --- /dev/null +++ b/docs/_static/images/cloud-gcp-market-05.webp diff --git a/docs/_static/images/cloud-gcp-proj.webp b/docs/_static/images/cloud-gcp-proj.webp Binary files differnew file mode 100644 index 00000000..c7842b72 --- /dev/null +++ b/docs/_static/images/cloud-gcp-proj.webp diff --git a/docs/_static/images/cloud-gcp-svc.webp b/docs/_static/images/cloud-gcp-svc.webp Binary files differnew file mode 100644 index 00000000..8f19d73a --- /dev/null +++ b/docs/_static/images/cloud-gcp-svc.webp diff --git a/docs/_static/images/cloud-gcp-vm-01.webp b/docs/_static/images/cloud-gcp-vm-01.webp Binary files differnew file mode 100644 index 00000000..be27a325 --- /dev/null +++ b/docs/_static/images/cloud-gcp-vm-01.webp diff --git a/docs/_static/images/cloud-gcp-vm-02.webp b/docs/_static/images/cloud-gcp-vm-02.webp Binary files differnew file mode 100644 index 00000000..c72dcb51 --- /dev/null +++ b/docs/_static/images/cloud-gcp-vm-02.webp diff --git a/docs/_static/images/cloud-gcp-vm-03.webp b/docs/_static/images/cloud-gcp-vm-03.webp Binary files differnew file mode 100644 index 00000000..0e30aff7 --- /dev/null +++ b/docs/_static/images/cloud-gcp-vm-03.webp diff --git a/docs/_static/images/cloud-gcp-vm-04.webp b/docs/_static/images/cloud-gcp-vm-04.webp Binary files differnew file mode 100644 index 00000000..0dc2cb41 --- /dev/null +++ b/docs/_static/images/cloud-gcp-vm-04.webp diff --git a/docs/_static/images/cloud-gcp-vm-06.webp b/docs/_static/images/cloud-gcp-vm-06.webp Binary files differnew file mode 100644 index 00000000..36a33528 --- /dev/null +++ b/docs/_static/images/cloud-gcp-vm-06.webp diff --git a/docs/_static/images/cloud-gcp-vm-07.webp b/docs/_static/images/cloud-gcp-vm-07.webp Binary files differnew file mode 100644 index 00000000..5ba96ee3 --- /dev/null +++ b/docs/_static/images/cloud-gcp-vm-07.webp diff --git a/docs/_static/images/cloud-gcp-vm-08.webp b/docs/_static/images/cloud-gcp-vm-08.webp Binary files differnew file mode 100644 index 00000000..21524ec8 --- /dev/null +++ b/docs/_static/images/cloud-gcp-vm-08.webp diff --git a/docs/_static/images/cloud-gcp-vm-09.webp b/docs/_static/images/cloud-gcp-vm-09.webp Binary files differnew file mode 100644 index 00000000..1cfb2d56 --- /dev/null +++ b/docs/_static/images/cloud-gcp-vm-09.webp diff --git a/docs/_static/images/cloud-gcp-vpc-01.webp b/docs/_static/images/cloud-gcp-vpc-01.webp Binary files differnew file mode 100644 index 00000000..194fa272 --- /dev/null +++ b/docs/_static/images/cloud-gcp-vpc-01.webp diff --git a/docs/_static/images/cloud-gcp-vpc-02.webp b/docs/_static/images/cloud-gcp-vpc-02.webp Binary files differnew file mode 100644 index 00000000..02267cca --- /dev/null +++ b/docs/_static/images/cloud-gcp-vpc-02.webp diff --git a/docs/_static/images/cloud-gcp-vpc-03.webp b/docs/_static/images/cloud-gcp-vpc-03.webp Binary files differnew file mode 100644 index 00000000..f738729b --- /dev/null +++ b/docs/_static/images/cloud-gcp-vpc-03.webp diff --git a/docs/_static/images/cloud-gcp-vpc-04.webp b/docs/_static/images/cloud-gcp-vpc-04.webp Binary files differnew file mode 100644 index 00000000..6cd6f63e --- /dev/null +++ b/docs/_static/images/cloud-gcp-vpc-04.webp diff --git a/docs/_static/images/cloud-gcp-vpc-05.webp b/docs/_static/images/cloud-gcp-vpc-05.webp Binary files differnew file mode 100644 index 00000000..a8dafebb --- /dev/null +++ b/docs/_static/images/cloud-gcp-vpc-05.webp diff --git a/docs/_static/images/cloud-gcp-vpc-06.webp b/docs/_static/images/cloud-gcp-vpc-06.webp Binary files differnew file mode 100644 index 00000000..72fe8bbb --- /dev/null +++ b/docs/_static/images/cloud-gcp-vpc-06.webp diff --git a/docs/_static/images/cloud-gcp-vpc-07.webp b/docs/_static/images/cloud-gcp-vpc-07.webp Binary files differnew file mode 100644 index 00000000..2225f55e --- /dev/null +++ b/docs/_static/images/cloud-gcp-vpc-07.webp diff --git a/docs/_static/images/dhcp-relay-through-gre-bridge.webp b/docs/_static/images/dhcp-relay-through-gre-bridge.webp Binary files differnew file mode 100644 index 00000000..4b626e91 --- /dev/null +++ b/docs/_static/images/dhcp-relay-through-gre-bridge.webp diff --git a/docs/_static/images/eve-ng-vyos.webp b/docs/_static/images/eve-ng-vyos.webp Binary files differnew file mode 100644 index 00000000..f68b2fba --- /dev/null +++ b/docs/_static/images/eve-ng-vyos.webp diff --git a/docs/_static/images/firewall-and-vrf-blueprints.webp b/docs/_static/images/firewall-and-vrf-blueprints.webp Binary files differnew file mode 100644 index 00000000..17194880 --- /dev/null +++ b/docs/_static/images/firewall-and-vrf-blueprints.webp diff --git a/docs/_static/images/firewall-bridge-packet-flow.webp b/docs/_static/images/firewall-bridge-packet-flow.webp Binary files differnew file mode 100644 index 00000000..908eaee3 --- /dev/null +++ b/docs/_static/images/firewall-bridge-packet-flow.webp diff --git a/docs/_static/images/firewall-flowtable-packet-flow.webp b/docs/_static/images/firewall-flowtable-packet-flow.webp Binary files differnew file mode 100644 index 00000000..6d20ab7a --- /dev/null +++ b/docs/_static/images/firewall-flowtable-packet-flow.webp diff --git a/docs/_static/images/firewall-fwd-packet-flow.webp b/docs/_static/images/firewall-fwd-packet-flow.webp Binary files differnew file mode 100644 index 00000000..31b155a9 --- /dev/null +++ b/docs/_static/images/firewall-fwd-packet-flow.webp diff --git a/docs/_static/images/firewall-gral-packet-flow.webp b/docs/_static/images/firewall-gral-packet-flow.webp Binary files differnew file mode 100644 index 00000000..add21b1e --- /dev/null +++ b/docs/_static/images/firewall-gral-packet-flow.webp diff --git a/docs/_static/images/firewall-input-packet-flow.webp b/docs/_static/images/firewall-input-packet-flow.webp Binary files differnew file mode 100644 index 00000000..a5f207a1 --- /dev/null +++ b/docs/_static/images/firewall-input-packet-flow.webp diff --git a/docs/_static/images/firewall-traditional.webp b/docs/_static/images/firewall-traditional.webp Binary files differnew file mode 100644 index 00000000..2804393f --- /dev/null +++ b/docs/_static/images/firewall-traditional.webp diff --git a/docs/_static/images/firewall-zonebased.webp b/docs/_static/images/firewall-zonebased.webp Binary files differnew file mode 100644 index 00000000..11394be0 --- /dev/null +++ b/docs/_static/images/firewall-zonebased.webp diff --git a/docs/_static/images/gns3-01.webp b/docs/_static/images/gns3-01.webp Binary files differnew file mode 100644 index 00000000..d0d48d26 --- /dev/null +++ b/docs/_static/images/gns3-01.webp diff --git a/docs/_static/images/gns3-02.webp b/docs/_static/images/gns3-02.webp Binary files differnew file mode 100644 index 00000000..83ec7546 --- /dev/null +++ b/docs/_static/images/gns3-02.webp diff --git a/docs/_static/images/gns3-03.webp b/docs/_static/images/gns3-03.webp Binary files differnew file mode 100644 index 00000000..aab36829 --- /dev/null +++ b/docs/_static/images/gns3-03.webp diff --git a/docs/_static/images/gns3-04.webp b/docs/_static/images/gns3-04.webp Binary files differnew file mode 100644 index 00000000..722789bb --- /dev/null +++ b/docs/_static/images/gns3-04.webp diff --git a/docs/_static/images/gns3-05.webp b/docs/_static/images/gns3-05.webp Binary files differnew file mode 100644 index 00000000..db42dd62 --- /dev/null +++ b/docs/_static/images/gns3-05.webp diff --git a/docs/_static/images/gns3-06.webp b/docs/_static/images/gns3-06.webp Binary files differnew file mode 100644 index 00000000..b41d774c --- /dev/null +++ b/docs/_static/images/gns3-06.webp diff --git a/docs/_static/images/gns3-07.webp b/docs/_static/images/gns3-07.webp Binary files differnew file mode 100644 index 00000000..360644f8 --- /dev/null +++ b/docs/_static/images/gns3-07.webp diff --git a/docs/_static/images/gns3-08.webp b/docs/_static/images/gns3-08.webp Binary files differnew file mode 100644 index 00000000..d7a8f3c3 --- /dev/null +++ b/docs/_static/images/gns3-08.webp diff --git a/docs/_static/images/gns3-09.webp b/docs/_static/images/gns3-09.webp Binary files differnew file mode 100644 index 00000000..b68dfdab --- /dev/null +++ b/docs/_static/images/gns3-09.webp diff --git a/docs/_static/images/gns3-10.webp b/docs/_static/images/gns3-10.webp Binary files differnew file mode 100644 index 00000000..61ab6d4e --- /dev/null +++ b/docs/_static/images/gns3-10.webp diff --git a/docs/_static/images/gns3-11.webp b/docs/_static/images/gns3-11.webp Binary files differnew file mode 100644 index 00000000..efac5bb7 --- /dev/null +++ b/docs/_static/images/gns3-11.webp diff --git a/docs/_static/images/gns3-12.webp b/docs/_static/images/gns3-12.webp Binary files differnew file mode 100644 index 00000000..f0760510 --- /dev/null +++ b/docs/_static/images/gns3-12.webp diff --git a/docs/_static/images/gns3-13.webp b/docs/_static/images/gns3-13.webp Binary files differnew file mode 100644 index 00000000..a246380e --- /dev/null +++ b/docs/_static/images/gns3-13.webp diff --git a/docs/_static/images/gns3-14.webp b/docs/_static/images/gns3-14.webp Binary files differnew file mode 100644 index 00000000..7e111c58 --- /dev/null +++ b/docs/_static/images/gns3-14.webp diff --git a/docs/_static/images/gns3-15.webp b/docs/_static/images/gns3-15.webp Binary files differnew file mode 100644 index 00000000..79e7e6db --- /dev/null +++ b/docs/_static/images/gns3-15.webp diff --git a/docs/_static/images/gns3-16.webp b/docs/_static/images/gns3-16.webp Binary files differnew file mode 100644 index 00000000..423503ed --- /dev/null +++ b/docs/_static/images/gns3-16.webp diff --git a/docs/_static/images/gns3-17.webp b/docs/_static/images/gns3-17.webp Binary files differnew file mode 100644 index 00000000..8b7e5c01 --- /dev/null +++ b/docs/_static/images/gns3-17.webp diff --git a/docs/_static/images/gns3-20.webp b/docs/_static/images/gns3-20.webp Binary files differnew file mode 100644 index 00000000..a65c47b4 --- /dev/null +++ b/docs/_static/images/gns3-20.webp diff --git a/docs/_static/images/gns3-21.webp b/docs/_static/images/gns3-21.webp Binary files differnew file mode 100644 index 00000000..adc71baa --- /dev/null +++ b/docs/_static/images/gns3-21.webp diff --git a/docs/_static/images/gns3-215.webp b/docs/_static/images/gns3-215.webp Binary files differnew file mode 100644 index 00000000..49755246 --- /dev/null +++ b/docs/_static/images/gns3-215.webp diff --git a/docs/_static/images/gns3-22.webp b/docs/_static/images/gns3-22.webp Binary files differnew file mode 100644 index 00000000..90bc4fa4 --- /dev/null +++ b/docs/_static/images/gns3-22.webp diff --git a/docs/_static/images/gowin-01.webp b/docs/_static/images/gowin-01.webp Binary files differnew file mode 100644 index 00000000..048252d3 --- /dev/null +++ b/docs/_static/images/gowin-01.webp diff --git a/docs/_static/images/gowin-02.webp b/docs/_static/images/gowin-02.webp Binary files differnew file mode 100644 index 00000000..816c178c --- /dev/null +++ b/docs/_static/images/gowin-02.webp diff --git a/docs/_static/images/gowin-03.webp b/docs/_static/images/gowin-03.webp Binary files differnew file mode 100644 index 00000000..ebf67368 --- /dev/null +++ b/docs/_static/images/gowin-03.webp diff --git a/docs/_static/images/gowin-04.webp b/docs/_static/images/gowin-04.webp Binary files differnew file mode 100644 index 00000000..b5e94a84 --- /dev/null +++ b/docs/_static/images/gowin-04.webp diff --git a/docs/_static/images/inter-vrf-routing-vrf-lite.webp b/docs/_static/images/inter-vrf-routing-vrf-lite.webp Binary files differnew file mode 100644 index 00000000..43394ec5 --- /dev/null +++ b/docs/_static/images/inter-vrf-routing-vrf-lite.webp diff --git a/docs/_static/images/ipsec-vyos-pa.webp b/docs/_static/images/ipsec-vyos-pa.webp Binary files differnew file mode 100644 index 00000000..1758d65c --- /dev/null +++ b/docs/_static/images/ipsec-vyos-pa.webp diff --git a/docs/_static/images/keypairs.webp b/docs/_static/images/keypairs.webp Binary files differnew file mode 100644 index 00000000..14df4da3 --- /dev/null +++ b/docs/_static/images/keypairs.webp diff --git a/docs/_static/images/lac-lns-diagram.webp b/docs/_static/images/lac-lns-diagram.webp Binary files differnew file mode 100644 index 00000000..0ce052c2 --- /dev/null +++ b/docs/_static/images/lac-lns-diagram.webp diff --git a/docs/_static/images/lac-lns-winclient.webp b/docs/_static/images/lac-lns-winclient.webp Binary files differnew file mode 100644 index 00000000..95792cad --- /dev/null +++ b/docs/_static/images/lac-lns-winclient.webp diff --git a/docs/_static/images/ldapone.webp b/docs/_static/images/ldapone.webp Binary files differnew file mode 100644 index 00000000..0f070454 --- /dev/null +++ b/docs/_static/images/ldapone.webp diff --git a/docs/_static/images/ldaptwo.webp b/docs/_static/images/ldaptwo.webp Binary files differnew file mode 100644 index 00000000..9ee636df --- /dev/null +++ b/docs/_static/images/ldaptwo.webp diff --git a/docs/_static/images/mainschema.webp b/docs/_static/images/mainschema.webp Binary files differnew file mode 100644 index 00000000..c9db82ca --- /dev/null +++ b/docs/_static/images/mainschema.webp diff --git a/docs/_static/images/multicast-basic.webp b/docs/_static/images/multicast-basic.webp Binary files differnew file mode 100644 index 00000000..8e963421 --- /dev/null +++ b/docs/_static/images/multicast-basic.webp diff --git a/docs/_static/images/nat_before_vpn_topology.webp b/docs/_static/images/nat_before_vpn_topology.webp Binary files differnew file mode 100644 index 00000000..7f93a3d8 --- /dev/null +++ b/docs/_static/images/nat_before_vpn_topology.webp diff --git a/docs/_static/images/nmp1.webp b/docs/_static/images/nmp1.webp Binary files differnew file mode 100644 index 00000000..60035421 --- /dev/null +++ b/docs/_static/images/nmp1.webp diff --git a/docs/_static/images/nmp2.webp b/docs/_static/images/nmp2.webp Binary files differnew file mode 100644 index 00000000..6dbf4d42 --- /dev/null +++ b/docs/_static/images/nmp2.webp diff --git a/docs/_static/images/nmp3.webp b/docs/_static/images/nmp3.webp Binary files differnew file mode 100644 index 00000000..72ab7050 --- /dev/null +++ b/docs/_static/images/nmp3.webp diff --git a/docs/_static/images/nmp4.webp b/docs/_static/images/nmp4.webp Binary files differnew file mode 100644 index 00000000..d7684b38 --- /dev/null +++ b/docs/_static/images/nmp4.webp diff --git a/docs/_static/images/nmp5.webp b/docs/_static/images/nmp5.webp Binary files differnew file mode 100644 index 00000000..6c64707c --- /dev/null +++ b/docs/_static/images/nmp5.webp diff --git a/docs/_static/images/nmp6.webp b/docs/_static/images/nmp6.webp Binary files differnew file mode 100644 index 00000000..85141b11 --- /dev/null +++ b/docs/_static/images/nmp6.webp diff --git a/docs/_static/images/nmp7.webp b/docs/_static/images/nmp7.webp Binary files differnew file mode 100644 index 00000000..6f64df83 --- /dev/null +++ b/docs/_static/images/nmp7.webp diff --git a/docs/_static/images/openvpn_site2site_diagram.webp b/docs/_static/images/openvpn_site2site_diagram.webp Binary files differnew file mode 100644 index 00000000..97d4df3f --- /dev/null +++ b/docs/_static/images/openvpn_site2site_diagram.webp diff --git a/docs/_static/images/password-recovery-01.webp b/docs/_static/images/password-recovery-01.webp Binary files differnew file mode 100644 index 00000000..26427ecb --- /dev/null +++ b/docs/_static/images/password-recovery-01.webp diff --git a/docs/_static/images/pbr_example_1.webp b/docs/_static/images/pbr_example_1.webp Binary files differnew file mode 100644 index 00000000..4e8ba882 --- /dev/null +++ b/docs/_static/images/pbr_example_1.webp diff --git a/docs/_static/images/permanent_install.webp b/docs/_static/images/permanent_install.webp Binary files differnew file mode 100644 index 00000000..6ab06b0a --- /dev/null +++ b/docs/_static/images/permanent_install.webp diff --git a/docs/_static/images/pppoe-ipv6-pd-diagram.webp b/docs/_static/images/pppoe-ipv6-pd-diagram.webp Binary files differnew file mode 100644 index 00000000..344bbf21 --- /dev/null +++ b/docs/_static/images/pppoe-ipv6-pd-diagram.webp diff --git a/docs/_static/images/qos1.webp b/docs/_static/images/qos1.webp Binary files differnew file mode 100644 index 00000000..fe9264a6 --- /dev/null +++ b/docs/_static/images/qos1.webp diff --git a/docs/_static/images/qos10.webp b/docs/_static/images/qos10.webp Binary files differnew file mode 100644 index 00000000..646ae67b --- /dev/null +++ b/docs/_static/images/qos10.webp diff --git a/docs/_static/images/qos2.webp b/docs/_static/images/qos2.webp Binary files differnew file mode 100644 index 00000000..7c8a1336 --- /dev/null +++ b/docs/_static/images/qos2.webp diff --git a/docs/_static/images/qos3.webp b/docs/_static/images/qos3.webp Binary files differnew file mode 100644 index 00000000..3cf2dd32 --- /dev/null +++ b/docs/_static/images/qos3.webp diff --git a/docs/_static/images/qos4.webp b/docs/_static/images/qos4.webp Binary files differnew file mode 100644 index 00000000..cc108ee8 --- /dev/null +++ b/docs/_static/images/qos4.webp diff --git a/docs/_static/images/qos5.webp b/docs/_static/images/qos5.webp Binary files differnew file mode 100644 index 00000000..d41ae04d --- /dev/null +++ b/docs/_static/images/qos5.webp diff --git a/docs/_static/images/qos6.webp b/docs/_static/images/qos6.webp Binary files differnew file mode 100644 index 00000000..7d238851 --- /dev/null +++ b/docs/_static/images/qos6.webp diff --git a/docs/_static/images/qos7.webp b/docs/_static/images/qos7.webp Binary files differnew file mode 100644 index 00000000..026452c2 --- /dev/null +++ b/docs/_static/images/qos7.webp diff --git a/docs/_static/images/qos8.webp b/docs/_static/images/qos8.webp Binary files differnew file mode 100644 index 00000000..e1706ce2 --- /dev/null +++ b/docs/_static/images/qos8.webp diff --git a/docs/_static/images/qos9.webp b/docs/_static/images/qos9.webp Binary files differnew file mode 100644 index 00000000..2cc6fdaa --- /dev/null +++ b/docs/_static/images/qos9.webp diff --git a/docs/_static/images/service_conntrack_sync-schema.webp b/docs/_static/images/service_conntrack_sync-schema.webp Binary files differnew file mode 100644 index 00000000..e347aa19 --- /dev/null +++ b/docs/_static/images/service_conntrack_sync-schema.webp diff --git a/docs/_static/images/service_dhcp-relay01.webp b/docs/_static/images/service_dhcp-relay01.webp Binary files differnew file mode 100644 index 00000000..5fbfad3e --- /dev/null +++ b/docs/_static/images/service_dhcp-relay01.webp diff --git a/docs/_static/images/service_dhcpv6-relay01.webp b/docs/_static/images/service_dhcpv6-relay01.webp Binary files differnew file mode 100644 index 00000000..1f72f51f --- /dev/null +++ b/docs/_static/images/service_dhcpv6-relay01.webp diff --git a/docs/_static/images/service_snmp_communication_principles_diagram.webp b/docs/_static/images/service_snmp_communication_principles_diagram.webp Binary files differnew file mode 100644 index 00000000..abb18133 --- /dev/null +++ b/docs/_static/images/service_snmp_communication_principles_diagram.webp diff --git a/docs/_static/images/sg.webp b/docs/_static/images/sg.webp Binary files differnew file mode 100644 index 00000000..5ee77e0d --- /dev/null +++ b/docs/_static/images/sg.webp diff --git a/docs/_static/images/sticky-connections.webp b/docs/_static/images/sticky-connections.webp Binary files differnew file mode 100644 index 00000000..92e5b769 --- /dev/null +++ b/docs/_static/images/sticky-connections.webp diff --git a/docs/_static/images/traffic.webp b/docs/_static/images/traffic.webp Binary files differnew file mode 100644 index 00000000..f6f9e183 --- /dev/null +++ b/docs/_static/images/traffic.webp diff --git a/docs/_static/images/virt-libvirt-01.webp b/docs/_static/images/virt-libvirt-01.webp Binary files differnew file mode 100644 index 00000000..02498c96 --- /dev/null +++ b/docs/_static/images/virt-libvirt-01.webp diff --git a/docs/_static/images/virt-libvirt-02.webp b/docs/_static/images/virt-libvirt-02.webp Binary files differnew file mode 100644 index 00000000..06ad10aa --- /dev/null +++ b/docs/_static/images/virt-libvirt-02.webp diff --git a/docs/_static/images/virt-libvirt-03.webp b/docs/_static/images/virt-libvirt-03.webp Binary files differnew file mode 100644 index 00000000..e8beae0c --- /dev/null +++ b/docs/_static/images/virt-libvirt-03.webp diff --git a/docs/_static/images/virt-libvirt-04.webp b/docs/_static/images/virt-libvirt-04.webp Binary files differnew file mode 100644 index 00000000..586cdedb --- /dev/null +++ b/docs/_static/images/virt-libvirt-04.webp diff --git a/docs/_static/images/virt-libvirt-05.webp b/docs/_static/images/virt-libvirt-05.webp Binary files differnew file mode 100644 index 00000000..65c57a3d --- /dev/null +++ b/docs/_static/images/virt-libvirt-05.webp diff --git a/docs/_static/images/virt-libvirt-06.webp b/docs/_static/images/virt-libvirt-06.webp Binary files differnew file mode 100644 index 00000000..da7a41a9 --- /dev/null +++ b/docs/_static/images/virt-libvirt-06.webp diff --git a/docs/_static/images/virt-libvirt-qc-01.webp b/docs/_static/images/virt-libvirt-qc-01.webp Binary files differnew file mode 100644 index 00000000..1b19ca60 --- /dev/null +++ b/docs/_static/images/virt-libvirt-qc-01.webp diff --git a/docs/_static/images/virt-libvirt-qc-02.webp b/docs/_static/images/virt-libvirt-qc-02.webp Binary files differnew file mode 100644 index 00000000..8281ebfb --- /dev/null +++ b/docs/_static/images/virt-libvirt-qc-02.webp diff --git a/docs/_static/images/virt-libvirt-qc-03.webp b/docs/_static/images/virt-libvirt-qc-03.webp Binary files differnew file mode 100644 index 00000000..7dc4e7e8 --- /dev/null +++ b/docs/_static/images/virt-libvirt-qc-03.webp diff --git a/docs/_static/images/vpn_dmvpn_topology01.webp b/docs/_static/images/vpn_dmvpn_topology01.webp Binary files differnew file mode 100644 index 00000000..3da35995 --- /dev/null +++ b/docs/_static/images/vpn_dmvpn_topology01.webp diff --git a/docs/_static/images/vpn_s2s_ikev2.webp b/docs/_static/images/vpn_s2s_ikev2.webp Binary files differnew file mode 100644 index 00000000..615f689c --- /dev/null +++ b/docs/_static/images/vpn_s2s_ikev2.webp diff --git a/docs/_static/images/vpn_s2s_ikev2_c.webp b/docs/_static/images/vpn_s2s_ikev2_c.webp Binary files differnew file mode 100644 index 00000000..f572fc29 --- /dev/null +++ b/docs/_static/images/vpn_s2s_ikev2_c.webp diff --git a/docs/_static/images/vrf-example-topology-01.webp b/docs/_static/images/vrf-example-topology-01.webp Binary files differnew file mode 100644 index 00000000..696abad1 --- /dev/null +++ b/docs/_static/images/vrf-example-topology-01.webp diff --git a/docs/_static/images/vyos-downloads.webp b/docs/_static/images/vyos-downloads.webp Binary files differnew file mode 100644 index 00000000..9d446701 --- /dev/null +++ b/docs/_static/images/vyos-downloads.webp diff --git a/docs/_static/images/vyos-sr-isis.webp b/docs/_static/images/vyos-sr-isis.webp Binary files differnew file mode 100644 index 00000000..8ecad813 --- /dev/null +++ b/docs/_static/images/vyos-sr-isis.webp diff --git a/docs/_static/images/vyos_1_4_nat66_simple.webp b/docs/_static/images/vyos_1_4_nat66_simple.webp Binary files differnew file mode 100644 index 00000000..6dedc08c --- /dev/null +++ b/docs/_static/images/vyos_1_4_nat66_simple.webp diff --git a/docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.webp b/docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.webp Binary files differnew file mode 100644 index 00000000..352d1f08 --- /dev/null +++ b/docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.webp diff --git a/docs/_static/images/vyos_arista_bond_lacp.webp b/docs/_static/images/vyos_arista_bond_lacp.webp Binary files differnew file mode 100644 index 00000000..6ac71379 --- /dev/null +++ b/docs/_static/images/vyos_arista_bond_lacp.webp diff --git a/docs/_static/images/vyosnew-downloads.webp b/docs/_static/images/vyosnew-downloads.webp Binary files differnew file mode 100644 index 00000000..fbbb21c8 --- /dev/null +++ b/docs/_static/images/vyosnew-downloads.webp diff --git a/docs/_static/images/wireguard_qrcode.webp b/docs/_static/images/wireguard_qrcode.webp Binary files differnew file mode 100644 index 00000000..7eb02d79 --- /dev/null +++ b/docs/_static/images/wireguard_qrcode.webp diff --git a/docs/_static/images/wireguard_site2site_diagram.webp b/docs/_static/images/wireguard_site2site_diagram.webp Binary files differnew file mode 100644 index 00000000..9f73ad4e --- /dev/null +++ b/docs/_static/images/wireguard_site2site_diagram.webp diff --git a/docs/_static/images/zone-policy-diagram.webp b/docs/_static/images/zone-policy-diagram.webp Binary files differnew file mode 100644 index 00000000..850df285 --- /dev/null +++ b/docs/_static/images/zone-policy-diagram.webp diff --git a/docs/_swap.txt b/docs/_swap.txt new file mode 100644 index 00000000..9e18a829 --- /dev/null +++ b/docs/_swap.txt @@ -0,0 +1,210 @@ +# Incremental MyST swap list +# One page stem per line (relative to docs/, no extension) +# Pages listed here will render from MD instead of RST at build time. +# +# Default: every imported md-*.md page is listed below so MD is served +# by default. To revert a specific page back to RST, remove its line +# (or comment it out). + +404 +automation/cloud-init +automation/command-scripting +automation/index +automation/terraform/index +automation/terraform/terraformAWS +automation/terraform/terraformAZ +automation/terraform/terraformGoogle +automation/terraform/terraformvSphere +automation/terraform/terraformvyos +automation/vyos-ansible +automation/vyos-api +automation/vyos-napalm +automation/vyos-netmiko +automation/vyos-salt +cli +configexamples/autotest/DHCPRelay_through_GRE/DHCPRelay_through_GRE +configexamples/autotest/L3VPN_EVPN/L3VPN_EVPN +configexamples/autotest/OpenVPN_with_LDAP/OpenVPN_with_LDAP +configexamples/autotest/Wireguard/Wireguard +configexamples/autotest/tunnelbroker/tunnelbroker +configexamples/azure-vpn-bgp +configexamples/azure-vpn-dual-bgp +configexamples/bgp-ipv6-unnumbered +configexamples/firewall +configexamples/fwall-and-vrf +configexamples/ha +configexamples/index +configexamples/inter-vrf-routing-vrf-lite +configexamples/ipsec-cisco-policy-based +configexamples/ipsec-cisco-route-based +configexamples/ipsec-pa-route-based +configexamples/l3vpn-hub-and-spoke +configexamples/lac-lns +configexamples/nmp +configexamples/ospf-unnumbered +configexamples/pppoe-ipv6-basic +configexamples/qos +configexamples/segment-routing-isis +configexamples/wan-load-balancing +configexamples/zone-policy +configuration/container/index +configuration/firewall/bridge +configuration/firewall/flowtables +configuration/firewall/global-options +configuration/firewall/groups +configuration/firewall/index +configuration/firewall/ipv4 +configuration/firewall/ipv6 +configuration/firewall/zone +configuration/highavailability/index +configuration/index +configuration/interfaces/bonding +configuration/interfaces/bridge +configuration/interfaces/dummy +configuration/interfaces/ethernet +configuration/interfaces/geneve +configuration/interfaces/index +configuration/interfaces/l2tpv3 +configuration/interfaces/loopback +configuration/interfaces/macsec +configuration/interfaces/openvpn +configuration/interfaces/pppoe +configuration/interfaces/pseudo-ethernet +configuration/interfaces/sstp-client +configuration/interfaces/tunnel +configuration/interfaces/virtual-ethernet +configuration/interfaces/vti +configuration/interfaces/vxlan +configuration/interfaces/wireguard +configuration/interfaces/wireless +configuration/interfaces/wwan +configuration/loadbalancing/index +configuration/loadbalancing/reverse-proxy +configuration/loadbalancing/wan +configuration/nat/index +configuration/nat/nat44 +configuration/nat/nat64 +configuration/nat/nat66 +configuration/pki/index +configuration/policy/access-list +configuration/policy/as-path-list +configuration/policy/community-list +configuration/policy/examples +configuration/policy/extcommunity-list +configuration/policy/index +configuration/policy/large-community-list +configuration/policy/local-route +configuration/policy/prefix-list +configuration/policy/route +configuration/policy/route-map +configuration/protocols/babel +configuration/protocols/bfd +configuration/protocols/bgp +configuration/protocols/failover +configuration/protocols/igmp-proxy +configuration/protocols/index +configuration/protocols/isis +configuration/protocols/mpls +configuration/protocols/ospf +configuration/protocols/pim +configuration/protocols/pim6 +configuration/protocols/rip +configuration/protocols/rpki +configuration/protocols/segment-routing +configuration/protocols/static +configuration/service/broadcast-relay +configuration/service/config-sync +configuration/service/conntrack-sync +configuration/service/console-server +configuration/service/dhcp-relay +configuration/service/dhcp-server +configuration/service/dns +configuration/service/eventhandler +configuration/service/https +configuration/service/ids +configuration/service/index +configuration/service/ipoe-server +configuration/service/lldp +configuration/service/mdns +configuration/service/monitoring +configuration/service/ntp +configuration/service/pppoe-server +configuration/service/router-advert +configuration/service/salt-minion +configuration/service/snmp +configuration/service/ssh +configuration/service/tftp-server +configuration/service/webproxy +configuration/system/acceleration +configuration/system/conntrack +configuration/system/console +configuration/system/default-route +configuration/system/flow-accounting +configuration/system/frr +configuration/system/host-name +configuration/system/index +configuration/system/ip +configuration/system/ipv6 +configuration/system/lcd +configuration/system/login +configuration/system/name-server +configuration/system/option +configuration/system/proxy +configuration/system/sflow +configuration/system/sysctl +configuration/system/syslog +configuration/system/task-scheduler +configuration/system/time-zone +configuration/system/updates +configuration/trafficpolicy/index +configuration/vpn/dmvpn +configuration/vpn/index +configuration/vpn/ipsec/index +configuration/vpn/ipsec/ipsec_general +configuration/vpn/ipsec/remoteaccess_ipsec +configuration/vpn/ipsec/site2site_ipsec +configuration/vpn/ipsec/troubleshooting_ipsec +configuration/vpn/l2tp +configuration/vpn/openconnect +configuration/vpn/pptp +configuration/vpn/rsa-keys +configuration/vpn/sstp +configuration/vrf/index +contributing/build-vyos +contributing/debugging +contributing/development +contributing/issues-features +contributing/testing +contributing/upstream-packages +coverage +documentation +index +installation/cloud/aws +installation/cloud/aws-ha +installation/cloud/aws-to-azure +installation/cloud/azure +installation/cloud/azure-ha +installation/cloud/gcp +installation/cloud/index +installation/cloud/oracel +installation/image +installation/index +installation/install +installation/update +installation/virtual/docker +installation/virtual/eve-ng +installation/virtual/gns3 +installation/virtual/index +installation/virtual/libvirt +installation/virtual/proxmox +installation/virtual/vmware +installation/vyos-on-baremetal +introducing/about +introducing/history +operation/boot-options +operation/index +operation/information +operation/password-recovery +operation/raid +quick-start +troubleshooting/index diff --git a/docs/automation/md-cloud-init.md b/docs/automation/md-cloud-init.md new file mode 100644 index 00000000..446d0f64 --- /dev/null +++ b/docs/automation/md-cloud-init.md @@ -0,0 +1,376 @@ +lastproofread +2021-07-12 + +# VyOS cloud-init + +Cloud and virtualized instances of VyOS are initialized using the +industry-standard cloud-init. Via cloud-init, the system performs tasks such as +injecting SSH keys and configuring the network. In addition, the user can supply +a custom configuration at the time of instance launch. + +## Config Sources + +VyOS support three types of config sources. + +- Metadata - Metadata is sourced by the cloud platform or hypervisor. + In some clouds, there is implemented as an HTTP endpoint at + `http://169.254.169.254`. +- Network configuration - This config source informs the system about the + network settings like IP addresses, routes, DNS. Available only in several + cloud and virtualization platforms. +- User-data - User-data is specified by the user. This config source offers the + ability to insert any CLI configuration commands into the configuration before + the first boot. + +## User-data + +Major cloud providers offer a means of providing user-data at the time of +instance launch. It can be provided as plain text or as base64-encoded text, +depending on cloud provider. Also, it can be compressed using gzip, which makes +sense with a long configuration commands list, because of the hard limit to +~16384 bytes for the whole user-data. + +The easiest way to configure the system via user-data is the Cloud-config syntax +described below. + +## Cloud-config modules + +In VyOS, by default, enables only two modules: + +- `write_files` - this module allows to insert any files into the filesystem + before the first boot, for example, pre-generated encryption keys, + certificates, or even a whole `config.boot` file. The format is described in the cloudinit documentation [Cloud-init-write_files](https://cloudinit.readthedocs.io/en/latest/topics/examples.html#writing-out-arbitrary-files). +- `vyos_userdata` - the module accepts a list of CLI configuration commands in + a `vyos_config_commands` section, which gives an easy way to configure the + system during deployment. + +## cloud-config file format + +A cloud-config document is written in YAML. The file must begin +with `#cloud-config` line. The only supported top-level keys are +`vyos_config_commands` and `write_files`. The use of these keys is described +in the following two sections. + +## Initial Configuration + +The key used to designate a VyOS configuration is `vyos_config_commands`. +What follows is VyOS configuration using the "set-style" syntax. Both "set" +and "delete" commands are supported. + +Commands requirements: + +- One command per line. +- If command ends in a value, it must be inside single quotes. +- A single-quote symbol is not allowed inside command or value. + +The commands list produced by the `show configuration commands` command on a +VyOS router should comply with all the requirements, so it is easy to get a +proper commands list by copying it from another router. + +The configuration specified in the cloud-config document overwrites default +configuration values and values configured via Metadata. + +Here is an example cloud-config that appends configuration at the time of +first boot. + +``` yaml +#cloud-config +vyos_config_commands: + - set system host-name 'vyos-prod-ashburn' + - set service ntp server 1.pool.ntp.org + - set service ntp server 2.pool.ntp.org + - delete interfaces ethernet eth1 address 'dhcp' + - set interfaces ethernet eth1 address '192.0.2.247/24' + - set protocols static route 198.51.100.0/24 next-hop '192.0.2.1' +``` + +### System Defaults/Fallbacks + +These are the VyOS defaults and fallbacks. + +- SSH is configured on port 22. +- `vyos`/`vyos` credentials if no others specified by data source. +- DHCP on first Ethernet interface if no network configuration is provided. + +All of these can be overridden using the configuration in user-data. + +## Command Execution at Initial Boot + +VyOS supports the execution of operational commands and linux commands at +initial boot. This is accomplished using `write_files` to certain +files in the /opt/vyatta/etc/config/scripts directory. Commands specified +in opt/vyatta/etc/config/scripts/vyos-preconfig-bootup.script are executed +prior to configuration. The +/opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script file contains +commands to be executed after configuration. In both cases, commands are +executed as the root user. + +Note that the /opt/vyatta/etc/config is used instead of the /config/scripts +directory referenced in the `command-scripting` section of the +documentation because the /config/script directory isn't mounted when the +`write_files` module executes. + +The following example shows how to execute commands after the initial +configuration. + +``` yaml +#cloud-config +write_files: + - path: /opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script + owner: root:vyattacfg + permissions: '0775' + content: | + #!/bin/vbash + source /opt/vyatta/etc/functions/script-template + filename=/tmp/bgp_status_`date +"%Y_%m_%d_%I_%M_%p"`.log + run show ip bgp summary >> $filename +``` + +If you need to gather information from linux commands to configure VyOS, you +can execute commands and then configure VyOS in the same script. + +The following example sets the hostname based on the instance identifier +obtained from the EC2 metadata service. + +Please observe that the same configuration pitfall described in `command-scripting` +exists here when running `configure` in any context as without user group +'vyattacfg' will cause the error message `Set failed` to appear. +We therefore need to wrap it and have the script re-execute itself with the correct +group permissions. + +``` yaml +#cloud-config +write_files: + - path: /opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script + owner: root:vyattacfg + permissions: '0775' + content: | + #!/bin/vbash + if [ "$(id -g -n)" != 'vyattacfg' ] ; then + exec sg vyattacfg -c "/bin/vbash $(readlink -f $0) $@" + fi + source /opt/vyatta/etc/functions/script-template + hostname=`curl -s http://169.254.169.254/latest/meta-data/instance-id` + configure + set system host-name $hostname + commit + exit +``` + +## NoCloud + +Injecting configuration data is not limited to cloud platforms. Users can +employ the NoCloud data source to inject user-data and meta-data on +virtualization platforms such as VMware, Hyper-V and KVM. + +While other methods exist, the most straightforward method for using the +NoCloud data source is creating a seed ISO and attaching it to the virtual +machine as a CD drive. The volume must be formatted as a vfat or ISO 9660 +file system with the label "cidata" or "CIDATA". + +Create text files named user-data and meta-data. On linux-based systems, +the mkisofs utility can be used to create the seed ISO. The following +syntax will add these files to the ISO 9660 file system. + +``` none +mkisofs -joliet -rock -volid "cidata" -output seed.iso meta-data user-data +``` + +The seed.iso file can be attached to the virtual machine. As an example, +the method with KVM to attach the ISO as a CD drive follows. + +``` none +$ virt-install -n vyos_r1 \ + --ram 4096 \ + --vcpus 2 \ + --cdrom seed.iso \ + --os-type linux \ + --os-variant debian10 \ + --network network=default \ + --graphics vnc \ + --hvm \ + --virt-type kvm \ + --disk path=/var/lib/libvirt/images/vyos_kvm.qcow2,bus=virtio \ + --import \ + --noautoconsole +``` + +For more information on the NoCloud data source, visit its [page](https://cloudinit.readthedocs.io/en/latest/reference/datasources/nocloud.html) +in the cloud-init documentation. + +## Troubleshooting + +If you encounter problems, verify that the cloud-config document contains +valid YAML. Online resources such as <https://www.yamllint.com/> provide +a simple tool for validating YAML. + +cloud-init logs to /var/log/cloud-init.log. This file can be helpful in +determining why the configuration varies from what you expect. You can fetch the +most important data filtering output for `vyos` keyword: + +``` none +sudo grep vyos /var/log/cloud-init.log +``` + +## Cloud-init on Proxmox + +Before starting, please refer to cloud-init [network-config-docs](https://cloudinit.readthedocs.io/en/latest/topics/network-config.html) in order to +know how to import user and network configurations. + +Most important keys that needs to be considered: + +- VyOS configuration commands are defined in user-data file. + +- Networking configurations shouldn't be passed in user-data file. + +- If no networking configuration is provided, then dhcp client is going to be + enabled on first interface. Bare in mind that this configuration will be + inyected at an OS level, so don't expect to find dhcp client configuration + on vyos cli. Because of this behavior, in next example lab we will disable + dhcp-client configuration on eth0. + + Also, this lab considers: + +- Proxmox IP address: **192.168.0.253/24** + +- Storaged used: volume local, which is mounted on directory **/var/lib/vz**, + and contains all type of content, including snippets. + +- Remove default dhcp client on first interface, and load other + configuration during first boot, using cloud-init. + +### Generate qcow image + +A VyOS qcow image with cloud-init options is needed. This can be obtained +using [vyos-vm-images](https://github.com/vyos/vyos-vm-images) repo. After cloning the repo, edit the file +**qemu.yml** and comment the **download-iso** role. + +In this lab, we are using 1.3.0 VyOS version and setting a disk of 10G. +Download VyOS .iso file and save it as `/tmp/vyos.iso`. Command used for +generating qcow image: + +``` sh +sudo ansible-playbook qemu.yml -e disk_size=10 \ + -e iso_local=/tmp/vyos.iso -e grub_console=serial -e vyos_version=1.3.0 \ + -e cloud_init=true -e cloud_init_ds=NoCloud +``` + +File generated with previous command: +`/tmp/vyos-1.3.0-cloud-init-10G-qemu.qcow2` + +Now, that file needs to be copied to proxmox server: + +``` sh +sudo scp /tmp/vyos-1.3.0-cloud-init-10G-qemu.qcow2 root@192.168.0.253:/tmp/ +``` + +### Prepare cloud-init files + +In Proxmox server three files are going to be used for this setup: + +- **network-config**: file that will indicate to avoid dhcp client on first + interface. +- **user-data**: includes vyos-commands. +- **meta-data**: empty file (required). + +In this lab, all files are located in `/tmp/`. So, before going on, lets +move to that directory: + +``` sh +cd /tmp/ +``` + +**user-data** file must start with `#cloud-config` and contains +vyos-commands. For example: + +``` none +#cloud-config +vyos_config_commands: + - set system host-name 'vyos-BRAS' + - set service ntp server 1.pool.ntp.org + - set service ntp server 2.pool.ntp.org + - delete interfaces ethernet eth0 address 'dhcp' + - set interfaces ethernet eth0 address '198.51.100.2/30' + - set interfaces ethernet eth0 description 'WAN - ISP01' + - set interfaces ethernet eth1 address '192.168.25.1/24' + - set interfaces ethernet eth1 description 'Comming through VLAN 25' + - set interfaces ethernet eth2 address '192.168.26.1/24' + - set interfaces ethernet eth2 description 'Comming through VLAN 26' + - set protocols static route 0.0.0.0/0 next-hop '198.51.100.1' +``` + +**network-config** file only has configuration that disables the automatic +dhcp client on first interface. + +Content of network-config file: + +``` none +version: 2 +ethernets: + eth0: + dhcp4: false + dhcp6: false +``` + +Finally, file **meta-data** has no content, but it's required. + +### Create seed.iso + +Once the three files were created, it's time to generate the `seed.iso` +image, which needs to be mounted to the new VM as a cd. + +Command for generating `seed.iso` + +``` sh +mkisofs -joliet -rock -volid "cidata" -output seed.iso meta-data \ +user-data network-config +``` + +**NOTE**: be careful while copying and pasting previous commands. Double +quotes may need to be corrected. + +### Creating the VM + +Notes for this particular example, that may need to be modified in other +setups: + +- VM ID: in this example, VM ID used is 555. +- VM Storage: `local` volume is used. +- ISO files storage: `local` volume is used for `.iso` file storage. In + this scenario `local` volume type is set to **directory**, abd attached to + `/var/lib/vz`. +- VM Resources: these parameters can be modified as needed. + +`seed.iso` was previously created in directory `/tmp/`. It's necessary to +move it to `/var/lib/vz/template/iso` + +``` sh +mv /tmp/seed.iso /var/lib/vz/template/iso/ +``` + +On proxmox server: + +``` none +## Create VM, import disk and define boot order +qm create 555 --name vyos-1.3.0-cloudinit --memory 1024 --net0 virtio,bridge=vmbr0 +qm importdisk 555 vyos-1.3.0-cloud-init-10G-qemu.qcow2 local +qm set 555 --virtio0 local:555/vm-555-disk-0.raw +qm set 555 --boot order=virtio0 + +## Import seed.iso for cloud init +qm set 555 --ide2 media=cdrom,file=local:iso/seed.iso + +## Since this server has 1 nic, lets add network intefaces (vlan 25 and 26) +qm set 555 --net1 virtio,bridge=vmbr0,firewall=1,tag=25 +qm set 555 --net2 virtio,bridge=vmbr0,firewall=1,tag=26 +``` + +### Power on VM and verifications + +From cli or GUI, power on VM, and after it boots, verify configuration + +### References + +- VyOS [cloud-init-docs](https://docs.vyos.io/en/equuleus/automation/cloud-init.html?highlight=cloud-init#vyos-cloud-init). +- Cloud-init [network-config-docs](https://cloudinit.readthedocs.io/en/latest/topics/network-config.html). +- Proxmox [Cloud-init-Support](https://pve.proxmox.com/pve-docs/pve-admin-guide.html#qm_cloud_init). diff --git a/docs/automation/md-command-scripting.md b/docs/automation/md-command-scripting.md new file mode 100644 index 00000000..5c2d8f19 --- /dev/null +++ b/docs/automation/md-command-scripting.md @@ -0,0 +1,219 @@ +lastproofread +2023-01-16 + +# Command Scripting + +VyOS supports executing configuration and operational commands non-interactively +from shell scripts. + +To include VyOS specific functions and aliases you need to `source /opt/vyatta/etc/functions/script-template` files at the top of your script. + +``` none +#!/bin/vbash +source /opt/vyatta/etc/functions/script-template +exit +``` + +## Run configuration commands + +Configuration commands are executed just like from a normal config session. For +example, if you want to disable a BGP peer on VRRP transition to backup: + +``` none +#!/bin/vbash +source /opt/vyatta/etc/functions/script-template +configure +set protocols bgp system-as 65536 +set protocols bgp neighbor 192.168.2.1 shutdown +commit +exit +``` + +## Run operational commands + +Unlike a normal configuration session, all operational commands must be +prepended with `run`, even if you haven't created a session with configure. + +``` none +#!/bin/vbash +source /opt/vyatta/etc/functions/script-template +run show interfaces +exit +``` + +## Run commands remotely + +Sometimes you simply want to execute a bunch of op-mode commands via SSH on +a remote VyOS system. + +``` none +ssh 192.0.2.1 'vbash -s' <<EOF +source /opt/vyatta/etc/functions/script-template +run show interfaces +exit +EOF +``` + +Will return: + +``` none +Welcome to VyOS +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +eth0 192.0.2.1/24 u/u +lo 127.0.0.1/8 u/u + ::1/128 +``` + +## Other script languages + +If you want to script the configs in a language other than bash you can have +your script output commands and then source them in a bash script. + +Here is a simple example: + +``` python +#!/usr/bin/env python3 +print("delete firewall group address-group somehosts") +print("set firewall group address-group somehosts address '192.0.2.3'") +print("set firewall group address-group somehosts address '203.0.113.55'") +``` + +``` none +#!/bin/vbash +source /opt/vyatta/etc/functions/script-template +configure +source < /config/scripts/setfirewallgroup.py +commit +``` + +## Executing Configuration Scripts + +There is a pitfall when working with configuration scripts. It is tempting to +call configuration scripts with "sudo" (i.e., temporary root permissions), +because that's the common way on most Linux platforms to call system commands. + +On VyOS this will cause the following problem: After modifying the configuration +via script like this once, it is not possible to manually modify the config +anymore: + +``` none +sudo ./myscript.sh # Modifies config +configure +set ... # Any configuration parameter +``` + +This will result in the following error message: `Set failed` If this happens, +a reboot is required to be able to edit the config manually again. + +To avoid these problems, the proper way is to call a script with the +`vyattacfg` group, e.g., by using the `sg` (switch group) command: + +``` none +sg vyattacfg -c ./myscript.sh +``` + +To make sure that a script is not accidentally called without the `vyattacfg` +group, the script can be safeguarded like this: + +``` none +if [ "$(id -g -n)" != 'vyattacfg' ] ; then + exec sg vyattacfg -c "/bin/vbash $(readlink -f $0) $@" +fi +``` + +## Executing pre-hooks/post-hooks Scripts + +VyOS has the ability to run custom scripts before and after each commit + +The default directories where your custom Scripts should be located are: + +``` none +/config/scripts/commit/pre-hooks.d - Directory with scripts that run before + each commit. + +/config/scripts/commit/post-hooks.d - Directory with scripts that run after + each commit. +``` + +Scripts are run in alphabetical order. Their names must consist entirely of +ASCII upper- and lower-case letters,ASCII digits, ASCII underscores, and +ASCII minus-hyphens.No other characters are allowed. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Custom scripts are not executed with root privileges +(Use sudo inside if this is necessary). + +</div> + +A simple example is shown below, where the ops command executed in +the post-hook script is "show interfaces". + +``` none +vyos@vyos# set interfaces ethernet eth1 address 192.0.2.3/24 +vyos@vyos# commit +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +eth0 198.51.100.10/24 u/u +eth1 192.0.2.3/24 u/u +eth2 - u/u +eth3 - u/u +lo 203.0.113.5/24 u/u +``` + +## Preconfig on boot + +The `/config/scripts/vyos-preconfig-bootup.script` script is called on boot +before the VyOS configuration during boot process. + +Any modifications were done to work around unfixed bugs and implement +enhancements that are not complete in the VyOS system can be placed here. + +The default file looks like this: + +``` none +#!/bin/sh +# This script is executed at boot time before VyOS configuration is applied. +# Any modifications required to work around unfixed bugs or use +# services not available through the VyOS CLI system can be placed here. +``` + +## Postconfig on boot + +The `/config/scripts/vyos-postconfig-bootup.script` script is called on boot +after the VyOS configuration is fully applied. + +Any modifications were done to work around unfixed bugs and implement +enhancements that are not complete in the VyOS system can be placed here. + +The default file looks like this: + +``` none +#!/bin/sh +# This script is executed at boot time after VyOS configuration is fully +# applied. Any modifications required to work around unfixed bugs or use +# services not available through the VyOS CLI system can be placed here. +``` + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +For configuration/upgrade management issues, modification of this +script should be the last option. Always try to find solutions based on CLI +commands first. + +</div> diff --git a/docs/automation/md-index.md b/docs/automation/md-index.md new file mode 100644 index 00000000..bf456f0d --- /dev/null +++ b/docs/automation/md-index.md @@ -0,0 +1,14 @@ +# VyOS Automation + +<div class="toctree" maxdepth="2"> + +vyos-api +vyos-ansible +terraform/index +vyos-napalm +vyos-netmiko +vyos-salt +command-scripting +cloud-init + +</div> diff --git a/docs/automation/md-vyos-ansible.md b/docs/automation/md-vyos-ansible.md new file mode 100644 index 00000000..ba348ca1 --- /dev/null +++ b/docs/automation/md-vyos-ansible.md @@ -0,0 +1,86 @@ +lastproofread +2023-01-16 + +# Ansible + +VyOS supports configuration via ansible. +Need to install `ansible` and `python3-paramiko` module + +Structure of files + +``` none +. +├── ansible.cfg +├── files +│ └── id_rsa_docker.pub +├── hosts +└── main.yml +``` + +## File contents + +ansible.cfg + +``` none +[defaults] +host_key_checking = no +retry_files_enabled = False +ANSIBLE_INVENTORY_UNPARSED_FAILED = true +``` + +id_rsa_docker.pub. Needs to declare only public key exactly. + +``` none +AAAAB3NzaC1yc2EAAAADAQABAAABAQCoDgfhQJuJRFWJijHn7ZinZ3NWp4hWVrt7HFcvn0kgtP/5PeCtMt +``` + +hosts + +``` none +[vyos_hosts] +r11 ansible_ssh_host=192.0.2.11 + +[vyos_hosts:vars] +ansible_python_interpreter=/usr/bin/python3 +ansible_user=vyos +ansible_ssh_pass=vyos +ansible_network_os=vyos +ansible_connection=network_cli +``` + +main.yml + +``` none +--- + +- hosts: r11 + + connection: network_cli + gather_facts: 'no' + + tasks: + - name: Configure remote r11 + vyos_config: + lines: + - set system host-name r11 + - set system name-server 203.0.113.254 + - set service ssh disable-host-validation + - set system login user vyos authentication public-keys docker@work type ssh-rsa + - set system login user vyos authentication public-keys docker@work key "{{ lookup('file', 'id_rsa_docker.pub') }}" + - set system time-zone America/Los_Angeles + - set interfaces ethernet eth0 description WAN +``` + +## Run ansible + +``` none +$ ansible-playbook -i hosts main.yml + +PLAY [r11] ****************************************************************************************************************************************************************************************************** + +TASK [Configure remote r11] ************************************************************************************************************************************************************************************* +changed: [r11] + +PLAY RECAP ***************************************************************************************************************************************************************************************************** +r11 : ok=1 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 +``` diff --git a/docs/automation/md-vyos-api.md b/docs/automation/md-vyos-api.md new file mode 100644 index 00000000..7618e262 --- /dev/null +++ b/docs/automation/md-vyos-api.md @@ -0,0 +1,380 @@ +lastproofread +2023-01-16 + +# VyOS API + +For configuration and enabling the API see `http-api` + +## Authentication + +All endpoints only listen on HTTP POST requests and the API KEY must set as +`key` in the formdata. + +Below see one example for curl and one for python. +The rest of the documentation is reduced to curl. + +``` none +curl --location --request POST 'https://vyos/retrieve' \ +--form data='{"op": "showConfig", "path": []}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' +``` + +``` python +import requests +url = "https://vyos/retrieve" +payload={'data': '{"op": "showConfig", "path": []}', + 'key': 'MY-HTTPS-API-PLAINTEXT-KEY' + } +headers = {} +response = requests.request("POST", url, headers=headers, data=payload) +print(response.text) +``` + +## API Endpoints + +### /retrieve + +With the `retrieve` endpoint you get parts or the whole configuration. + +To get the whole configuration, pass an empty list to the `path` field + +``` none +curl --location --request POST 'https://vyos/retrieve' \ +--form data='{"op": "showConfig", "path": []}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + + +response (shorted) +{ + "success": true, + "data": { + "interfaces": { + "ethernet": { + "eth0": { + "address": "dhcp", + "duplex": "auto", + "hw-id": "50:00:00:01:00:00", + "speed": "auto" + }, + "eth1": { + "duplex": "auto", + "hw-id": "50:00:00:01:00:01", + "speed": "auto" + ... + }, + "error": null +} +``` + +To only get a part of the configuration, for example `system syslog`. + +``` none +curl -k --location --request POST 'https://vyos/retrieve' \ +--form data='{"op": "showConfig", "path": ["system", "syslog"]}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + + +response: +{ + "success": true, + "data": { + "global": { + "facility": { + "all": { + "level": "info" + }, + "protocols": { + "level": "debug" + } + } + } + }, + "error": null +} +``` + +if you just want the Value of a multi-valued node, use the `returnValues` +operation. + +For example, get the addresses of a `dum0` interface. + +``` none +curl -k --location --request POST 'https://vyos/retrieve' \ +--form data='{"op": "returnValues", "path": ["interfaces","dummy","dum0","address"]}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +respone: +{ + "success": true, + "data": [ + "10.10.10.10/24", + "10.10.10.11/24", + "10.10.10.12/24" + ], + "error": null +} +``` + +To check existence of a configuration path, use the `exists` operation. + +For example, check an existing path: + +``` none +curl -k --location --request POST 'https://vyos/retrieve' \ +--form data='{"op": "exists", "path": ["service","https","api"]}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +response: +{ + "success": true, + "data": true, + "error": null +} +``` + +versus a non-existent path: + +``` none +curl -k --location --request POST 'https://vyos/retrieve' \ +--form data='{"op": "exists", "path": ["service","non","existent","path"]}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +response: +{ + "success": true, + "data": false, + "error": null +} +``` + +### /reset + +The `reset` endpoint run a `reset` command. + +``` none +curl --location --request POST 'https://vyos/reset' \ +--form data='{"op": "reset", "path": ["ip", "bgp", "192.0.2.11"]}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +respone: +{ + "success": true, + "data": "", + "error": null +} +``` + +### /reboot + +To initiate a reboot use the `reboot` endpoint. + +``` none +curl --location --request POST 'https://vyos/reboot' \ +--form data='{"op": "reboot", "path": ["now"]}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +respone: +{ + "success": true, + "data": "", + "error": null +} +``` + +### /poweroff + +To power off the system use the `poweroff` endpoint. + +``` none +curl --location --request POST 'https://vyos/poweroff' \ +--form data='{"op": "poweroff", "path": ["now"]}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +respone: +{ + "success": true, + "data": "", + "error": null +} +``` + +### /image + +To add or delete an image, use the `/image` endpoint. + +add an image + +``` none +curl -k --location --request POST 'https://vyos/image' \ +--form data='{"op": "add", "url": "https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso"}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +respone (shorted): +{ + "success": true, + "data": "Trying to fetch ISO file from https://downloads.vyos.io/rolling-latest.iso\n + ... + Setting up grub configuration...\nDone.\n", + "error": null +} +``` + +delete an image, for example `1.3-rolling-202006070117` + +``` none +curl -k --location --request POST 'https://vyos/image' \ +--form data='{"op": "delete", "name": "1.3-rolling-202006070117"}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +response: +{ + "success": true, + "data": "Deleting the \"1.3-rolling-202006070117\" image...\nDone\n", + "error": null +} +``` + +### /show + +The `/show` endpoint is to show everything in the operational mode. + +For example, show which images are installed. + +``` none +curl -k --location --request POST 'https://vyos/show' \ +--form data='{"op": "show", "path": ["system", "image"]}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +response: +{ + "success": true, + "data": "The system currently has the following image(s) installed:\n\n + 1: 1.4-rolling-202102280559 (default boot)\n + 2: 1.4-rolling-202102230218\n + 3: 1.3-beta-202102210443\n\n", + "error": null +} +``` + +### /generate + +The `generate` endpoint run a `generate` command. + +``` none +curl -k --location --request POST 'https://vyos/generate' \ +--form data='{"op": "generate", "path": ["pki", "wireguard", "key-pair"]}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +response: +{ + "success": true, + "data": "Private key: CFZR2eyhoVZwk4n3JFPMJx3E145f1EYgDM+ubytXYVY=\n + Public key: jjtpPT8ycI1Q0bNtrWuxAkO4k88Xwzg5VHV9xGZ58lU=\n\n", + "error": null +} +``` + +### /configure + +You can pass a `set`, `delete` or `comment` command to the +`/configure` endpoint. + +`set` a single command + +``` none +curl -k --location --request POST 'https://vyos/configure' \ +--form data='{"op": "set", "path": ["interfaces", "dummy", "dum1", "address", "10.11.0.1/32"]}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +response: +{ + "success": true, + "data": null, + "error": null +} +``` + +`delete` a single command + +``` none +curl -k --location --request POST 'https://vyos/configure' \ +--form data='{"op": "delete", "path": ["interfaces", "dummy", "dum1", "address", "10.11.0.1/32"]}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +response: +{ + "success": true, + "data": null, + "error": null +} +``` + +The API pushes every request to a session and commit it. +But some of VyOS components like DHCP and PPPoE Servers, IPSec, VXLAN, and +other tunnels require full configuration for commit. +The endpoint will process multiple commands when you pass them as a list to +the `data` field. + +``` none +curl -k --location --request POST 'https://vyos/configure' \ +--form data='[{"op": "set","path":["interfaces","vxlan","vxlan1","remote","203.0.113.99"]}, {"op": "set","path":["interfaces","vxlan","vxlan1","vni","1"]}]' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +response: +{ + "success": true, + "data": null, + "error": null +} +``` + +### /config-file + +The endpoint `/config-file` is to save or load a configuration. + +Save a running configuration to the startup configuration. +When you don't specify the file when saving, it saves to +`/config/config.boot`. + +``` none +curl -k --location --request POST 'https://vyos/config-file' \ +--form data='{"op": "save"}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +response: +{ + "success": true, + "data": "Saving configuration to '/config/config.boot'...\nDone\n", + "error": null +} +``` + +Save a running configuration to a file. + +``` none +curl -k --location --request POST 'https://vyos/config-file' \ +--form data='{"op": "save", "file": "/config/test.config"}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +response: +{ + "success": true, + "data": "Saving configuration to '/config/test.config'...\nDone\n", + "error": null +} +``` + +To Load a configuration file. + +``` none +curl -k --location --request POST 'https://vyos/config-file' \ +--form data='{"op": "load", "file": "/config/test.config"}' \ +--form key='MY-HTTPS-API-PLAINTEXT-KEY' + +response: +{ + "success": true, + "data": null, + "error": null +} +``` diff --git a/docs/automation/md-vyos-napalm.md b/docs/automation/md-vyos-napalm.md new file mode 100644 index 00000000..ca3fd97c --- /dev/null +++ b/docs/automation/md-vyos-napalm.md @@ -0,0 +1,137 @@ +lastproofread +2023-01-16 + +# Napalm + +VyOS supports some [napalm](https://napalm.readthedocs.io/en/latest/base.html) functions for configuration and op-mode. +It requires more tests. + +Install `napalm-vyos` module + +``` none +apt install python3-pip +pip3 install napalm +pip3 install napalm-vyos +``` + +## Op-mode + +``` none +#!/usr/bin/env python3 + +import json +from napalm import get_network_driver + +driver = get_network_driver('vyos') + +vyos_router = driver( + hostname="192.0.2.1", + username="vyos", + password="vyospass", + optional_args={"port": 22}, +) + +vyos_router.open() +output = vyos_router.get_facts() +print(json.dumps(output, indent=4)) + +output = vyos_router.get_arp_table() +print(json.dumps(output, indent=4)) + +vyos_router.close() +``` + +Output op-mode + +``` none +$ ./vyos-napalm.py +{ + "uptime": 7185, + "vendor": "VyOS", + "os_version": "1.3.0-rc5", + "serial_number": "", + "model": "Standard PC (Q35 + ICH9, 2009)", + "hostname": "r4-1.3", + "fqdn": "vyos.local", + "interface_list": [ + "eth0", + "eth1", + "eth2", + "lo", + "vtun10" + ] +} +[ + { + "interface": "eth1", + "mac": "52:54:00:b2:38:2c", + "ip": "192.0.2.2", + "age": 0.0 + }, + { + "interface": "eth0", + "mac": "52:54:00:a2:b9:5b", + "ip": "203.0.113.11", + "age": 0.0 + } +] +``` + +## Configuration + +We need 2 files, commands.conf and script itself. + +Content of commands.conf + +``` none +set service ssh disable-host-validation +set service ssh port '2222' +set system name-server '192.0.2.8' +set system name-server '203.0.113.8' +set interfaces ethernet eth1 description 'FOO' +``` + +Script vyos-napalm.py + +``` none +#!/usr/bin/env python3 + +from napalm import get_network_driver + +driver = get_network_driver('vyos') + +vyos_router = driver( + hostname="192.0.2.1", + username="vyos", + password="vyospass", + optional_args={"port": 22}, +) + +vyos_router.open() +vyos_router.load_merge_candidate(filename='commands.conf') +diffs = vyos_router.compare_config() + +if bool(diffs) == True: + print(diffs) + vyos_router.commit_config() +else: + print('No configuration changes to commit') + vyos_router.discard_config() + +vyos_router.close() +``` + +Output + +``` none +$./vyos-napalm.py +[edit interfaces ethernet eth1] ++description FOO +[edit service ssh] ++disable-host-validation ++port 2222 +[edit system] ++name-server 192.0.2.8 ++name-server 203.0.113.8 +[edit] +``` diff --git a/docs/automation/md-vyos-netmiko.md b/docs/automation/md-vyos-netmiko.md new file mode 100644 index 00000000..84622a0d --- /dev/null +++ b/docs/automation/md-vyos-netmiko.md @@ -0,0 +1,67 @@ +lastproofread +2023-01-16 + +# Netmiko + +VyOS supports configuration via [netmiko](https://github.com/ktbyers/netmiko). +It requires to install `python3-netmiko` module. + +## Example + +``` none +#!/usr/bin/env python3 + +from netmiko import ConnectHandler + +vyos_router = { + "device_type": "vyos", + "host": "192.0.2.1", + "username": "vyos", + "password": "vyospass", + "port": 22, + } + +net_connect = ConnectHandler(**vyos_router) + +config_commands = [ + 'set interfaces ethernet eth0 description WAN', + 'set interfaces ethernet eth1 description LAN', + ] + +# set configuration +output = net_connect.send_config_set(config_commands, exit_config_mode=False) +print(output) + +# commit configuration +output = net_connect.commit() +print(output) + +# op-mode commands +output = net_connect.send_command("run show interfaces") +print(output) +``` + +Output + +``` none +$ ./vyos-netmiko.py +configure +set interfaces ethernet eth0 description WAN +[edit] +vyos@r4-1.3# set interfaces ethernet eth1 description LAN +[edit] +vyos@r4-1.3# +commit +[edit] +vyos@r4-1.3# +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +eth0 203.0.113.1/24 u/u WAN +eth1 192.0.2.1/30 u/u LAN +eth2 - u/u +lo 127.0.0.1/8 u/u + ::1/128 +vtun10 10.10.0.1/24 u/u +[edit] +``` diff --git a/docs/automation/md-vyos-salt.md b/docs/automation/md-vyos-salt.md new file mode 100644 index 00000000..8b770a8f --- /dev/null +++ b/docs/automation/md-vyos-salt.md @@ -0,0 +1,204 @@ +lastproofread +2023-01-16 + +<div id="vyos-salt"> + +</div> + +# Salt + +VyOS supports op-mode and configuration via [salt](https://docs.saltproject.io/en/latest/contents.html). + +Without proxy it requires VyOS minion configuration +and supports op-mode data: + +``` none +set service salt-minion id 'r14' +set service salt-minion master '192.0.2.250' +``` + +Check salt-keys on the salt master + +``` none +/ # salt-key --list-all +Accepted Keys: +r11 +Denied Keys: +Unaccepted Keys: +r14 +Rejected Keys: +``` + +Accept minion key + +``` none +/ # salt-key --accept r14 +The following keys are going to be accepted: +Unaccepted Keys: +r14 +Proceed? [n/Y] y +Key for minion r14 accepted. +``` + +Check that salt master can communicate with minions + +``` none +/ # salt '*' test.ping +r14: + True +r11: + True +``` + +At this step we can get some op-mode information from VyOS nodes: + +``` none +/ # salt '*' network.interface eth0 +r11: + |_ + ---------- + address: + 192.0.2.11 + broadcast: + 192.0.2.255 + label: + eth0 + netmask: + 255.255.255.0 +r14: + |_ + ---------- + address: + 192.0.2.14 + broadcast: + 192.0.2.255 + label: + eth0 + netmask: + 255.255.255.0 + + +/ # salt r14 network.arp +r14: + ---------- + aa:bb:cc:dd:f3:db: + 192.0.2.1 + aa:bb:cc:dd:2e:80: + 203.0.113.1 +``` + +## Netmiko-proxy + +It is possible to configure VyOS via [netmiko](https://docs.saltproject.io/en/latest/ref/modules/all/salt.modules.netmiko_mod.html#module-salt.modules.netmiko_mod) proxy module. +It requires a minion with installed packet `python3-netmiko` module +who has a connection to VyOS nodes. Salt-minion have to communicate +with salt master + +### Configuration + +Salt master configuration: + +``` none +/ # cat /etc/salt/master +file_roots: + base: + - /srv/salt/states + +pillar_roots: + base: + - /srv/salt/pillars +``` + +Structure of /srv/salt: + +``` none +/ # tree /srv/salt/ +/srv/salt/ +|___ pillars +| |__ r11-proxy.sls +| |__ top.sls +|___ states + |__ commands.txt +``` + +top.sls + +``` none +/ # cat /srv/salt/pillars/top.sls +base: + r11-proxy: + - r11-proxy +``` + +r11-proxy.sls Includes parameters for connecting to salt-proxy minion + +``` none +/ # cat /srv/salt/pillars/r11-proxy.sls +proxy: + proxytype: netmiko # how to connect to proxy minion, change it + device_type: vyos # + host: 192.0.2.250 + username: user + password: secret_passwd +``` + +commands.txt + +``` none +/ # cat /srv/salt/states/commands.txt +set interfaces ethernet eth0 description 'WAN' +set interfaces ethernet eth1 description 'LAN' +``` + +Check that proxy minion is alive: + +``` none +/ # salt r11-proxy test.ping +r11-proxy: + True +/ # +``` + +### Examples + +Example of op-mode: + +``` none +/ # salt r11-proxy netmiko.send_command 'show interfaces ethernet eth0 brief' host=192.0.2.14 device_type=vyos username=vyos password=vyos +r11-proxy: + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 192.0.2.14/24 u/u Upstream +/ # +``` + +Example of configuration: + +``` none +/ # salt r11-proxy netmiko.send_config config_commands=['set interfaces ethernet eth0 description Link_to_WAN'] commit=True host=192.0.2.14 device_type=vyos username=vyos password=vyos +r11-proxy: + configure + set interfaces ethernet eth0 description Link_to_WAN + [edit] + vyos@r14# commit + [edit] + vyos@r14# +/ # +``` + +Example of configuration commands from the file "/srv/salt/states/commands.txt" + +``` none +/ # salt r11-proxy netmiko.send_config config_file=salt://commands.txt commit=True host=192.0.2.11 device_type=vyos username=vyos password=vyos +r11-proxy: + configure + set interfaces ethernet eth0 description 'WAN' + [edit] + vyos@r1# set interfaces ethernet eth1 description 'LAN' + [edit] + vyos@r1# commit + [edit] + vyos@r1# +/ # +``` diff --git a/docs/automation/terraform/md-index.md b/docs/automation/terraform/md-index.md new file mode 100644 index 00000000..9d02b913 --- /dev/null +++ b/docs/automation/terraform/md-index.md @@ -0,0 +1,11 @@ +# VyOS Terraform + +<div class="toctree" maxdepth="1" caption="Content"> + +terraformvyos +terraformAWS +terraformAZ +terraformvSphere +terraformGoogle + +</div> diff --git a/docs/automation/terraform/md-terraformAWS.md b/docs/automation/terraform/md-terraformAWS.md new file mode 100644 index 00000000..7485b3eb --- /dev/null +++ b/docs/automation/terraform/md-terraformAWS.md @@ -0,0 +1,493 @@ +lastproofread +2024-01-11 + +# Deploying VyOS in the AWS cloud + +With the help of Terraform, you can quickly deploy VyOS-based infrastructure in the AWS cloud. If necessary, the infrastructure can be removed using terraform. +Also we will make provisioning using Ansible. + +<img src="/_static/images/aws.webp" class="align-center" style="width:50.0%" alt="Network Topology Diagram" /> + +In this case, we'll create the necessary files for Terraform and Ansible next using Terraform we'll create a single instance on the AWS cloud and make provisioning using Ansible. + +## Preparation steps for deploying VyOS on AWS + +How to create a single instance and install your configuration using Terraform+Ansible+AWS +Step by step: + +AWS + +1 Create an account with AWS and get your "access_key", "secret key" + +2 Create a key [pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/create-key-pairs.html) and download your .pem key + +<img src="/_static/images/keypairs.webp" class="align-center" style="width:50.0%" alt="Network Topology Diagram" /> + +3 Create a security [group](https://docs.aws.amazon.com/cli/latest/userguide/cli-services-ec2-sg.html) for the new VyOS instance and open all traffic + +<img src="/_static/images/sg.webp" class="align-center" style="width:50.0%" alt="Network Topology Diagram" /> + +<img src="/_static/images/traffic.webp" class="align-center" style="width:50.0%" alt="Network Topology Diagram" /> + +Terraform + +> 1 Create an UNIX or Windows instance +> +> 2 Download and install Terraform +> +> 3 Create the folder for example /root/awsterraform + +``` none +mkdir /root/awsterraform + + 4 Copy all files into your Terraform project "/root/awsterraform" (vyos.tf, var.tf, terraform.tfvars,version.tf), more detailed see `Structure of files Terrafom for AWS`_ + + 5 Type the commands : +``` + +``` none +cd /<your folder> +terraform init +``` + +Ansible + +> 1 Create an UNIX instance whenever you want (local, cloud, and so on) +> +> 2 Download and install Ansible +> +> 3 Create the folder for example /root/aws/ +> +> 4 Copy all files into your Ansible project "/root/aws/" (ansible.cfg, instance.yml, mykey.pem and "all"), more detailed see [Structure of files Ansible for AWS](#structure-of-files-ansible-for-aws) + +mykey.pem you have to get using step 1.2 + +Start + +Type the commands on your Terrafom instance: + +``` none +cd /<your folder> +terraform plan +terraform apply +yes +``` + +## Start creating an AWS instance and check the result + +``` none +root@localhost:~/awsterraform# terraform apply + +Terraform used the selected providers to generate the following execution plan. +Resource actions are indicated with the following symbols: + + create + +Terraform will perform the following actions: + + # aws_instance.myVyOSec2 will be created + + resource "aws_instance" "myVyOSec2" { + + ami = "ami-************62c2d" + + arn = (known after apply) + + associate_public_ip_address = (known after apply) + + availability_zone = (known after apply) + + cpu_core_count = (known after apply) + + cpu_threads_per_core = (known after apply) + + disable_api_stop = (known after apply) + + disable_api_termination = (known after apply) + + ebs_optimized = (known after apply) + + get_password_data = false + + host_id = (known after apply) + + host_resource_group_arn = (known after apply) + + iam_instance_profile = (known after apply) + + id = (known after apply) + + instance_initiated_shutdown_behavior = (known after apply) + + instance_lifecycle = (known after apply) + + instance_state = (known after apply) + + instance_type = "t2.micro" + + ipv6_address_count = (known after apply) + + ipv6_addresses = (known after apply) + + key_name = "awsterraform" + + monitoring = (known after apply) + + outpost_arn = (known after apply) + + password_data = (known after apply) + + placement_group = (known after apply) + + placement_partition_number = (known after apply) + + primary_network_interface_id = (known after apply) + + private_dns = (known after apply) + + private_ip = (known after apply) + + public_dns = (known after apply) + + public_ip = (known after apply) + + secondary_private_ips = (known after apply) + + security_groups = [ + + "awsterraformsg", + ] + + source_dest_check = true + + spot_instance_request_id = (known after apply) + + subnet_id = (known after apply) + + tags = { + + "name" = "VyOS System" + } + + tags_all = { + + "name" = "VyOS System" + } + + tenancy = (known after apply) + + user_data = (known after apply) + + user_data_base64 = (known after apply) + + user_data_replace_on_change = false + + vpc_security_group_ids = (known after apply) + } + + # local_file.ip will be created + + resource "local_file" "ip" { + + content = (known after apply) + + content_base64sha256 = (known after apply) + + content_base64sha512 = (known after apply) + + content_md5 = (known after apply) + + content_sha1 = (known after apply) + + content_sha256 = (known after apply) + + content_sha512 = (known after apply) + + directory_permission = "0777" + + file_permission = "0777" + + filename = "ip.txt" + + id = (known after apply) + } + + # null_resource.SSHconnection1 will be created + + resource "null_resource" "SSHconnection1" { + + id = (known after apply) + } + + # null_resource.SSHconnection2 will be created + + resource "null_resource" "SSHconnection2" { + + id = (known after apply) + } + +Plan: 4 to add, 0 to change, 0 to destroy. + +Changes to Outputs: + + my_IP = (known after apply) + +Do you want to perform these actions? + Terraform will perform the actions described above. + Only 'yes' will be accepted to approve. + + Enter a value: yes + +aws_instance.myVyOSec2: Creating... +aws_instance.myVyOSec2: Still creating... [10s elapsed] +aws_instance.myVyOSec2: Still creating... [20s elapsed] +aws_instance.myVyOSec2: Still creating... [30s elapsed] +aws_instance.myVyOSec2: Still creating... [40s elapsed] +aws_instance.myVyOSec2: Creation complete after 44s [id=i-09edfca15aac2fe0a] +null_resource.SSHconnection1: Creating... +null_resource.SSHconnection2: Creating... +null_resource.SSHconnection1: Provisioning with 'file'... +null_resource.SSHconnection2: Provisioning with 'remote-exec'... +null_resource.SSHconnection2 (remote-exec): Connecting to remote host via SSH... +null_resource.SSHconnection2 (remote-exec): Host: 10.217.80.104 +null_resource.SSHconnection2 (remote-exec): User: root +null_resource.SSHconnection2 (remote-exec): Password: true +null_resource.SSHconnection2 (remote-exec): Private key: false +null_resource.SSHconnection2 (remote-exec): Certificate: false +null_resource.SSHconnection2 (remote-exec): SSH Agent: false +null_resource.SSHconnection2 (remote-exec): Checking Host Key: false +null_resource.SSHconnection2 (remote-exec): Target Platform: unix +local_file.ip: Creating... +local_file.ip: Creation complete after 0s [id=e8e91f2e24579cd28b92e2d152c0c24c3bf4b52c] +null_resource.SSHconnection2 (remote-exec): Connected! +null_resource.SSHconnection1: Creation complete after 0s [id=7070868940858935600] + +null_resource.SSHconnection2 (remote-exec): PLAY [integration of terraform and ansible] ************************************ + +null_resource.SSHconnection2 (remote-exec): TASK [Wait 300 seconds, but only start checking after 60 seconds] ************** +null_resource.SSHconnection2: Still creating... [10s elapsed] +null_resource.SSHconnection2: Still creating... [20s elapsed] +null_resource.SSHconnection2: Still creating... [30s elapsed] +null_resource.SSHconnection2: Still creating... [40s elapsed] +null_resource.SSHconnection2: Still creating... [50s elapsed] +null_resource.SSHconnection2: Still creating... [1m0s elapsed] +null_resource.SSHconnection2 (remote-exec): ok: [54.xxx.xxx.xxx] + +null_resource.SSHconnection2 (remote-exec): TASK [Configure general settings for the vyos hosts group] ********************* +null_resource.SSHconnection2: Still creating... [1m10s elapsed] +null_resource.SSHconnection2 (remote-exec): changed: [54.xxx.xxx.xxx] + +null_resource.SSHconnection2 (remote-exec): PLAY RECAP ********************************************************************* +null_resource.SSHconnection2 (remote-exec): 54.xxx.xxx.xxx : ok=2 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + +null_resource.SSHconnection2: Creation complete after 1m16s [id=4902256962410024771] + +Apply complete! Resources: 4 added, 0 changed, 0 destroyed. + +Outputs: + +my_IP = "54.xxx.xxx.xxx" +``` + +After executing all the commands you will have your VyOS instance on the AWS cloud with your configuration, it's a very convenient desition. +If you need to delete the instance please type the command: + +``` none +terraform destroy +``` + +## Troubleshooting + +1 Ansible doesn't connect via SSH to your AWS instance: you have to check that your SSH key has copied into the path /root/aws/. +Also, increase the time in the file instance.yml from 300 sec to 500 sec or more. (It depends on your location). +Make sure that you have opened access to the instance in the security group. + +> 2 Terraform doesn't connect via SSH to your Ansible instance: you have to check the correct login and password in the part of the file VyOS. tf + +``` none +connection { + type = "ssh" + user = "root" # open root access using login and password on your Ansible + password = var.password # check password in the file terraform.tfvars isn't empty + host = var.host # check the correct IP address of your Ansible host +} +``` + +Make sure that Ansible is pinging from Terrafom. + +## Structure of files Terrafom for AWS + +``` none +. +├── vyos.tf # The main script +├── var.tf # The file of all variables in "vyos.tf" +├── versions.tf # File for the changing version of Terraform. +└── terraform.tfvars # The value of all variables (passwords, login, ip adresses and so on) +``` + +## File contents of Terrafom for AWS + +vyos.tf + +``` none +############################################################################## +# Build an VyOS VM from the Marketplace +# To finde nessesery AMI image_ in AWS +# +# In the script vyos.tf we'll use default values (you can chang it as you need) +# AWS Region = "us-east-1" +# AMI = "standard AMI of VyOS from AWS Marketplace" +# Size of VM = "t2.micro" +# AWS Region = "us-east-1" +# After deploying the AWS instance and getting an IP address, the IP address is copied into the file +#"ip.txt" and copied to the Ansible node for provisioning. +############################################################################## + +provider "aws" { + access_key = var.access + secret_key = var.secret + region = var.region +} + +variable "region" { + default = "us-east-1" + description = "AWS Region" +} + +variable "ami" { + default = "ami-**************3b3" # ami image please enter your details + description = "Amazon Machine Image ID for VyOS" +} + +variable "type" { + default = "t2.micro" + description = "Size of VM" +} + +# my resource for VyOS + +resource "aws_instance" "myVyOSec2" { + ami = var.ami + key_name = "awsterraform" # Please enter your details from 1.2 of Preparation steps for deploying VyOS on AWS + security_groups = ["awsterraformsg"] # Please enter your details from 1.3 of Preparation steps for deploying VyOS on AWS + instance_type = var.type + tags = { + name = "VyOS System" + } +} + +############################################################################## +# specific variable (to getting type "terraform plan"): +# aws_instance.myVyOSec2.public_ip - the information about public IP address +# of our instance, needs for provisioning and ssh connection from Ansible +############################################################################## + +output "my_IP"{ +value = aws_instance.myVyOSec2.public_ip +} + +############################################################################## +# +# IP of aws instance copied to a file ip.txt in local system Terraform +# ip.txt looks like: +# cat ./ip.txt +# ххх.ххх.ххх.ххх +############################################################################## + +resource "local_file" "ip" { + content = aws_instance.myVyOSec2.public_ip + filename = "ip.txt" +} + +#connecting to the Ansible control node using SSH connection + +############################################################################## +# Steps "SSHconnection1" and "SSHconnection2" need to get file ip.txt from the terraform node and start remotely the playbook of Ansible. +############################################################################## + +resource "null_resource" "SSHconnection1" { +depends_on = [aws_instance.myVyOSec2] +connection { + type = "ssh" + user = "root" + password = var.password + host = var.host +} + +#copying the ip.txt file to the Ansible control node from local system + + provisioner "file" { + source = "ip.txt" + destination = "/root/aws/ip.txt" # The folder of your Ansible project + } +} + +resource "null_resource" "SSHconnection2" { +depends_on = [aws_instance.myVyOSec2] +connection { + type = "ssh" + user = "root" + password = var.password + host = var.host +} +#command to run Ansible playbook on remote Linux OS +provisioner "remote-exec" { + inline = [ + "cd /root/aws/", + "ansible-playbook instance.yml" # more detailed in "File contents of Ansible for AWS" +] +} +} +``` + +var.tf + +``` none +variable "password" { + description = "pass for Ansible" + type = string + sensitive = true +} +variable "host"{ + description = "The IP of my Ansible" + type = string +} +variable "access" { + description = "my access_key for AWS" + type = string + sensitive = true +} +variable "secret" { + description = "my secret_key for AWS" + type = string + sensitive = true +} +``` + +versions.tf + +``` none +terraform { + required_providers { + aws = { + source = "hashicorp/aws" + version = "~> 5.0" + } + } +} +``` + +terraform.tfvars + +``` none +password = "" # password for Ansible SSH +host = "" # IP of my Ansible +access = "" # access_key for AWS +secret = "" # secret_key for AWS +``` + +## Structure of files Ansible for AWS + +``` none +. +├── group_vars + └── all +├── ansible.cfg +├── mykey.pem +└── instance.yml +``` + +## File contents of Ansible for AWS + +ansible.cfg + +``` none +[defaults] +inventory = /root/aws/ip.txt +host_key_checking= False +private_key_file = /root/aws/awsterraform.pem # check the name +remote_user=vyos +``` + +mykey.pem + +``` none +Copy your key.pem from AWS +``` + +instance.yml + +``` none +############################################################################## +# About tasks: +# "Wait 300 seconds, but only start checking after 60 seconds" - try to make ssh connection every 60 seconds until 300 seconds +# "Configure general settings for the VyOS hosts group" - make provisioning into AWS VyOS node +# You have to add all necessary cammans of VyOS under the block "lines:" +############################################################################## + + +- name: integration of terraform and ansible + hosts: all + gather_facts: 'no' + + tasks: + + - name: "Wait 300 seconds, but only start checking after 60 seconds" + wait_for_connection: + delay: 60 + timeout: 300 + + - name: "Configure general settings for the VyOS hosts group" + vyos_config: + lines: + - set system name-server xxx.xxx.xxx.xxx + save: + true +``` + +group_vars/all + +``` none +ansible_connection: ansible.netcommon.network_cli +ansible_network_os: vyos.vyos.vyos +ansible_user: vyos +``` + +## Sourse files for AWS from GIT + +All files about the article can be found [here](https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/AWS_terraform_ansible_single_vyos_instance-main) diff --git a/docs/automation/terraform/md-terraformAZ.md b/docs/automation/terraform/md-terraformAZ.md new file mode 100644 index 00000000..e4ed9de9 --- /dev/null +++ b/docs/automation/terraform/md-terraformAZ.md @@ -0,0 +1,466 @@ +lastproofread +2024-03-03 + +# Deploying VyOS in the Azure cloud + +With the help of Terraform, you can quickly deploy VyOS-based infrastructure in the Azure cloud. If necessary, the infrastructure can be removed using terraform. +Also we will make provisioning using Ansible. + +In this case, we'll create the necessary files for Terraform and Ansible next using Terraform we'll create a single instance on the Azure cloud and make provisioning using Ansible. + +## Preparation steps for deploying VyOS on Azure + +How to create a single instance and install your configuration using Terraform+Ansible+Azure +Step by step: + +Azure + +> 1 Create an account with Azure + +Terraform + +> 1 Create an UNIX or Windows instance +> +> 2 Download and install Terraform +> +> 3 Create the folder for example /root/azvyos/ + +``` none +mkdir /root/azvyos + + 4 Copy all files into your Terraform project "/root/azvyos" (vyos.tf, var.tf, terraform.tfvars), more detailed see `Structure of files Terrafom for Azure`_ + + 5 Login with Azure using the command +``` + +``` none +az login +``` + +2.6 Type the commands : + +``` none +cd /<your folder> +terraform init +``` + +Ansible + +> 1 Create an UNIX instance whenever you want (local, cloud, and so on) +> +> 2 Download and install Ansible +> +> 3 Create the folder for example /root/az/ +> +> 4 Copy all files into your Ansible project "/root/az/" (ansible.cfg, instance.yml,"all"), more detailed see [Structure of files Ansible for Azure](#structure-of-files-ansible-for-azure) + +Start + +Type the commands on your Terrafom instance: + +``` none +cd /<your folder> +terraform plan +terraform apply +yes +``` + +After executing all the commands you will have your VyOS instance on the Azure cloud with your configuration, it's a very convenient desition. +If you need to delete the instance please type the command: + +``` none +terraform destroy +``` + +## Structure of files Terrafom for Azure + +``` none +. +├── vyos.tf # The main script +├── var.tf # File for the changing version of Terraform. +└── terraform.tfvars # The value of all variables (passwords, login, ip adresses and so on) +``` + +## File contents of Terrafom for Azure + +vyos.tf + +``` none +############################################################################## +# HashiCorp Guide to Using Terraform on Azure +# This Terraform configuration will create the following: +# Resource group with a virtual network and subnet +# An VyOS server without ssh key (only login+password) +############################################################################## + +# Chouse a provider + +provider "azurerm" { + features {} +} + +# Create a resource group. In Azure every resource belongs to a +# resource group. + +resource "azurerm_resource_group" "azure_vyos" { + name = "${var.resource_group}" + location = "${var.location}" +} + +# The next resource is a Virtual Network. + +resource "azurerm_virtual_network" "vnet" { + name = "${var.virtual_network_name}" + location = "${var.location}" + address_space = ["${var.address_space}"] + resource_group_name = "${var.resource_group}" +} + +# Build a subnet to run our VMs in. + +resource "azurerm_subnet" "subnet" { + name = "${var.prefix}subnet" + virtual_network_name = "${azurerm_virtual_network.vnet.name}" + resource_group_name = "${var.resource_group}" + address_prefixes = ["${var.subnet_prefix}"] +} + +############################################################################## +# Build an VyOS VM from the Marketplace +# To finde nessesery image use the command: +# +# az vm image list --offer vyos --all +# +# Now that we have a network, we'll deploy an VyOS server. +# An Azure Virtual Machine has several components. In this example we'll build +# a security group, a network interface, a public ip address, a storage +# account and finally the VM itself. Terraform handles all the dependencies +# automatically, and each resource is named with user-defined variables. +############################################################################## + + +# Security group to allow inbound access on port 22 (ssh) + +resource "azurerm_network_security_group" "vyos-sg" { + name = "${var.prefix}-sg" + location = "${var.location}" + resource_group_name = "${var.resource_group}" + + security_rule { + name = "SSH" + priority = 100 + direction = "Inbound" + access = "Allow" + protocol = "Tcp" + source_port_range = "*" + destination_port_range = "22" + source_address_prefix = "${var.source_network}" + destination_address_prefix = "*" + } +} + +# A network interface. + +resource "azurerm_network_interface" "vyos-nic" { + name = "${var.prefix}vyos-nic" + location = "${var.location}" + resource_group_name = "${var.resource_group}" + + ip_configuration { + name = "${var.prefix}ipconfig" + subnet_id = "${azurerm_subnet.subnet.id}" + private_ip_address_allocation = "Dynamic" + public_ip_address_id = "${azurerm_public_ip.vyos-pip.id}" + } +} + +# Add a public IP address. + +resource "azurerm_public_ip" "vyos-pip" { + name = "${var.prefix}-ip" + location = "${var.location}" + resource_group_name = "${var.resource_group}" + allocation_method = "Dynamic" +} + +# Build a virtual machine. This is a standard VyOS instance from Marketplace. + +resource "azurerm_virtual_machine" "vyos" { + name = "${var.hostname}-vyos" + location = "${var.location}" + resource_group_name = "${var.resource_group}" + vm_size = "${var.vm_size}" + + network_interface_ids = ["${azurerm_network_interface.vyos-nic.id}"] + delete_os_disk_on_termination = "true" + +# To finde an information about the plan use the command: +# az vm image list --offer vyos --all + + plan { + publisher = "sentriumsl" + name = "vyos-1-3" + product = "vyos-1-2-lts-on-azure" + } + + storage_image_reference { + publisher = "${var.image_publisher}" + offer = "${var.image_offer}" + sku = "${var.image_sku}" + version = "${var.image_version}" + } + + storage_os_disk { + name = "${var.hostname}-osdisk" + managed_disk_type = "Standard_LRS" + caching = "ReadWrite" + create_option = "FromImage" + } + + os_profile { + computer_name = "${var.hostname}" + admin_username = "${var.admin_username}" + admin_password = "${var.admin_password}" + } + + os_profile_linux_config { + disable_password_authentication = false + } +} + +data "azurerm_public_ip" "example" { + depends_on = ["azurerm_virtual_machine.vyos"] + name = "vyos-ip" + resource_group_name = "${var.resource_group}" +} +output "public_ip_address" { + value = data.azurerm_public_ip.example.ip_address +} + +# IP of AZ instance copied to a file ip.txt in local system + +resource "local_file" "ip" { + content = data.azurerm_public_ip.example.ip_address + filename = "ip.txt" +} + +#Connecting to the Ansible control node using SSH connection + +resource "null_resource" "nullremote1" { +depends_on = ["azurerm_virtual_machine.vyos"] +connection { + type = "ssh" + user = "root" + password = var.password + host = var.host +} + +# Copying the ip.txt file to the Ansible control node from local system + + provisioner "file" { + source = "ip.txt" + destination = "/root/az/ip.txt" + } +} + +resource "null_resource" "nullremote2" { +depends_on = ["azurerm_virtual_machine.vyos"] +connection { + type = "ssh" + user = "root" + password = var.password + host = var.host +} + +# Command to run ansible playbook on remote Linux OS + +provisioner "remote-exec" { + + inline = [ + "cd /root/az/", + "ansible-playbook instance.yml" +] +} +} +``` + +var.tf + +``` none +############################################################################## +# Variables File +# +# Here is where we store the default values for all the variables used in our +# Terraform code. +############################################################################## + +variable "resource_group" { + description = "The name of your Azure Resource Group." + default = "my_resource_group" +} + +variable "prefix" { + description = "This prefix will be included in the name of some resources." + default = "vyos" +} + +variable "hostname" { + description = "Virtual machine hostname. Used for local hostname, DNS, and storage-related names." + default = "vyos_terraform" +} + +variable "location" { + description = "The region where the virtual network is created." + default = "centralus" +} + +variable "virtual_network_name" { + description = "The name for your virtual network." + default = "vnet" +} + +variable "address_space" { + description = "The address space that is used by the virtual network. You can supply more than one address space. Changing this forces a new resource to be created." + default = "10.0.0.0/16" +} + +variable "subnet_prefix" { + description = "The address prefix to use for the subnet." + default = "10.0.10.0/24" +} + +variable "storage_account_tier" { + description = "Defines the storage tier. Valid options are Standard and Premium." + default = "Standard" +} + +variable "storage_replication_type" { + description = "Defines the replication type to use for this storage account. Valid options include LRS, GRS etc." + default = "LRS" +} + +# The most chippers size + +variable "vm_size" { + description = "Specifies the size of the virtual machine." + default = "Standard_B1s" +} + +variable "image_publisher" { + description = "Name of the publisher of the image (az vm image list)" + default = "sentriumsl" +} + +variable "image_offer" { + description = "Name of the offer (az vm image list)" + default = "vyos-1-2-lts-on-azure" +} + +variable "image_sku" { + description = "Image SKU to apply (az vm image list)" + default = "vyos-1-3" +} + +variable "image_version" { + description = "Version of the image to apply (az vm image list)" + default = "1.3.3" +} + +variable "admin_username" { + description = "Administrator user name" + default = "vyos" +} + +variable "admin_password" { + description = "Administrator password" + type = string + sensitive = true +} + +variable "source_network" { + description = "Allow access from this network prefix. Defaults to '*'." + default = "*" +} + +variable "password" { + description = "pass for Ansible" + type = string + sensitive = true +} +variable "host"{ + description = "IP of my Ansible" +} +``` + +terraform.tfvars + +``` none +password = "" # password for Ansible SSH +host = "" # IP of my Ansible +``` + +## Structure of files Ansible for Azure + +``` none +. +├── group_vars + └── all +├── ansible.cfg +└── instance.yml +``` + +## File contents of Ansible for Azure + +ansible.cfg + +``` none +[defaults] +inventory = /root/az/ip.txt +host_key_checking= False +remote_user=vyos +``` + +instance.yml + +``` none +############################################################################## +# About tasks: +# "Wait 300 seconds, but only start checking after 60 seconds" - try to make ssh connection every 60 seconds until 300 seconds +# "Configure general settings for the VyOS hosts group" - make provisioning into Azure VyOS node +# You have to add all necessary cammans of VyOS under the block "lines:" +############################################################################## + + +- name: integration of terraform and ansible + hosts: all + gather_facts: 'no' + + tasks: + + - name: "Wait 300 seconds, but only start checking after 60 seconds" + wait_for_connection: + delay: 60 + timeout: 300 + + - name: "Configure general settings for the VyOS hosts group" + vyos_config: + lines: + - set system name-server xxx.xxx.xxx.xxx + save: + true +``` + +group_vars/all + +``` none +ansible_connection: ansible.netcommon.network_cli +ansible_network_os: vyos.vyos.vyos + +# user and password gets from terraform variables "admin_username" and "admin_password" in the file /root/azvyos/var.tf +ansible_user: vyos +ansible_ssh_pass: "{{ vault_vyos_ssh_pass }}" +``` + +## Sourse files for Azure from GIT + +All files about the article can be found [here](https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/Azure_terraform_ansible_single_vyos_instance-main) diff --git a/docs/automation/terraform/md-terraformGoogle.md b/docs/automation/terraform/md-terraformGoogle.md new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/docs/automation/terraform/md-terraformGoogle.md @@ -0,0 +1 @@ + diff --git a/docs/automation/terraform/md-terraformvSphere.md b/docs/automation/terraform/md-terraformvSphere.md new file mode 100644 index 00000000..2e5d3927 --- /dev/null +++ b/docs/automation/terraform/md-terraformvSphere.md @@ -0,0 +1,372 @@ +lastproofread +2024-03-03 + +# Deploying VyOS in the vSphere infrastructure + +With the help of Terraform, you can quickly deploy VyOS-based infrastructure in the vSphere. +Also we will make provisioning using Ansible. + +In this case, we'll create the necessary files for Terraform and Ansible next using Terraform we'll create a single instance on the vSphere cloud and make provisioning using Ansible. + +## Preparation steps for deploying VyOS on vSphere + +How to create a single instance and install your configuration using Terraform+Ansible+vSphere +Step by step: + +vSphere + +> 1 Collect all data in to file "terraform.tfvars" and create resources for example "terraform" + +Terraform + +> 1 Create an UNIX or Windows instance +> +> 2 Download and install Terraform +> +> 3 Create the folder for example /root/vsphereterraform + +``` none +mkdir /root/vsphereterraform + + + 4 Copy all files into your Terraform project "/root/vsphereterraform" (vyos.tf, var.tf, terraform.tfvars,version.tf), more detailed see `Structure of files Terrafom for vSphere`_ + + 5 Type the commands : +``` + +``` none +cd /<your folder> +terraform init +``` + +Ansible + +> 1 Create an UNIX instance whenever you want (local, cloud, and so on) +> +> 2 Download and install Ansible +> +> 3 Create the folder for example /root/vsphereterraform/ +> +> 4 Copy all files into your Ansible project "/root/vsphereterraform/" (ansible.cfg, instance.yml,"all"), more detailed see [Structure of files Ansible for vSphere](#structure-of-files-ansible-for-vsphere) + +Start + +Type the commands on your Terrafom instance: + +``` none +cd /<your folder> +terraform plan +terraform apply +yes +``` + +After executing all the commands you will have your VyOS instance on the vSphere with your configuration, it's a very convenient desition. +If you need to delete the instance please type the command: + +``` none +terraform destroy +``` + +## Structure of files Terrafom for vSphere + +``` none +. +├── vyos.tf # The main script +├── versions.tf # File for the changing version of Terraform. +├── var.tf # File for the changing version of Terraform. +└── terraform.tfvars # The value of all variables (passwords, login, ip adresses and so on) +``` + +## File contents of Terrafom for vSphere + +vyos.tf + +``` none +provider "vsphere" { + user = var.vsphere_user + password = var.vsphere_password + vsphere_server = var.vsphere_server + allow_unverified_ssl = true +} + +data "vsphere_datacenter" "datacenter" { + name = var.datacenter +} + +data "vsphere_datastore" "datastore" { + name = var.datastore + datacenter_id = data.vsphere_datacenter.datacenter.id +} + +data "vsphere_compute_cluster" "cluster" { + name = var.cluster + datacenter_id = data.vsphere_datacenter.datacenter.id +} + +data "vsphere_resource_pool" "default" { + name = format("%s%s", data.vsphere_compute_cluster.cluster.name, "/Resources/terraform") # set as you need + datacenter_id = data.vsphere_datacenter.datacenter.id +} + +data "vsphere_host" "host" { + name = var.host + datacenter_id = data.vsphere_datacenter.datacenter.id +} + +data "vsphere_network" "network" { + name = var.network_name + datacenter_id = data.vsphere_datacenter.datacenter.id +} + +# Deployment of VM from Remote OVF +resource "vsphere_virtual_machine" "vmFromRemoteOvf" { + name = var.remotename + datacenter_id = data.vsphere_datacenter.datacenter.id + datastore_id = data.vsphere_datastore.datastore.id + host_system_id = data.vsphere_host.host.id + resource_pool_id = data.vsphere_resource_pool.default.id + network_interface { + network_id = data.vsphere_network.network.id + } + wait_for_guest_net_timeout = 2 + wait_for_guest_ip_timeout = 2 + + ovf_deploy { + allow_unverified_ssl_cert = true + remote_ovf_url = var.url_ova + disk_provisioning = "thin" + ip_protocol = "IPv4" + ip_allocation_policy = "dhcpPolicy" + ovf_network_map = { + "Network 1" = data.vsphere_network.network.id + "Network 2" = data.vsphere_network.network.id + } + } + vapp { + properties = { + "password" = "12345678", + "local-hostname" = "terraform_vyos" + } + } +} + +output "ip" { + description = "default ip address of the deployed VM" + value = vsphere_virtual_machine.vmFromRemoteOvf.default_ip_address +} + +# IP of vSphere instance copied to a file ip.txt in local system + +resource "local_file" "ip" { + content = vsphere_virtual_machine.vmFromRemoteOvf.default_ip_address + filename = "ip.txt" +} + +#Connecting to the Ansible control node using SSH connection + +resource "null_resource" "nullremote1" { +depends_on = ["vsphere_virtual_machine.vmFromRemoteOvf"] +connection { + type = "ssh" + user = "root" + password = var.ansiblepassword + host = var.ansiblehost + +} + +# Copying the ip.txt file to the Ansible control node from local system + + provisioner "file" { + source = "ip.txt" + destination = "/root/vsphere/ip.txt" + } +} + +resource "null_resource" "nullremote2" { +depends_on = ["vsphere_virtual_machine.vmFromRemoteOvf"] +connection { + type = "ssh" + user = "root" + password = var.ansiblepassword + host = var.ansiblehost +} + +# Command to run ansible playbook on remote Linux OS + +provisioner "remote-exec" { + + inline = [ + "cd /root/vsphere/", + "ansible-playbook instance.yml" +] +} +} +``` + +versions.tf + +``` none +# Copyright (c) HashiCorp, Inc. +# SPDX-License-Identifier: MPL-2.0 + +terraform { + required_providers { + vsphere = { + source = "hashicorp/vsphere" + version = "2.4.0" + } + } +} +``` + +var.tf + +``` none +# Copyright (c) HashiCorp, Inc. +# SPDX-License-Identifier: MPL-2.0 + +variable "vsphere_server" { + description = "vSphere server" + type = string +} + +variable "vsphere_user" { + description = "vSphere username" + type = string +} + +variable "vsphere_password" { + description = "vSphere password" + type = string + sensitive = true +} + +variable "datacenter" { + description = "vSphere data center" + type = string +} + +variable "cluster" { + description = "vSphere cluster" + type = string +} + +variable "datastore" { + description = "vSphere datastore" + type = string +} + +variable "network_name" { + description = "vSphere network name" + type = string +} + +variable "host" { + description = "name if yor host" + type = string +} + +variable "remotename" { + description = "the name of you VM" + type = string +} + +variable "url_ova" { + description = "the URL to .OVA file or cloude store" + type = string +} + +variable "ansiblepassword" { + description = "Ansible password" + type = string +} + +variable "ansiblehost" { + description = "Ansible host name or IP" + type = string +} +``` + +terraform.tfvars + +``` none +vsphere_user = "" +vsphere_password = "" +vsphere_server = "" +datacenter = "" +datastore = "" +cluster = "" +network_name = "" +host = "" +url_ova = "" +ansiblepassword = "" +ansiblehost = "" +remotename = "" +``` + +## Structure of files Ansible for vSphere + +``` none +. +├── group_vars + └── all +├── ansible.cfg +└── instance.yml +``` + +## File contents of Ansible for vSphere + +ansible.cfg + +``` none +[defaults] +inventory = /root/vsphere/ip.txt +host_key_checking= False +remote_user=vyos +``` + +instance.yml + +``` none +############################################################################## +# About tasks: +# "Wait 300 seconds, but only start checking after 60 seconds" - try to make ssh connection every 60 seconds until 300 seconds +# "Configure general settings for the VyOS hosts group" - make provisioning into vSphere VyOS node +# You have to add all necessary commands of VyOS under the block "lines:" +############################################################################## + + +- name: integration of terraform and ansible + hosts: all + gather_facts: 'no' + + tasks: + + - name: "Wait 300 seconds, but only start checking after 60 seconds" + wait_for_connection: + delay: 60 + timeout: 300 + + - name: "Configure general settings for the VyOS hosts group" + vyos_config: + lines: + - set system name-server 8.8.8.8 + save: + true +``` + +group_vars/all + +``` none +ansible_connection: ansible.netcommon.network_cli +ansible_network_os: vyos.vyos.vyos + +# user and password gets from terraform variables "admin_username" and "admin_password" +ansible_user: vyos +# get from vyos.tf "vapp" +ansible_ssh_pass: 12345678 +``` + +## Sourse files for vSphere from GIT + +All files about the article can be found [here](https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/Vsphere_terraform_ansible_single_vyos_instance-main) diff --git a/docs/automation/terraform/md-terraformvyos.md b/docs/automation/terraform/md-terraformvyos.md new file mode 100644 index 00000000..78606cba --- /dev/null +++ b/docs/automation/terraform/md-terraformvyos.md @@ -0,0 +1,31 @@ +lastproofread +2024-03-03 + +# Terraform for VyOS + +VyOS supports development infrastructure via Terraform and provisioning via Ansible. +Terraform allows you to automate the process of deploying instances on many cloud and virtual platforms. +In this article, we will look at using terraforms to deploy VyOS on platforms - AWS, Azure, and vSphere. +For more details about Terraform please have a look here [link](https://developer.hashicorp.com/terraform/intro). + +Need to [install](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli) Terraform + +Structure of files in the standard Terraform project: + +``` none +. +├── main.tf # The main script +├── version.tf # File for the changing version of Terraform. +├── variables.tf # The file of all variables in "main.tf" +└── terraform.tfvars # The value of all variables (passwords, login, ip adresses and so on) +``` + +General commands that we will use for running Terraform scripts + +``` none +cd /<your folder> # go to the Terrafom project +terraform init # install all addons and provider (aws az and so on) +terraform plan # show what is changing +terraform apply # run script +yes # apply running +``` diff --git a/docs/conf.py b/docs/conf.py index 7d933306..bbc74ea8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -13,6 +13,7 @@ # documentation root, use os.path.abspath to make it absolute, like shown here. # import os +import shutil import sys sys.path.append(os.path.abspath("./_ext")) @@ -83,7 +84,23 @@ gettext_uuid = False # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path . -exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store', '_include/vyos-1x'] +exclude_patterns = [ + u'_build', 'Thumbs.db', '.DS_Store', '_include/vyos-1x', + 'md-*.md', '**/md-*.md', +] + +# MyST-Parser configuration +myst_enable_extensions = ["colon_fence", "deflist", "fieldlist", "substitution"] +myst_fence_as_directive = ["cfgcmd", "opcmd", "cmdincludemd"] + +# Incremental RST→MyST swap: extend exclude_patterns with the RST paths that +# swap_sources.py just hid behind their md-prefixed counterparts. +import pathlib +_build = pathlib.Path(__file__).parent / '_build' +if (_build / '_swap_state.json').exists() and (_build / '_swap_exclude.txt').exists(): + exclude_patterns.extend( + s for s in (line.strip() for line in (_build / '_swap_exclude.txt').read_text().splitlines()) if s + ) # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' @@ -193,5 +210,32 @@ texinfo_documents = [ ] +def _prefer_webp(app): + """Prepend WebP to supported image types for HTML builders so MyST pages + can use webp without falling back to PDF/PNG fallbacks.""" + if app.builder.name in ('html', 'dirhtml', 'readthedocs'): + types = app.builder.supported_image_types + if 'image/webp' not in types: + app.builder.supported_image_types = ['image/webp'] + types + + +def _copy_md_sources(app, exception): + """Copy .md source files verbatim into the HTML output tree. + + Skips md-*.md staging files (pre-swap originals that are not public). + """ + if exception is not None: + return + src = pathlib.Path(app.srcdir) + out = pathlib.Path(app.outdir) + for path in src.rglob("*.md"): + if path.name.startswith("md-"): + continue + dest = out / path.relative_to(src) + dest.parent.mkdir(parents=True, exist_ok=True) + shutil.copy2(path, dest) + + def setup(app): - pass + app.connect('builder-inited', _prefer_webp) + app.connect('build-finished', _copy_md_sources) diff --git a/docs/configexamples/autotest/DHCPRelay_through_GRE/_include/topology.webp b/docs/configexamples/autotest/DHCPRelay_through_GRE/_include/topology.webp Binary files differnew file mode 100644 index 00000000..592484cb --- /dev/null +++ b/docs/configexamples/autotest/DHCPRelay_through_GRE/_include/topology.webp diff --git a/docs/configexamples/autotest/DHCPRelay_through_GRE/md-DHCPRelay_through_GRE.md b/docs/configexamples/autotest/DHCPRelay_through_GRE/md-DHCPRelay_through_GRE.md new file mode 100644 index 00000000..179f7885 --- /dev/null +++ b/docs/configexamples/autotest/DHCPRelay_through_GRE/md-DHCPRelay_through_GRE.md @@ -0,0 +1,89 @@ +# DHCP Relay through GRE-Bridge + +Testdate: 2023-05-11\ +Version: 1.4-rolling-202305100734 + +This simple structure shows how to configure a DHCP Relay over a GRE Bridge +interface. + +## Topology + +The topology has 3 VyOS routers and one client. Between the DHCP Server and +the DHCP Relay is a GRE tunnel. The <span class="title-ref">transport</span> VyOS represent a large +Network. + + + +## Configuration + +First, we configure the transport network and the Tunnel interface. + +Transport: + +<div class="literalinclude" language="none"> + +<span id="include">include</span>/transport.conf + +</div> + +DHCP-Server + +<div class="literalinclude" language="none" lines="1-8"> + +<span id="include">include</span>/dhcp-server.conf + +</div> + +DHCP-Relay + +<div class="literalinclude" language="none" lines="1-8"> + +<span id="include">include</span>/dhcp-relay.conf + +</div> + +After this, we need the DHCP-Server and Relay configuration. +To get a testable result, we just have one IP in the DHCP range. +Expand it as you need it. + +DHCP-Server + +<div class="literalinclude" language="none" lines="9-13"> + +<span id="include">include</span>/dhcp-server.conf + +</div> + +DHCP-Relay + +<div class="literalinclude" language="none" lines="9-10"> + +<span id="include">include</span>/dhcp-relay.conf + +</div> + +## Test the result + +Ping the Client from the DHCP Server. + +``` none +vyos@dhcp-server:~$ ping 192.168.0.30 count 4 +PING 192.168.0.30 (192.168.0.30) 56(84) bytes of data. +64 bytes from 192.168.0.30: icmp_seq=1 ttl=63 time=1.02 ms +64 bytes from 192.168.0.30: icmp_seq=2 ttl=63 time=1.06 ms +64 bytes from 192.168.0.30: icmp_seq=3 ttl=63 time=1.21 ms +64 bytes from 192.168.0.30: icmp_seq=4 ttl=63 time=1.16 ms + +--- 192.168.0.30 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 3004ms +rtt min/avg/max/mdev = 1.016/1.112/1.214/0.077 ms +``` + +And show all DHCP Leases + +``` none +vyos@dhcp-server:~$ show dhcp server leases +IP Address MAC address State Lease start Lease expiration Remaining Pool Hostname +------------ ----------------- ------- ------------------- ------------------- ----------- ---------- ---------- +192.168.0.30 00:50:79:66:68:05 active 2023/05/11 13:08:50 2023/05/12 13:08:50 23:59:16 DHCPTun100 VPCS +``` diff --git a/docs/configexamples/autotest/L3VPN_EVPN/_include/topology.webp b/docs/configexamples/autotest/L3VPN_EVPN/_include/topology.webp Binary files differnew file mode 100644 index 00000000..f3218799 --- /dev/null +++ b/docs/configexamples/autotest/L3VPN_EVPN/_include/topology.webp diff --git a/docs/configexamples/autotest/L3VPN_EVPN/md-L3VPN_EVPN.md b/docs/configexamples/autotest/L3VPN_EVPN/md-L3VPN_EVPN.md new file mode 100644 index 00000000..c090c16e --- /dev/null +++ b/docs/configexamples/autotest/L3VPN_EVPN/md-L3VPN_EVPN.md @@ -0,0 +1,245 @@ +# L3VPN EVPN with VyOS + +Testdate: 2023-05-11\ +Version: 1.4-rolling-202305100734 + +I spun up a new lab in EVE-NG, which represents this as the +"Foo Bar - Service Provider Inc." that has 3 points of presence (PoP) in random +datacenters/sites named PE1, PE2, and PE3. Each PoP aggregates at least two +customers. + +I named the customers blue, red and green which is common practice in +VRF (Virtual Routing and Forwarding) documentation scenarios. + +- PE1 is located in an industrial area that holds multiple office buildings. + All customers have a site in this area. +- PE2 is located in a smaller area where by coincidence two customers + (blue and red) share an office building. +- PE3 is located in a smaller area where by coincidence two customers + (blue and green) are located. + +## Management VRF + +A brief excursion into VRFs: This has been one of the longest-standing feature +requests of VyOS (dating back to 2016) which can be described as +"a VLAN for layer 2 is what a VRF is for layer 3". +With VRFs, a router/system can hold multiple, isolated routing tables on the +same system. If you wonder what's the difference between multiple tables that +people used for policy-based routing since forever, it's that a VRF also +isolates connected routes rather than just static and dynamically learned +routes, so it allows NICs in different VRFs to use conflicting network +ranges without issues. + +VyOS 1.3 added initial support for VRFs (including IPv4/IPv6 static routing) +and VyOS 1.4 now enables full dynamic routing protocol support for +OSPF, IS-IS, and BGP for individual VRFs. + +The lab I built is using a VRF (called **mgmt**) to provide out-of-band +SSH access to the PE (Provider Edge) routers. + +<div class="literalinclude" language="none" lines="1-6"> + +<span id="include">include</span>/PE1.conf + +</div> + +## Topology + +We use the following network topology in this example: + + + +## Core network + +I chose to run OSPF as the IGP (Interior Gateway Protocol). +All required BGP sessions are established via a dummy interfaces +(similar to the loopback, but in Linux you can have only one loopback, +while there can be many dummy interfaces) on the PE routers. In case of a link +failure, traffic is diverted in the other direction in this triangle setup and +BGP sessions will not go down. One could even enable +BFD (Bidirectional Forwarding Detection) on the links for a faster +failover and resilience in the network. + +Regular VyOS users will notice that the BGP syntax has changed in VyOS 1.4 from +even the prior post about this subject. This is due to T1711, where it was +finally decided to get rid of the redundant BGP ASN (Autonomous System Number) +specification on the CLI and move it to a single leaf node +(set protocols bgp local-as). + +It's important to note that all your existing configurations will be migrated +automatically on image upgrade. Nothing to do on your side. + +PE1 + +<div class="literalinclude" language="none" lines="8-38"> + +<span id="include">include</span>/PE1.conf + +</div> + +PE2 + +<div class="literalinclude" language="none" lines="8-38"> + +<span id="include">include</span>/PE2.conf + +</div> + +PE3 + +<div class="literalinclude" language="none" lines="8-38"> + +<span id="include">include</span>/PE3.conf + +</div> + +## Tenant networks (VRFs) + +Once all routers can be safely remotely managed and the core network is +operational, we can now setup the tenant networks. + +Every tenant is assigned an individual VRF that would support overlapping +address ranges for customers blue, red and green. In our example, +we do not use overlapping ranges to make it easier when showing debug commands. + +Thus you can easily match it to one of the devices/networks below. + +Every router that provides access to a customer network needs to have the +customer network (VRF + VNI) configured. To make our own lives easier, +we utilize the same VRF table id (local routing table number) and +VNI (Virtual Network Identifier) per tenant on all our routers. + +- blue uses local routing table id and VNI 2000 +- red uses local routing table id and VNI 3000 +- green uses local routing table id and VNI 4000 + +PE1 + +<div class="literalinclude" language="none" lines="40-96"> + +<span id="include">include</span>/PE1.conf + +</div> + +PE2 + +<div class="literalinclude" language="none" lines="40-89"> + +<span id="include">include</span>/PE2.conf + +</div> + +PE3 + +<div class="literalinclude" language="none" lines="40-89"> + +<span id="include">include</span>/PE3.conf + +</div> + +## Testing and debugging + +You managed to come this far, now we want to see the network and routing +tables in action. + +Show routes for all VRFs + +``` none +vyos@PE1:~$ show ip route vrf all +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +VRF blue: +C>* 10.1.1.0/24 is directly connected, br2000, 00:01:13 +B>* 10.1.2.0/24 [200/0] via 172.29.255.2, br2000 onlink, weight 1, 00:00:49 +B>* 10.1.3.0/24 [200/0] via 172.29.255.3, br2000 onlink, weight 1, 00:00:49 + +VRF default: +O 172.29.0.2/31 [110/1] is directly connected, eth1, weight 1, 00:01:09 +C>* 172.29.0.2/31 is directly connected, eth1, 00:01:12 +O>* 172.29.0.4/31 [110/2] via 172.29.0.3, eth1, weight 1, 00:00:46 + * via 172.29.0.7, eth3, weight 1, 00:00:46 +O 172.29.0.6/31 [110/1] is directly connected, eth3, weight 1, 00:01:09 +C>* 172.29.0.6/31 is directly connected, eth3, 00:01:12 +C>* 172.29.255.1/32 is directly connected, dum0, 00:01:14 +O>* 172.29.255.2/32 [110/20] via 172.29.0.3, eth1, weight 1, 00:00:50 +O>* 172.29.255.3/32 [110/20] via 172.29.0.7, eth3, weight 1, 00:00:45 + +VRF green: +C>* 10.3.1.0/24 is directly connected, br4000, 00:01:13 +B>* 10.3.3.0/24 [200/0] via 172.29.255.3, br4000 onlink, weight 1, 00:00:49 + +VRF mgmt: +S>* 0.0.0.0/0 [210/0] via 10.100.0.1, eth0, weight 1, 00:01:45 +C>* 10.100.0.0/24 is directly connected, eth0, 00:01:45 + +VRF red: +C>* 10.2.1.0/24 is directly connected, br3000, 00:01:13 +B>* 10.2.2.0/24 [200/0] via 172.29.255.2, br3000 onlink, weight 1, 00:00:49 +``` + +Information about Ethernet Virtual Private Networks + +``` none +vyos@PE1:~$ show bgp l2vpn evpn +BGP table version is 1, local router ID is 172.29.255.1 +Status codes: s suppressed, d damped, h history, * valid, > best, i - internal +Origin codes: i - IGP, e - EGP, ? - incomplete +EVPN type-1 prefix: [1]:[EthTag]:[ESI]:[IPlen]:[VTEP-IP]:[Frag-id] +EVPN type-2 prefix: [2]:[EthTag]:[MAClen]:[MAC]:[IPlen]:[IP] +EVPN type-3 prefix: [3]:[EthTag]:[IPlen]:[OrigIP] +EVPN type-4 prefix: [4]:[ESI]:[IPlen]:[OrigIP] +EVPN type-5 prefix: [5]:[EthTag]:[IPlen]:[IP] + + Network Next Hop Metric LocPrf Weight Path +Route Distinguisher: 10.1.1.1:5 +*> [5]:[0]:[24]:[10.1.1.0] + 172.29.255.1 0 32768 ? + ET:8 RT:100:2000 Rmac:4e:bb:3c:ba:bd:a6 +Route Distinguisher: 10.1.2.1:4 +*>i[5]:[0]:[24]:[10.1.2.0] + 172.29.255.2 0 100 0 ? + RT:100:2000 ET:8 Rmac:26:07:da:eb:fc:ea +Route Distinguisher: 10.1.3.1:4 +*>i[5]:[0]:[24]:[10.1.3.0] + 172.29.255.3 0 100 0 ? + RT:100:2000 ET:8 Rmac:26:98:28:24:6e:54 +Route Distinguisher: 10.2.1.1:6 +*> [5]:[0]:[24]:[10.2.1.0] + 172.29.255.1 0 32768 ? + ET:8 RT:100:3000 Rmac:50:00:00:01:00:05 +Route Distinguisher: 10.2.2.1:5 +*>i[5]:[0]:[24]:[10.2.2.0] + 172.29.255.2 0 100 0 ? + RT:100:3000 ET:8 Rmac:50:00:00:02:00:05 +Route Distinguisher: 10.3.1.1:7 +*> [5]:[0]:[24]:[10.3.1.0] + 172.29.255.1 0 32768 ? + ET:8 RT:100:4000 Rmac:50:00:00:01:00:06 +Route Distinguisher: 10.3.3.1:6 +*>i[5]:[0]:[24]:[10.3.3.0] + 172.29.255.3 0 100 0 ? + RT:100:4000 ET:8 Rmac:06:32:9d:22:55:8a + +Displayed 7 out of 7 total prefixes +``` + +If we need to retrieve information about a specific host/network inside +the EVPN network we need to run + +``` none +vyos@PE2:~$ show bgp l2vpn evpn 10.3.1.10 +BGP routing table entry for 10.3.1.1:7:[5]:[0]:[24]:[10.3.1.0] +Paths: (1 available, best #1) + Not advertised to any peer + Route [5]:[0]:[24]:[10.3.1.0] VNI 4000 + Local + 172.29.255.1 (metric 20) from 172.29.255.1 (172.29.255.1) + Origin incomplete, metric 0, localpref 100, valid, internal, best (First path received) + Extended Community: RT:100:4000 ET:8 Rmac:50:00:00:01:00:06 + Last update: Thu May 11 13:31:13 2023 +``` diff --git a/docs/configexamples/autotest/OpenVPN_with_LDAP/_include/topology.webp b/docs/configexamples/autotest/OpenVPN_with_LDAP/_include/topology.webp Binary files differnew file mode 100644 index 00000000..13bf2d73 --- /dev/null +++ b/docs/configexamples/autotest/OpenVPN_with_LDAP/_include/topology.webp diff --git a/docs/configexamples/autotest/OpenVPN_with_LDAP/md-OpenVPN_with_LDAP.md b/docs/configexamples/autotest/OpenVPN_with_LDAP/md-OpenVPN_with_LDAP.md new file mode 100644 index 00000000..7e662cfd --- /dev/null +++ b/docs/configexamples/autotest/OpenVPN_with_LDAP/md-OpenVPN_with_LDAP.md @@ -0,0 +1,226 @@ +# OpenVPN with LDAP + +Testdate: 2023-05-11\ +Version: 1.4-rolling-202305100734 + +This LAB shows how to use OpenVPN with a Active Directory authentication method. + +Topology consists of: +- Windows Server 2019 with a running Active Directory +- VyOS as a OpenVPN Server +- VyOS as Client + + + +## Active Directory on Windows server + +The lab assumes a full running Active Directory on the Windows Server. +Here are some PowerShell commands to quickly add a Test Active Directory. + +``` powershell +# install the Active Directory Server role +Install-WindowsFeature AD-Domain-Services -IncludeManagementTools + +# install the Active Directory Server role +Install-ADDSForest -DomainName "vyos.local" -DomainNetBiosName "VYOS" -InstallDns:$true -NoRebootCompletion:$true + +# create test user01 and binduser +New-ADUser binduser -AccountPassword(Read-Host -AsSecureString "Input Password") -Enabled $true +New-ADUser user01 -AccountPassword(Read-Host -AsSecureString "Input Password") -Enabled $true +``` + +## Configure VyOS as OpenVPN Server + +In this example OpenVPN will be setup with a client certificate and username / password authentication. + +First a CA, a signed server and client ceftificate and a Diffie-Hellman parameter musst be generated and installed. +Please look `here <configuration/pki/index:pki>` for more information. + +Add the LDAP plugin configuration file <span class="title-ref">/config/auth/ldap-auth.config</span>\ +Check all possible settings [here](https://github.com/threerings/openvpn-auth-ldap/blob/master/auth-ldap.conf) + +<div class="literalinclude" language="none"> + +<span id="include">include</span>/ldap-auth.config + +</div> + +Now generate all required certificates on the ovpn-server: + +First the CA + +``` none +vyos@ovpn-server# run generate pki ca install OVPN-CA +``` + +after this create a signed server and a client certificate + +``` none +vyos@ovpn-server# run generate pki certificate sign OVPN-CA install SRV +vyos@ovpn-server# run generate pki certificate sign OVPN-CA install CLIENT +``` + +and last the DH Key + +``` none +vyos@ovpn-server# run generate pki dh install DH +``` + +after all these steps the config look like this: + +``` none +set pki ca OVPN-CA certificate 'MIIFnTCCA4WgAwIBAgIUIPFIXvCxYdavCnSPFNjr6lUtlsswDQYJKoZIhvcNAQELBQAwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA1MTExMjM4MjJaFw0zMzA1MDgxMjM4MjJaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxEDAOBgNVBAMMB3Z5b3MuaW8wggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAwggIKAoICAQDg45vAzS6xNqU+Pa7wk1Imt1/az1C22Sbp3wPJLfgOmy0K3TA5qVsx/c/8gatsatMkCsekGnK5BPzCDd5eCCLo//B25HFO6fBYRNvHvVyCUx7QEXw4FHFNG88zCIizx114AGtVwZfGGG9xCc53xjLPUpH6iqTXme41cCFFQlqXwZ7fuySieSdoV8SAsJTTOsGCEUEcDEnNPn6tX3KWTzNuyFPECy8WCmNgWNyG2nmH+U7WRTX0ehZ5dZyU5au7TxpRN4a+JtE0gNqcWJ+nh1A543q2pcRoQpPAzHFclgj8wG/EyauQMY/LC4tLc6moPaNlTwA9HJv8s6xUqpzNptDoUHKOqKuw2JRFnno5SCQ788KkKNgVWBy2o3BGoewfHFhAdR61CXeLpmuneuhi96GcM031gW8ptXbd4DkCF7H6KRtqeIvwiyG79ttC8kZf01Sn1fM5fTjGxaE38dAk/RchtHRC6rtFavHJjB2cUcCkhhQofUE6IR2dYJZ1cw0Wy5CI3bXHf43BpvDGmuxIlNGirTq8wf5RCWzDJJgmkQpYhUYe8x4faF4gTo00uH4ZvAYjQu3JNZGkb50p4kM9Mu5rQAiZJUeMAz/QD+EIV9xXgOk14+BbnHKWbZ7Ou5emewFuE/bjl79oNJklpXdc4soRkCPCTEGK3zDBdmUtCYk1DwIDAQABo2EwXzAPBgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBhjAdBgNVHSUEFjAUBggrBgEFBQcDAgYIKwYBBQUHAwEwHQYDVR0OBBYEFP5NDac/yC+mQmaTpZDUv9GZMGMBMA0GCSqGSIb3DQEBCwUAA4ICAQDEqpF2ibwYFxsF1XDIPS5/Gs0sZTZBuByNm5d2+jTyO7d5alZUdbvobbwhxZOhWasmFNyPLr4TYmZm5zF+efFsiOxjyRuEoVU+Fe8rZmpRIF/+6+nYX5r9vMI4QxGjeeyP20OHJ85Kvz182CTsITrM15Vw/kVVjAVzFI5Gm/QolalAoFQza9rAL4kDqaUszjHjPbysvDpGF+NLPjiYDHXcty/BC48bnuzAeEM60SGZ7EXvf8l0X8YsO7z39w6780A/3rbZvFhCYMKp/+p5xBRDjnX91dM6DJw73RwYQ1KHbHk9wWUwnL1giL71jzp/y4Oj6SSK2PQv+OnO80J6Zg06WIQx9xYcxr108Xh9FotUrlG7GYPI3Udf95t6SjuydDhULAVD0lMBxlDe9DHW1k1q1pOXaHZg926tY66xx/lda6dcuwJjA2Dx5JI6L0u9ureQmQAtxvnoTCtf+hR1iX/IkskZCKs34SjNiCnBuw/DNfdOpfaABm7y+tWiXBwnu5l/K8poXcQYQByyZj6YMmpgsbVPr5KNsLWOgRA81M6IPof8qxvnFrkazhiQWh1YHSjnaHtA3z5/BdgwHVICuFyrIOlbkKyJOjKcKBsDdMwIV0tsnpnyli2xEPZKu1tAQFAavXrK/RGYYhOZ3e0aRSV8hlP8i/mf7p0I45cJiBCqPg==' +set pki ca OVPN-CA private key '<REDACTED>' +set pki certificate SRV certificate 'MIIFtTCCA52gAwIBAgIUeZnSAMPohIvKL/1Fy/pW2cV73HkwDQYJKoZIhvcNAQELBQAwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA1MTExMjM4MzFaFw0zMzA1MDgxMjM4MzFaMFsxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxFDASBgNVBAMMC292cG4tc2VydmVyMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEApDWzTcB5LFM/tacaRHvpchBKLigJ5FlqNNfJ2vnP87KfCmTA5tkWF7MtuY990tHZtl1vQ3Pim4d6XBOngiQmaw7tZeWAIrv1L2/VBjORUrLrQhkkg9nSpcYFxoyUQzukTY75PcwhYLkS6ZO/vPPSBuh97f3XR645Aauf7ZIk2NsUidP2uGZz/Sr5VC7ovH2l3zz1kIHPCinfvpPEVb5oTt7qEffk4vnKjy9RY+H1hZowvcAp1zfLaOt/dXaK6vfNutbmwDHbYAlIals0EcjtTr+63ymxmupn7RBjgWtK7MgocGZnt6HKJ4J6teP3WgiSd+I9pdFG4wHZOSVL3axf3rBx7q09DMn/Snvfbly+SlhXw9Ebk368J6j6rhNUkxo/M9fbfgxS0JnNjHInRNAvRQW5CgQfT9KyUdxR63BeSnngk2XYX+bDinb0ig+VDpZcr6PgOBR8aNFsCPbXRwDy0bmuFnFYMzs/7ZmFQhzE6rQykHvVvAsyv7FYrlW0E02H4+Xe6bEVpE1fLcH8OCGY2cfuTfq1Ax6R4r+tdHYW1kzFLjwdh3uqTLF11zcbkAwd78E/ItrfEadvgxrYR9gfhX79AkK0VHmZ/hzrLFeGznnVcqoTKgq21dfMfQG2P13QvqS7tCE5swM9N09ASVrifyVDuoL6jaW96wgeqR6eHMECAwEAAaN1MHMwDAYDVR0TAQH/BAIwADAOBgNVHQ8BAf8EBAMCB4AwEwYDVR0lBAwwCgYIKwYBBQUHAwEwHQYDVR0OBBYEFE1U3Zamfuv6ocYiF9q7H//U8h+AMB8GA1UdIwQYMBaAFP5NDac/yC+mQmaTpZDUv9GZMGMBMA0GCSqGSIb3DQEBCwUAA4ICAQBZwHvGj/jziNFwXS2W1Q11I12YANmVhISP39AA7DNhXR+E1hXFs+U52ehurZoLTi5YTjd8PD0KcE58mw8CLsFQB/+pni9EwJuAhpMb6XsmYEp0PeOH7C/q5eOc4TB/NBsvEa5IdTmUoewmjubKeJ8OHdRBMI77Me53lSC6iskc9DGyixSLqQogQW4aiTposFJOW/YugBy7kiuygmFNJv4luDbyRBb9131zH0qSSishLT4Bp5lXQNYWI4AU0JeyQcYaSHWCr0h6H9GN3QOf/emc3/2Tee40FcEMsszJBRnQ3IISzU5xVLlfU02SJMpjvFT2MGfHAs7obrNbwiFeoLZ6fQeGLe53aOQ5M9XeW5bdIeR2ZrLoO1hW33x5jYI8nLnU0FnqpMMY14r7LZE/mjwfdrTsGChFzsLasB0Tj++mGMOXw3DSusppub17AE2bO2uO6J9XMlbkOC8EmDCF1Hetija4D3aunhtu6jRBOcR8DHVBqNae2YgUk1ALqGrNUGFH4bEioTjDDx2GieOtp9rUwJMlkAyUEe0k/wzcBLjZaO8KBCtrmTdr1wMXizPT+XcjAlzRNXvHiZFq0NG5Rnim+LH9tp90EHzO7EeVXV+LegnIKQqboIrY3KOw5Qx8ska+t1WrWHpyzpwsA0WjA6sDTyWthgNYSxb1ikNGO8STCA==' +set pki certificate SRV private key '<REDACTED>' +set pki certificate CLIENT certificate 'MIIFsDCCA5igAwIBAgIUSzQgwzGsfJFecGxCwLXVsGCLMkAwDQYJKoZIhvcNAQELBQAwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA1MTExMjM4MzlaFw0zMzA1MDgxMjM4MzlaMFYxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxDzANBgNVBAMMBmNsaWVudDCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBANHNJOSwcDbRqziL1gXYnHIq7P7vEUFvS8d/XLYJ1xIpcYTRXTut2CTGRar7fZZicu7x0yoK4TzrHvGVf1o4NC4NSGV5RX6kwRdrfWBmvpIkjSLGtCREFyhb+PHDpnsIS7cfN9udC0vocqVlx/xM/sfcP6Vja/uFp+9TQcneJIxYw34zkF+TtOVbE3pP5VxU7ZAj8F5/q1ONhTMdzG4Ol4/0nBqZfdYA3LVDeSSNIJNF5jlaKXXFHz1EJRemTYDx+f5bfCVcK2Qs8fU9jCFBlATjMu9O5rgk6nMLRwEnJZuZ1gj2tWQvz4e9yo5yUqf1PUhOrn3c81MRliUNHKr+CkxgQJal6P3Ar3q4iftJih3K+/j4o194mQ/Dt/Et+/Qn/DUFk2FB0rTMcQwJLTEAzxtTdmBJeJpipIPDR0u7UMZLNh/raQ8s3FsbY4uYORt2f5YQlCVHbth4dRa9xa+oRbm7eomNACIbWfkLh5Bzud1+qIfdBMZKaZbnf0HEeuH0J5LBJeova8EPxWbYMJPrRHzu5gowkIKl+uIxcy8IiNTA9YEoJVonCjmlr8NEtYShrIVbicdMNSI3pOQR60MFhkHwBjSU2l/z+4wwLxtzq/c2xKw9yrOZ46ZVLwGDFq8rPwp7/P9r6mDKsbn6jIvGOeH71dMZvoc4lCaClw+hKIzLAgMBAAGjdTBzMAwGA1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMCMB0GA1UdDgQWBBS6j30FmL6kZW7rDH8QjRMoWoA/njAfBgNVHSMEGDAWgBT+TQ2nP8gvpkJmk6WQ1L/RmTBjATANBgkqhkiG9w0BAQsFAAOCAgEANW2Y4bgaB9oexEjj6rkGvePtQmXRkF/adVQREY9iZDGTe72ePybVzrfMkZHjse3o7JvXWRIVVztWSzEpv5noIOX7lAioGG3wsFTHotTFR0zrYJHXHBcV2Neq4Kx2Ta/TZwD8QnZHAAxEQ1pYb4fxwN/A60VElAZoz9zYsbrJyVrfuHDL9queQxPFzqis+7W1BiVIcv4rn0DMQ560jTGh4t4rImOSu5gUsUrQaih85XDdOBPxViSNwfVdZJIgbvamudpfEaKsIun/uCjcxpNnzIp0rhyYmDeqVat4GnTV7Sy48e/Uvcq71ZWbBYJF4+yW4pylIU2Sh/Uy2sAz4C2M71FlFB7qsmcnPRsFFHf+r1NyD1lkVI9k2371fTG/Kub9V0rOz4pvKz4Em5b4MUPdDbZOqJ8hQ+atGE3ovFJIovA3NFb0OtnyC4l+kG7dfjqFudOnmDa+Qsya+2YOxBZBIRfuhlXhb6Y6Smsk9R6x0jBmcQTPS5ZmvKaTxQCFc53xMdQNAswjiI2L9rw4BcqQfVmf/vpoN+VusD/XEv2V0Ixm10YybA7BI/tixh9vwj3fdQXVLy3jSYjVBd5WOFPizbQZeD10ElvlLqZZyWrP/Wre7Nmi/gEOnhBXXmo034fFF/vXf0JRpQsd2oDs24+4XwZYb8mbM31j7Nx8YvhR+64=' +set pki certificate CLIENT private key '<REDACTED>' +set pki dh DH parameters 'MIIBCAKCAQEAzPOQWrWaIX2qt4sbV6bRbUnFx4jmeE+WXC8GIvulnC4pIr1nt2Gc/7uNfEPjDZ4X6csD3X6zAWxtSuWeNuml9Yuy+tS8gI7d0FlbQRAFO/9GIlRuVdMcbCtEhg8ja7Y0g3fQjOSQJ9mqFo7sRoXyYQALD+MDEJOxhnV7neCrgDi1pqnN4xZLoR9DLARp0ad30VIvnv0ay55wxFWAKh2iwNRwyeXIEOtUDBkfcLGSNNfK0kQsos/J8Q+7YXmk4cN9tiVX4xR92edVO4z/vhMkjsGKLSDm/E6EMusX+N0UhQ3dv7qDgeSS8vDsqBm8XJonumNZLvFbYt2ARGRZYL6DUwIBAg==' +``` + +Once all the required certificates and keys are installed, the remaining +OpenVPN Server configuration can be carried out. + +<div class="literalinclude" language="none"> + +<span id="include">include</span>/ovpn-server.conf + +</div> + +## Client configuration + +One advantage of having the client certificate stored is the ability to create the client configuration. + +``` none +vyos@ovpn-server:~$ generate openvpn client-config interface vtun10 ca OVPN-CA certificate CLIENT +``` + +save the output to a file and import it in nearly all openvpn clients. + +``` none +client +nobind +remote 198.51.100.254 1194 +remote-cert-tls server +proto udp +dev tun +dev-type tun +persist-key +persist-tun +verb 3 + +# Encryption options + +keysize 256 +comp-lzo no + +<ca> +-----BEGIN CERTIFICATE----- +MIIFnTCCA4WgAwIBAgIUIPFIXvCxYdavCnSPFNjr6lUtlsswDQYJKoZIhvcNAQEL +BQAwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcM +CVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0y +MzA1MTExMjM4MjJaFw0zMzA1MDgxMjM4MjJaMFcxCzAJBgNVBAYTAkdCMRMwEQYD +VQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5 +T1MxEDAOBgNVBAMMB3Z5b3MuaW8wggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAwggIK +AoICAQDg45vAzS6xNqU+Pa7wk1Imt1/az1C22Sbp3wPJLfgOmy0K3TA5qVsx/c/8 +gatsatMkCsekGnK5BPzCDd5eCCLo//B25HFO6fBYRNvHvVyCUx7QEXw4FHFNG88z +CIizx114AGtVwZfGGG9xCc53xjLPUpH6iqTXme41cCFFQlqXwZ7fuySieSdoV8SA +sJTTOsGCEUEcDEnNPn6tX3KWTzNuyFPECy8WCmNgWNyG2nmH+U7WRTX0ehZ5dZyU +5au7TxpRN4a+JtE0gNqcWJ+nh1A543q2pcRoQpPAzHFclgj8wG/EyauQMY/LC4tL +c6moPaNlTwA9HJv8s6xUqpzNptDoUHKOqKuw2JRFnno5SCQ788KkKNgVWBy2o3BG +oewfHFhAdR61CXeLpmuneuhi96GcM031gW8ptXbd4DkCF7H6KRtqeIvwiyG79ttC +8kZf01Sn1fM5fTjGxaE38dAk/RchtHRC6rtFavHJjB2cUcCkhhQofUE6IR2dYJZ1 +cw0Wy5CI3bXHf43BpvDGmuxIlNGirTq8wf5RCWzDJJgmkQpYhUYe8x4faF4gTo00 +uH4ZvAYjQu3JNZGkb50p4kM9Mu5rQAiZJUeMAz/QD+EIV9xXgOk14+BbnHKWbZ7O +u5emewFuE/bjl79oNJklpXdc4soRkCPCTEGK3zDBdmUtCYk1DwIDAQABo2EwXzAP +BgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBhjAdBgNVHSUEFjAUBggrBgEF +BQcDAgYIKwYBBQUHAwEwHQYDVR0OBBYEFP5NDac/yC+mQmaTpZDUv9GZMGMBMA0G +CSqGSIb3DQEBCwUAA4ICAQDEqpF2ibwYFxsF1XDIPS5/Gs0sZTZBuByNm5d2+jTy +O7d5alZUdbvobbwhxZOhWasmFNyPLr4TYmZm5zF+efFsiOxjyRuEoVU+Fe8rZmpR +IF/+6+nYX5r9vMI4QxGjeeyP20OHJ85Kvz182CTsITrM15Vw/kVVjAVzFI5Gm/Qo +lalAoFQza9rAL4kDqaUszjHjPbysvDpGF+NLPjiYDHXcty/BC48bnuzAeEM60SGZ +7EXvf8l0X8YsO7z39w6780A/3rbZvFhCYMKp/+p5xBRDjnX91dM6DJw73RwYQ1KH +bHk9wWUwnL1giL71jzp/y4Oj6SSK2PQv+OnO80J6Zg06WIQx9xYcxr108Xh9FotU +rlG7GYPI3Udf95t6SjuydDhULAVD0lMBxlDe9DHW1k1q1pOXaHZg926tY66xx/ld +a6dcuwJjA2Dx5JI6L0u9ureQmQAtxvnoTCtf+hR1iX/IkskZCKs34SjNiCnBuw/D +NfdOpfaABm7y+tWiXBwnu5l/K8poXcQYQByyZj6YMmpgsbVPr5KNsLWOgRA81M6I +Pof8qxvnFrkazhiQWh1YHSjnaHtA3z5/BdgwHVICuFyrIOlbkKyJOjKcKBsDdMwI +V0tsnpnyli2xEPZKu1tAQFAavXrK/RGYYhOZ3e0aRSV8hlP8i/mf7p0I45cJiBCq +Pg== +-----END CERTIFICATE----- + +</ca> + +<cert> +-----BEGIN CERTIFICATE----- +MIIFsDCCA5igAwIBAgIUSzQgwzGsfJFecGxCwLXVsGCLMkAwDQYJKoZIhvcNAQEL +BQAwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcM +CVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0y +MzA1MTExMjM4MzlaFw0zMzA1MDgxMjM4MzlaMFYxCzAJBgNVBAYTAkdCMRMwEQYD +VQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5 +T1MxDzANBgNVBAMMBmNsaWVudDCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoC +ggIBANHNJOSwcDbRqziL1gXYnHIq7P7vEUFvS8d/XLYJ1xIpcYTRXTut2CTGRar7 +fZZicu7x0yoK4TzrHvGVf1o4NC4NSGV5RX6kwRdrfWBmvpIkjSLGtCREFyhb+PHD +pnsIS7cfN9udC0vocqVlx/xM/sfcP6Vja/uFp+9TQcneJIxYw34zkF+TtOVbE3pP +5VxU7ZAj8F5/q1ONhTMdzG4Ol4/0nBqZfdYA3LVDeSSNIJNF5jlaKXXFHz1EJRem +TYDx+f5bfCVcK2Qs8fU9jCFBlATjMu9O5rgk6nMLRwEnJZuZ1gj2tWQvz4e9yo5y +Uqf1PUhOrn3c81MRliUNHKr+CkxgQJal6P3Ar3q4iftJih3K+/j4o194mQ/Dt/Et ++/Qn/DUFk2FB0rTMcQwJLTEAzxtTdmBJeJpipIPDR0u7UMZLNh/raQ8s3FsbY4uY +ORt2f5YQlCVHbth4dRa9xa+oRbm7eomNACIbWfkLh5Bzud1+qIfdBMZKaZbnf0HE +euH0J5LBJeova8EPxWbYMJPrRHzu5gowkIKl+uIxcy8IiNTA9YEoJVonCjmlr8NE +tYShrIVbicdMNSI3pOQR60MFhkHwBjSU2l/z+4wwLxtzq/c2xKw9yrOZ46ZVLwGD +Fq8rPwp7/P9r6mDKsbn6jIvGOeH71dMZvoc4lCaClw+hKIzLAgMBAAGjdTBzMAwG +A1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMC +MB0GA1UdDgQWBBS6j30FmL6kZW7rDH8QjRMoWoA/njAfBgNVHSMEGDAWgBT+TQ2n +P8gvpkJmk6WQ1L/RmTBjATANBgkqhkiG9w0BAQsFAAOCAgEANW2Y4bgaB9oexEjj +6rkGvePtQmXRkF/adVQREY9iZDGTe72ePybVzrfMkZHjse3o7JvXWRIVVztWSzEp +v5noIOX7lAioGG3wsFTHotTFR0zrYJHXHBcV2Neq4Kx2Ta/TZwD8QnZHAAxEQ1pY +b4fxwN/A60VElAZoz9zYsbrJyVrfuHDL9queQxPFzqis+7W1BiVIcv4rn0DMQ560 +jTGh4t4rImOSu5gUsUrQaih85XDdOBPxViSNwfVdZJIgbvamudpfEaKsIun/uCjc +xpNnzIp0rhyYmDeqVat4GnTV7Sy48e/Uvcq71ZWbBYJF4+yW4pylIU2Sh/Uy2sAz +4C2M71FlFB7qsmcnPRsFFHf+r1NyD1lkVI9k2371fTG/Kub9V0rOz4pvKz4Em5b4 +MUPdDbZOqJ8hQ+atGE3ovFJIovA3NFb0OtnyC4l+kG7dfjqFudOnmDa+Qsya+2YO +xBZBIRfuhlXhb6Y6Smsk9R6x0jBmcQTPS5ZmvKaTxQCFc53xMdQNAswjiI2L9rw4 +BcqQfVmf/vpoN+VusD/XEv2V0Ixm10YybA7BI/tixh9vwj3fdQXVLy3jSYjVBd5W +OFPizbQZeD10ElvlLqZZyWrP/Wre7Nmi/gEOnhBXXmo034fFF/vXf0JRpQsd2oDs +24+4XwZYb8mbM31j7Nx8YvhR+64= +-----END CERTIFICATE----- + +</cert> + +<key> +-----BEGIN PRIVATE KEY----- +...REDACTED... +-----END PRIVATE KEY----- + +</key> +``` + +### Configure VyOS as client + +``` none +set interfaces openvpn vtun10 authentication username 'user01' +set interfaces openvpn vtun10 authentication password '$ecret' +set interfaces openvpn vtun10 encryption cipher 'aes256' +set interfaces openvpn vtun10 hash 'sha512' +set interfaces openvpn vtun10 mode 'client' +set interfaces openvpn vtun10 persistent-tunnel +set interfaces openvpn vtun10 protocol 'udp' +set interfaces openvpn vtun10 remote-host '198.51.100.254' +set interfaces openvpn vtun10 remote-port '1194' +set interfaces openvpn vtun10 tls ca-certificate 'OVPN-CA' +set interfaces openvpn vtun10 tls certificate 'CLIENT' +``` + +## Monitoring + +If the client is connected successfully you can check the status + +``` none +vyos@ovpn-server:~$ show openvpn server +OpenVPN status on vtun10 + +Client CN Remote Host Tunnel IP Local Host TX bytes RX bytes Connected Since +----------- ------------------ ----------- ------------------- ---------- ---------- ------------------- +client 198.51.100.1:55150 10.23.1.6 198.51.100.254:1194 4.7 KB 4.7 KB 2023-05-11 12:47:11 +``` diff --git a/docs/configexamples/autotest/Wireguard/_include/topology.webp b/docs/configexamples/autotest/Wireguard/_include/topology.webp Binary files differnew file mode 100644 index 00000000..3cc5e992 --- /dev/null +++ b/docs/configexamples/autotest/Wireguard/_include/topology.webp diff --git a/docs/configexamples/autotest/Wireguard/md-Wireguard.md b/docs/configexamples/autotest/Wireguard/md-Wireguard.md new file mode 100644 index 00000000..ea0ca8e3 --- /dev/null +++ b/docs/configexamples/autotest/Wireguard/md-Wireguard.md @@ -0,0 +1,108 @@ +# Wireguard + +Testdate: 2023-08-31\ +Version: 1.4-rolling-202308240020 + +This simple structure show how to connect two offices. One remote branch and the +central office. + +## Topology + +The topology have a central and a branch VyOS router and one client, to +test, in each site. + + + +## Configuration + +Set the local subnet on eth2 and the public ip address eth1 on each site. + +Central + +<div class="literalinclude" language="none" lines="1-2"> + +<span id="include">include</span>/central.conf + +</div> + +Branch + +<div class="literalinclude" language="none" lines="1-2"> + +<span id="include">include</span>/branch.conf + +</div> + +Next thing to do, is to create a wireguard keypair on each side. +After this, the public key can be displayed, to save for later. + +``` none +vyos@central:~$ generate pki wireguard +Private key: cMNGHtb5dW92ORG3HS8JJlvQF8pmVGt2Ydny8hTBLnY= +Public key: WyfLCTXi31gL+YbYOwoAHCl2RgS+y56cYHEK6pQsTQ8= +``` + +After you have each public key. The wireguard interfaces can be setup. + +Central + +<div class="literalinclude" language="none" lines="4-12"> + +<span id="include">include</span>/central.conf + +</div> + +Branch + +<div class="literalinclude" language="none" lines="4-12"> + +<span id="include">include</span>/branch.conf + +</div> + +To reach the network, a route must be set on each VyOS host. +In this structure, a static interface route will fit the requirements. + +Central + +<div class="literalinclude" language="none" lines="14"> + +<span id="include">include</span>/central.conf + +</div> + +Branch + +<div class="literalinclude" language="none" lines="14"> + +<span id="include">include</span>/branch.conf + +</div> + +## Testing and debugging + +After all is done and commit, let's take a look if the Wireguard interface is +up and running. + +``` none +vyos@central:~$ show interfaces wireguard +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +wg01 192.168.0.1/24 u/u VPN-to-Branch +``` + +And ping the Branch PC from your central router to check the response. + +``` none +vyos@central:~$ ping 10.0.2.100 count 4 +PING 10.0.2.100 (10.0.2.100) 56(84) bytes of data. +64 bytes from 10.0.2.100: icmp_seq=1 ttl=63 time=0.641 ms +64 bytes from 10.0.2.100: icmp_seq=2 ttl=63 time=0.836 ms +64 bytes from 10.0.2.100: icmp_seq=3 ttl=63 time=0.792 ms +64 bytes from 10.0.2.100: icmp_seq=4 ttl=63 time=1.09 ms + +--- 10.0.2.100 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 3013ms +rtt min/avg/max/mdev = 0.641/0.838/1.086/0.160 ms +``` diff --git a/docs/configexamples/autotest/tunnelbroker/_include/topology.webp b/docs/configexamples/autotest/tunnelbroker/_include/topology.webp Binary files differnew file mode 100644 index 00000000..c3a812ab --- /dev/null +++ b/docs/configexamples/autotest/tunnelbroker/_include/topology.webp diff --git a/docs/configexamples/autotest/tunnelbroker/md-tunnelbroker.md b/docs/configexamples/autotest/tunnelbroker/md-tunnelbroker.md new file mode 100644 index 00000000..8c8eaf78 --- /dev/null +++ b/docs/configexamples/autotest/tunnelbroker/md-tunnelbroker.md @@ -0,0 +1,195 @@ +# Tunnelbroker.net (IPv6) + +Testdate: 2023-08-31\ +Version: 1.4-rolling-202308240020 + +This guide walks through the setup of <https://www.tunnelbroker.net/> for an +IPv6 Tunnel. + +## Prerequisites + +- A public, routable IPv4 address. This does not necessarily need to be static, + but you will need to update the tunnel endpoint when/if your IP address + changes, which can be done with a script and a scheduled task. +- Account at <https://www.tunnelbroker.net/> +- Requested a "Regular Tunnel". You want to choose a location that is closest + to your physical location for the best response time. + +### Topology + +The example topology has 2 VyOS routers. One as The WAN Router and on as a +Client, to test a single LAN setup + + + +### Configuration + +First, we configure the `vyos-wan` interface to get a DHCP address. + +<div class="literalinclude" language="none"> + +<span id="include">include</span>/vyos-wan.conf + +</div> + +Now we are able to setup the tunnel interface. + +<div class="literalinclude" language="none" lines="1-5"> + +<span id="include">include</span>/vyos-wan_tun0.conf + +</div> + +Setup the ipv6 default route to the tunnel interface + +<div class="literalinclude" language="none" lines="7"> + +<span id="include">include</span>/vyos-wan_tun0.conf + +</div> + +Now you should be able to ping a public IPv6 Address + +``` none +vyos@vyos-wan:~$ ping 2001:470:20::2 count 4 +PING 2001:470:20::2(2001:470:20::2) 56 data bytes +64 bytes from 2001:470:20::2: icmp_seq=1 ttl=64 time=39.4 ms +64 bytes from 2001:470:20::2: icmp_seq=2 ttl=64 time=29.9 ms +64 bytes from 2001:470:20::2: icmp_seq=3 ttl=64 time=30.0 ms +64 bytes from 2001:470:20::2: icmp_seq=4 ttl=64 time=29.9 ms + +--- 2001:470:20::2 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 3005ms +rtt min/avg/max/mdev = 29.885/32.293/39.371/4.086 ms +``` + +Assuming the pings are successful, you need to add some DNS servers. +Some options: + +<div class="literalinclude" language="none" lines="13"> + +<span id="include">include</span>/vyos-wan_tun0.conf + +</div> + +You should now be able to ping something by IPv6 DNS name: + +``` none +vyos@vyos-wan:~$ ping tunnelbroker.net count 4 +PING tunnelbroker.net(tunnelbroker.net (2001:470:0:63::2)) 56 data bytes +64 bytes from tunnelbroker.net (2001:470:0:63::2): icmp_seq=1 ttl=46 time=200 ms +64 bytes from tunnelbroker.net (2001:470:0:63::2): icmp_seq=2 ttl=46 time=176 ms +64 bytes from tunnelbroker.net (2001:470:0:63::2): icmp_seq=3 ttl=46 time=244 ms +64 bytes from tunnelbroker.net (2001:470:0:63::2): icmp_seq=4 ttl=46 time=176 ms + +--- tunnelbroker.net ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 3002ms +rtt min/avg/max/mdev = 175.737/198.653/243.621/27.714 ms +``` + +### LAN Configuration + +At this point, your VyOS install should have full IPv6, but now your LAN devices +need access. + +With Tunnelbroker.net, you have two options: + +- Routed /64. This is the default assignment. In IPv6-land, it's good for a + single "LAN", and is somewhat equivalent to a /24. +- Routed /48. This is something you can request by clicking the "Assign /48" + link in the Tunnelbroker.net tunnel config. It allows you to have up to 65k + +Unlike IPv4, IPv6 is really not designed to be broken up smaller than /64. So +if you ever want to have multiple LANs, VLANs, DMZ, etc, you'll want to ignore +the assigned /64, and request the /48 and use that. + +## Single LAN Setup + +Single LAN setup where eth2 is your LAN interface. Use the Tunnelbroker +Routed /64 prefix: + +<div class="literalinclude" language="none" lines="9-11"> + +<span id="include">include</span>/vyos-wan_tun0.conf + +</div> + +Please note, 'autonomous-flag' and 'on-link-flag' are enabled by default, +'valid-lifetime' and 'preferred-lifetime' are set to default values of +30 days and 4 hours respectively. + +And the `client` to receive an IPv6 address with stateless autoconfig. + +<div class="literalinclude" language="none"> + +<span id="include">include</span>/client.conf + +</div> + +This accomplishes a few things: + +- Sets your LAN interface's IP address +- Enables router advertisements. This is an IPv6 alternative for DHCP (though + DHCPv6 can still be used). With RAs, Your devices will automatically find the + information they need for routing and DNS. + +Now the Client is able to ping a public IPv6 address + +``` none +vyos@client:~$ ping 2001:470:20::2 count 4 +PING 2001:470:20::2(2001:470:20::2) 56 data bytes +64 bytes from 2001:470:20::2: icmp_seq=1 ttl=63 time=30.5 ms +64 bytes from 2001:470:20::2: icmp_seq=2 ttl=63 time=29.6 ms +64 bytes from 2001:470:20::2: icmp_seq=3 ttl=63 time=29.9 ms +64 bytes from 2001:470:20::2: icmp_seq=4 ttl=63 time=29.8 ms + +--- 2001:470:20::2 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 3005ms +rtt min/avg/max/mdev = 29.578/29.959/30.490/0.333 ms +``` + +## Multiple LAN/DMZ Setup + +That's how you can expand the example above. +Use the <span class="title-ref">Routed /48</span> information. This allows you to assign a +different /64 to every interface, LAN, or even device. Or you could break your +network into smaller chunks like /56 or /60. + +The format of these addresses: + +- \`2001:470:xxxx::/48\`: The whole subnet. xxxx should come from Tunnelbroker. +- \`2001:470:xxxx:1::/64\`: A subnet suitable for a LAN +- \`2001:470:xxxx:2::/64\`: Another subnet +- \`2001:470:xxxx:ffff::/64\`: The last usable /64 subnet. + +In the above examples, 1,2,ffff are all chosen by you. You can use 1-ffff +(1-65535). + +So, when your LAN is eth1, your DMZ is eth2, your cameras are on eth3, etc: + +``` none +set interfaces ethernet eth1 address '2001:470:xxxx:1::1/64' +set service router-advert interface eth1 name-server '2001:470:20::2' +set service router-advert interface eth1 prefix 2001:470:xxxx:1::/64 + +set interfaces ethernet eth2 address '2001:470:xxxx:2::1/64' +set service router-advert interface eth2 name-server '2001:470:20::2' +set service router-advert interface eth2 prefix 2001:470:xxxx:2::/64 + +set interfaces ethernet eth3 address '2001:470:xxxx:3::1/64' +set service router-advert interface eth3 name-server '2001:470:20::2' +set service router-advert interface eth3 prefix 2001:470:xxxx:3::/64 +``` + +Please note, 'autonomous-flag' and 'on-link-flag' are enabled by default, +'valid-lifetime' and 'preferred-lifetime' are set to default values of +30 days and 4 hours respectively. + +## Firewall + +Finally, don't forget the `firewall`. The usage is identical, except for +instead of <span class="title-ref">set firewall name NAME</span>, you would use <span class="title-ref">set firewall ipv6-name +NAME</span>. + +Similarly, to attach the firewall, you would use <span class="title-ref">set interfaces ethernet eth0 +firewall in ipv6-name</span> or <span class="title-ref">et firewall zone LOCAL from WAN firewall ipv6-name</span>. diff --git a/docs/configexamples/md-azure-vpn-bgp.md b/docs/configexamples/md-azure-vpn-bgp.md new file mode 100644 index 00000000..d6ac6552 --- /dev/null +++ b/docs/configexamples/md-azure-vpn-bgp.md @@ -0,0 +1,162 @@ +lastproofread +2021-06-28 + +# Route-Based Site-to-Site VPN to Azure (BGP over IKEv2/IPsec) + +This guide shows an example of a route-based IKEv2 site-to-site VPN to +Azure using VTI and BGP for dynamic routing updates. + +For redundant / active-active configurations see +`examples-azure-vpn-dual-bgp` + +## Prerequisites + +- A pair of Azure VNet Gateways deployed in active-passive + configuration with BGP enabled. +- A local network gateway deployed in Azure representing + the Vyos device, matching the below Vyos settings except for + address space, which only requires the Vyos private IP, in + this example 10.10.0.5/32 +- A connection resource deployed in Azure linking the + Azure VNet gateway and the local network gateway representing + the Vyos device. + +## Example + +<table style="width:86%;"> +<colgroup> +<col style="width: 55%" /> +<col style="width: 30%" /> +</colgroup> +<tbody> +<tr> +<td>WAN Interface</td> +<td>eth0</td> +</tr> +<tr> +<td>On-premises address space</td> +<td>10.10.0.0/16</td> +</tr> +<tr> +<td>Azure address space</td> +<td><blockquote> +<p>10.0.0.0/16</p> +</blockquote></td> +</tr> +<tr> +<td>Vyos public IP</td> +<td>198.51.100.3</td> +</tr> +<tr> +<td>Vyos private IP</td> +<td>10.10.0.5</td> +</tr> +<tr> +<td>Azure VNet Gateway public IP</td> +<td><blockquote> +<p>203.0.113.2</p> +</blockquote></td> +</tr> +<tr> +<td>Azure VNet Gateway BGP IP</td> +<td><blockquote> +<p>10.0.0.4</p> +</blockquote></td> +</tr> +<tr> +<td>Pre-shared key</td> +<td>ch00s3-4-s3cur3-psk</td> +</tr> +<tr> +<td>Vyos ASN</td> +<td>64499</td> +</tr> +<tr> +<td>Azure ASN</td> +<td>65540</td> +</tr> +</tbody> +</table> + +## Vyos configuration + +- Configure the IKE and ESP settings to match a subset + of those supported by Azure: + +``` none +set vpn ipsec esp-group AZURE lifetime '3600' +set vpn ipsec esp-group AZURE mode 'tunnel' +set vpn ipsec esp-group AZURE pfs 'dh-group2' +set vpn ipsec esp-group AZURE proposal 1 encryption 'aes256' +set vpn ipsec esp-group AZURE proposal 1 hash 'sha1' + +set vpn ipsec ike-group AZURE dead-peer-detection action 'restart' +set vpn ipsec ike-group AZURE dead-peer-detection interval '15' +set vpn ipsec ike-group AZURE dead-peer-detection timeout '30' +set vpn ipsec ike-group AZURE ikev2-reauth +set vpn ipsec ike-group AZURE key-exchange 'ikev2' +set vpn ipsec ike-group AZURE lifetime '28800' +set vpn ipsec ike-group AZURE proposal 1 dh-group '2' +set vpn ipsec ike-group AZURE proposal 1 encryption 'aes256' +set vpn ipsec ike-group AZURE proposal 1 hash 'sha1' +``` + +- Enable IPsec on eth0 + +``` none +set vpn ipsec interface 'eth0' +``` + +- Configure a VTI with a dummy IP address + +``` none +set interfaces vti vti1 address '10.10.1.5/32' +set interfaces vti vti1 description 'Azure Tunnel' +``` + +- Clamp the VTI's MSS to 1350 to avoid PMTU blackholes. + +``` none +set interfaces vti vti1 ip adjust-mss 1350 +``` + +- Configure the VPN tunnel + +``` none +set vpn ipsec authentication psk azure id '198.51.100.3' +set vpn ipsec authentication psk azure id '203.0.113.2' +set vpn ipsec authentication psk azure secret 'ch00s3-4-s3cur3-psk' +set vpn ipsec site-to-site peer 203.0.113.2 authentication local-id '198.51.100.3' +set vpn ipsec site-to-site peer 203.0.113.2 authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer 203.0.113.2 authentication remote-id '203.0.113.2' +set vpn ipsec site-to-site peer 203.0.113.2 connection-type 'respond' +set vpn ipsec site-to-site peer 203.0.113.2 description 'AZURE PRIMARY TUNNEL' +set vpn ipsec site-to-site peer 203.0.113.2 ike-group 'AZURE' +set vpn ipsec site-to-site peer 203.0.113.2 ikev2-reauth 'inherit' +set vpn ipsec site-to-site peer 203.0.113.2 local-address '10.10.0.5' +set vpn ipsec site-to-site peer 203.0.113.2 remote-address '203.0.113.2' +set vpn ipsec site-to-site peer 203.0.113.2 vti bind 'vti1' +set vpn ipsec site-to-site peer 203.0.113.2 vti esp-group 'AZURE' +``` + +- **Important**: Add an interface route to reach Azure's BGP listener + +``` none +set protocols static route 10.0.0.4/32 interface vti1 +``` + +- Configure your BGP settings + +``` none +set protocols bgp system-as 64499 +set protocols bgp neighbor 10.0.0.4 remote-as '65540' +set protocols bgp neighbor 10.0.0.4 address-family ipv4-unicast soft-reconfiguration 'inbound' +set protocols bgp neighbor 10.0.0.4 timers holdtime '30' +set protocols bgp neighbor 10.0.0.4 timers keepalive '10' +``` + +- **Important**: Disable connected check + +``` none +set protocols bgp neighbor 10.0.0.4 disable-connected-check +``` diff --git a/docs/configexamples/md-azure-vpn-dual-bgp.md b/docs/configexamples/md-azure-vpn-dual-bgp.md new file mode 100644 index 00000000..e1b69fc3 --- /dev/null +++ b/docs/configexamples/md-azure-vpn-dual-bgp.md @@ -0,0 +1,192 @@ +lastproofread +2021-06-28 + +# Route-Based Redundant Site-to-Site VPN to Azure (BGP over IKEv2/IPsec) + +This guide shows an example of a redundant (active-active) route-based IKEv2 +site-to-site VPN to Azure using VTI +and BGP for dynamic routing updates. + +## Prerequisites + +- A pair of Azure VNet Gateways deployed in active-active + configuration with BGP enabled. +- A local network gateway deployed in Azure representing + the Vyos device, matching the below Vyos settings except for + address space, which only requires the Vyos private IP, in + this example 10.10.0.5/32 +- A connection resource deployed in Azure linking the + Azure VNet gateway and the local network gateway representing + the Vyos device. + +## Example + +<table style="width:86%;"> +<colgroup> +<col style="width: 55%" /> +<col style="width: 30%" /> +</colgroup> +<tbody> +<tr> +<td>WAN Interface</td> +<td>eth0</td> +</tr> +<tr> +<td>On-premises address space</td> +<td>10.10.0.0/16</td> +</tr> +<tr> +<td>Azure address space</td> +<td><blockquote> +<p>10.0.0.0/16</p> +</blockquote></td> +</tr> +<tr> +<td>Vyos public IP</td> +<td>198.51.100.3</td> +</tr> +<tr> +<td>Vyos private IP</td> +<td>10.10.0.5</td> +</tr> +<tr> +<td>Azure VNet Gateway 1 public IP</td> +<td><blockquote> +<p>203.0.113.2</p> +</blockquote></td> +</tr> +<tr> +<td>Azure VNet Gateway 2 public IP</td> +<td><blockquote> +<p>203.0.113.3</p> +</blockquote></td> +</tr> +<tr> +<td>Azure VNet Gateway BGP IP</td> +<td><blockquote> +<p>10.0.0.4,10.0.0.5</p> +</blockquote></td> +</tr> +<tr> +<td>Pre-shared key</td> +<td>ch00s3-4-s3cur3-psk</td> +</tr> +<tr> +<td>Vyos ASN</td> +<td>64499</td> +</tr> +<tr> +<td>Azure ASN</td> +<td>65540</td> +</tr> +</tbody> +</table> + +## Vyos configuration + +- Configure the IKE and ESP settings to match a subset + of those supported by Azure: + +``` none +set vpn ipsec esp-group AZURE lifetime '3600' +set vpn ipsec esp-group AZURE mode 'tunnel' +set vpn ipsec esp-group AZURE pfs 'dh-group2' +set vpn ipsec esp-group AZURE proposal 1 encryption 'aes256' +set vpn ipsec esp-group AZURE proposal 1 hash 'sha1' + +set vpn ipsec ike-group AZURE dead-peer-detection action 'restart' +set vpn ipsec ike-group AZURE dead-peer-detection interval '15' +set vpn ipsec ike-group AZURE dead-peer-detection timeout '30' +set vpn ipsec ike-group AZURE ikev2-reauth +set vpn ipsec ike-group AZURE key-exchange 'ikev2' +set vpn ipsec ike-group AZURE lifetime '28800' +set vpn ipsec ike-group AZURE proposal 1 dh-group '2' +set vpn ipsec ike-group AZURE proposal 1 encryption 'aes256' +set vpn ipsec ike-group AZURE proposal 1 hash 'sha1' +``` + +- Enable IPsec on eth0 + +``` none +set vpn ipsec interface 'eth0' +``` + +- Configure two VTIs with a dummy IP address each + +``` none +set interfaces vti vti1 address '10.10.1.5/32' +set interfaces vti vti1 description 'Azure Primary Tunnel' + +set interfaces vti vti2 address '10.10.1.6/32' +set interfaces vti vti2 description 'Azure Secondary Tunnel' +``` + +- Clamp the VTI's MSS to 1350 to avoid PMTU blackholes. + +``` none +set interfaces vti vti1 ip adjust-mss 1350 +set interfaces vti vti2 ip adjust-mss 1350 +``` + +- Configure the VPN tunnels + +``` none +set vpn ipsec authentication psk azure id '198.51.100.3' +set vpn ipsec authentication psk azure id '203.0.113.2' +set vpn ipsec authentication psk azure id '203.0.113.3' +set vpn ipsec authentication psk azure secret 'ch00s3-4-s3cur3-psk' + +set vpn ipsec site-to-site peer azure-primary authentication local-id '198.51.100.3' +set vpn ipsec site-to-site peer azure-primary authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer azure-primary authentication remote-id '203.0.113.2' +set vpn ipsec site-to-site peer azure-primary connection-type 'respond' +set vpn ipsec site-to-site peer azure-primary description 'AZURE PRIMARY TUNNEL' +set vpn ipsec site-to-site peer azure-primary ike-group 'AZURE' +set vpn ipsec site-to-site peer azure-primary ikev2-reauth 'inherit' +set vpn ipsec site-to-site peer azure-primary local-address '10.10.0.5' +set vpn ipsec site-to-site peer azure-primary remote-address '203.0.113.2' +set vpn ipsec site-to-site peer azure-primary vti bind 'vti1' +set vpn ipsec site-to-site peer azure-primary vti esp-group 'AZURE' + +set vpn ipsec site-to-site peer azure-secondary authentication local-id '198.51.100.3' +set vpn ipsec site-to-site peer azure-secondary authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer azure-secondary authentication remote-id '203.0.113.3' +set vpn ipsec site-to-site peer azure-secondary connection-type 'respond' +set vpn ipsec site-to-site peer azure-secondary description 'AZURE secondary TUNNEL' +set vpn ipsec site-to-site peer azure-secondary ike-group 'AZURE' +set vpn ipsec site-to-site peer azure-secondary ikev2-reauth 'inherit' +set vpn ipsec site-to-site peer azure-secondary local-address '10.10.0.5' +set vpn ipsec site-to-site peer azure-secondary remote-address '203.0.113.3' +set vpn ipsec site-to-site peer azure-secondary vti bind 'vti2' +set vpn ipsec site-to-site peer azure-secondary vti esp-group 'AZURE' +``` + +- **Important**: Add an interface route to reach both Azure's BGP listeners + +``` none +set protocols static route 10.0.0.4/32 interface vti1 +set protocols static route 10.0.0.5/32 interface vti2 +``` + +- Configure your BGP settings + +``` none +set protocols bgp system-as 64499 +set protocols bgp neighbor 10.0.0.4 remote-as '65540' +set protocols bgp neighbor 10.0.0.4 address-family ipv4-unicast soft-reconfiguration 'inbound' +set protocols bgp neighbor 10.0.0.4 timers holdtime '30' +set protocols bgp neighbor 10.0.0.4 timers keepalive '10' + +set protocols bgp neighbor 10.0.0.5 remote-as '65540' +set protocols bgp neighbor 10.0.0.5 address-family ipv4-unicast soft-reconfiguration 'inbound' +set protocols bgp neighbor 10.0.0.5 timers holdtime '30' +set protocols bgp neighbor 10.0.0.5 timers keepalive '10' +``` + +- **Important**: Disable connected check, otherwise the routes learned + from Azure will not be imported into the routing table. + +``` none +set protocols bgp neighbor 10.0.0.4 disable-connected-check +set protocols bgp neighbor 10.0.0.5 disable-connected-check +``` diff --git a/docs/configexamples/md-bgp-ipv6-unnumbered.md b/docs/configexamples/md-bgp-ipv6-unnumbered.md new file mode 100644 index 00000000..89a0da8b --- /dev/null +++ b/docs/configexamples/md-bgp-ipv6-unnumbered.md @@ -0,0 +1,170 @@ +lastproofread +2021-06-28 + +# BGP IPv6 unnumbered with extended nexthop + +General information can be found in the `routing-bgp` chapter. + +## Configuration + +- Router A: + +``` none +set protocols bgp system-as 64496 +set protocols bgp address-family ipv4-unicast redistribute connected +set protocols bgp address-family ipv6-unicast redistribute connected +set protocols bgp neighbor eth1 interface v6only +set protocols bgp neighbor eth1 interface v6only peer-group 'fabric' +set protocols bgp neighbor eth2 interface v6only +set protocols bgp neighbor eth2 interface v6only peer-group 'fabric' +set protocols bgp parameters bestpath as-path multipath-relax +set protocols bgp parameters bestpath compare-routerid +set protocols bgp parameters default no-ipv4-unicast +set protocols bgp parameters router-id '192.168.0.1' +set protocols bgp peer-group fabric address-family ipv4-unicast +set protocols bgp peer-group fabric address-family ipv6-unicast +set protocols bgp peer-group fabric capability extended-nexthop +set protocols bgp peer-group fabric remote-as 'external' +``` + +- Router B: + +``` none +set protocols bgp system-as 64499 +set protocols bgp address-family ipv4-unicast redistribute connected +set protocols bgp address-family ipv6-unicast redistribute connected +set protocols bgp neighbor eth1 interface v6only +set protocols bgp neighbor eth1 interface v6only peer-group 'fabric' +set protocols bgp neighbor eth2 interface v6only +set protocols bgp neighbor eth2 interface v6only peer-group 'fabric' +set protocols bgp parameters bestpath as-path multipath-relax +set protocols bgp parameters bestpath compare-routerid +set protocols bgp parameters default no-ipv4-unicast +set protocols bgp parameters router-id '192.168.0.2' +set protocols bgp peer-group fabric address-family ipv4-unicast +set protocols bgp peer-group fabric address-family ipv6-unicast +set protocols bgp peer-group fabric capability extended-nexthop +set protocols bgp peer-group fabric remote-as 'external' +``` + +## Results + +- Router A: + +``` none +vyos@vyos:~$ show interfaces +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +eth0 198.51.100.34/24 u/u +eth1 - u/u +eth2 - u/u +lo 127.0.0.1/8 u/u + 192.168.0.1/32 + ::1/128 +``` + +``` none +vyos@vyos:~$ show ip route +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route + +S>* 0.0.0.0/0 [210/0] via 198.51.100.34, eth0, 03:21:53 +C>* 198.51.100.0/24 is directly connected, eth0, 03:21:53 +C>* 192.168.0.1/32 is directly connected, lo, 03:21:56 +B>* 192.168.0.2/32 [20/0] via fe80::a00:27ff:fe3b:7ed2, eth2, 00:05:07 + * via fe80::a00:27ff:fe7b:4000, eth1, 00:05:07 +``` + +``` none +vyos@vyos:~$ ping 192.168.0.2 +PING 192.168.0.2 (192.168.0.2) 56(84) bytes of data. +64 bytes from 192.168.0.2: icmp_seq=1 ttl=64 time=0.575 ms +64 bytes from 192.168.0.2: icmp_seq=2 ttl=64 time=0.628 ms +64 bytes from 192.168.0.2: icmp_seq=3 ttl=64 time=0.581 ms +64 bytes from 192.168.0.2: icmp_seq=4 ttl=64 time=0.682 ms +64 bytes from 192.168.0.2: icmp_seq=5 ttl=64 time=0.597 ms + +--- 192.168.0.2 ping statistics --- +5 packets transmitted, 5 received, 0% packet loss, time 4086ms +rtt min/avg/max/mdev = 0.575/0.612/0.682/0.047 ms +``` + +``` none +vyos@vyos:~$ show ip bgp summary + +IPv4 Unicast Summary: +BGP router identifier 192.168.0.1, local AS number 64496 vrf-id 0 +BGP table version 4 +RIB entries 5, using 800 bytes of memory +Peers 2, using 41 KiB of memory +Peer groups 1, using 64 bytes of memory + +Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd +eth1 4 64499 13 13 0 0 0 00:05:33 2 +eth2 4 64499 13 14 0 0 0 00:05:29 2 + +Total number of neighbors 2 +``` + +- Router B: + +``` none +vyos@vyos:~$ show interfaces +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +eth0 198.51.100.33/24 u/u +eth1 - u/u +eth2 - u/u +lo 127.0.0.1/8 u/u + 192.168.0.2/32 + ::1/128 +``` + +``` none +vyos@vyos:~$ show ip route +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route + +S>* 0.0.0.0/0 [210/0] via 198.51.100.33, eth0, 00:44:08 +C>* 198.51.100.0/24 is directly connected, eth0, 00:44:09 +B>* 192.168.0.1/32 [20/0] via fe80::a00:27ff:fe2d:205d, eth1, 00:06:18 + * via fe80::a00:27ff:fe93:e142, eth2, 00:06:18 +C>* 192.168.0.2/32 is directly connected, lo, 00:44:11 +``` + +``` none +vyos@vyos:~$ ping 192.168.0.1 +PING 192.168.0.1 (192.168.0.1) 56(84) bytes of data. +64 bytes from 192.168.0.1: icmp_seq=1 ttl=64 time=0.427 ms +64 bytes from 192.168.0.1: icmp_seq=2 ttl=64 time=0.471 ms +64 bytes from 192.168.0.1: icmp_seq=3 ttl=64 time=0.782 ms +64 bytes from 192.168.0.1: icmp_seq=4 ttl=64 time=0.715 ms + +--- 192.168.0.1 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 3051ms +rtt min/avg/max/mdev = 0.427/0.598/0.782/0.155 ms +``` + +``` none +vyos@vyos:~$ show ip bgp summary +IPv4 Unicast Summary: +BGP router identifier 192.168.0.2, local AS number 64499 vrf-id 0 +BGP table version 4 +RIB entries 5, using 800 bytes of memory +Peers 2, using 41 KiB of memory +Peer groups 1, using 64 bytes of memory + +Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd +eth1 4 64496 14 14 0 0 0 00:06:40 2 +eth2 4 64496 14 14 0 0 0 00:06:37 2 + +Total number of neighbors 2 +``` diff --git a/docs/configexamples/md-firewall.md b/docs/configexamples/md-firewall.md new file mode 100644 index 00000000..2849a66c --- /dev/null +++ b/docs/configexamples/md-firewall.md @@ -0,0 +1,13 @@ +lastproofread +2024-06-14 + +# Firewall Examples + +This section contains examples of firewall configurations for various deployments. + +<div class="toctree" maxdepth="2"> + +fwall-and-vrf +zone-policy + +</div> diff --git a/docs/configexamples/md-fwall-and-vrf.md b/docs/configexamples/md-fwall-and-vrf.md new file mode 100644 index 00000000..c7320902 --- /dev/null +++ b/docs/configexamples/md-fwall-and-vrf.md @@ -0,0 +1,118 @@ +# VRF and firewall example + +## Scenario and requirements + +This example shows how to configure a VyOS router with VRFs and firewall rules. + +Diagram used in this example: + +<img src="/_static/images/firewall-and-vrf-blueprints.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +As exposed in the diagram, there are four VRFs. These VRFs are `MGMT`, +`WAN`, `LAN` and `PROD`, and their requirements are: + +- VRF MGMT: + - Allow connections to LAN and PROD. + - Deny connections to internet(WAN). + - Allow connections to the router. + +- VRF LAN: + - Allow connections to PROD. + - Allow connections to internet(WAN). + +- VRF PROD: + - Only accepts connections. + +- VRF WAN: + - Allow connection to PROD. + +## Configuration + +First, we need to configure the interfaces and VRFs: + +``` none +set interfaces ethernet eth1 address '10.100.100.1/24' +set interfaces ethernet eth1 vrf 'MGMT' +set interfaces ethernet eth2 vif 150 address '10.150.150.1/24' +set interfaces ethernet eth2 vif 150 vrf 'LAN' +set interfaces ethernet eth2 vif 160 address '10.160.160.1/24' +set interfaces ethernet eth2 vif 160 vrf 'LAN' +set interfaces ethernet eth2 vif 3500 address '172.16.20.1/24' +set interfaces ethernet eth2 vif 3500 vrf 'PROD' +set interfaces loopback lo +set interfaces pppoe pppoe0 authentication password 'p4ssw0rd' +set interfaces pppoe pppoe0 authentication username 'vyos' +set interfaces pppoe pppoe0 source-interface 'eth0' +set interfaces pppoe pppoe0 vrf 'WAN' +set vrf bind-to-all +set vrf name LAN protocols static route 0.0.0.0/0 interface pppoe0 vrf 'WAN' +set vrf name LAN protocols static route 10.100.100.0/24 interface eth1 vrf 'MGMT' +set vrf name LAN protocols static route 172.16.20.0/24 interface eth2.3500 vrf 'PROD' +set vrf name LAN table '103' +set vrf name MGMT protocols static route 10.150.150.0/24 interface eth2.150 vrf 'LAN' +set vrf name MGMT protocols static route 10.160.160.0/24 interface eth2.160 vrf 'LAN' +set vrf name MGMT protocols static route 172.16.20.0/24 interface eth2.3500 vrf 'PROD' +set vrf name MGMT table '102' +set vrf name PROD protocols static route 0.0.0.0/0 interface pppoe0 vrf 'WAN' +set vrf name PROD protocols static route 10.100.100.0/24 interface eth1 vrf 'MGMT' +set vrf name PROD protocols static route 10.150.150.0/24 interface eth2.150 vrf 'LAN' +set vrf name PROD protocols static route 10.160.160.0/24 interface eth2.160 vrf 'LAN' +set vrf name PROD table '104' +set vrf name WAN protocols static route 10.150.150.0/24 interface eth2.150 vrf 'LAN' +set vrf name WAN protocols static route 10.160.160.0/24 interface eth2.160 vrf 'LAN' +set vrf name WAN protocols static route 172.16.20.0/24 interface eth2.3500 vrf 'PROD' +set vrf name WAN table '101' +``` + +And before firewall rules are shown, we need to pay attention how to configure +and match interfaces and VRFs. In case where an interface is assigned to a +non-default VRF, if we want to use inbound-interface or outbound-interface in +firewall rules, we need to: + +- For **inbound-interface**: use the interface name with the VRF name, like + `MGMT` or `LAN`. +- For **outbound-interface**: use the interface name, like `eth0`, `vtun0`, + `eth2*` or similar. + +Next, we need to configure the firewall rules. First we will define all rules +for transit traffic between VRFs. + +``` none +set firewall ipv4 forward filter default-action 'drop' +set firewall ipv4 forward filter default-log +set firewall ipv4 forward filter rule 10 action 'accept' +set firewall ipv4 forward filter rule 10 description 'MGMT - Allow to LAN and PROD' +set firewall ipv4 forward filter rule 10 inbound-interface name 'MGMT' +set firewall ipv4 forward filter rule 10 outbound-interface name 'eth2*' +set firewall ipv4 forward filter rule 99 action 'drop' +set firewall ipv4 forward filter rule 99 description 'MGMT - Drop all going to mgmt' +set firewall ipv4 forward filter rule 99 outbound-interface name 'eth1' +set firewall ipv4 forward filter rule 120 action 'accept' +set firewall ipv4 forward filter rule 120 description 'LAN - Allow to PROD' +set firewall ipv4 forward filter rule 120 inbound-interface name 'LAN' +set firewall ipv4 forward filter rule 120 outbound-interface name 'eth2.3500' +set firewall ipv4 forward filter rule 130 action 'accept' +set firewall ipv4 forward filter rule 130 description 'LAN - Allow internet' +set firewall ipv4 forward filter rule 130 inbound-interface name 'LAN' +set firewall ipv4 forward filter rule 130 outbound-interface name 'pppoe0' +``` + +Also, we are adding global state policies, in order to allow established and +related traffic, in order not to drop valid responses: + +``` none +set firewall global-options state-policy established action 'accept' +set firewall global-options state-policy invalid action 'drop' +set firewall global-options state-policy related action 'accept' +``` + +And finally, we need to allow input connections to the router itself only from +vrf MGMT: + +``` none +set firewall ipv4 input filter default-action 'drop' +set firewall ipv4 input filter default-log +set firewall ipv4 input filter rule 10 action 'accept' +set firewall ipv4 input filter rule 10 description 'MGMT - Allow input' +set firewall ipv4 input filter rule 10 inbound-interface name 'MGMT' +``` diff --git a/docs/configexamples/md-ha.md b/docs/configexamples/md-ha.md new file mode 100644 index 00000000..1a4589dd --- /dev/null +++ b/docs/configexamples/md-ha.md @@ -0,0 +1,572 @@ +lastproofread +2021-06-28 + +# High Availability Walkthrough + +This document walks you through a complete HA setup of two VyOS machines. This +design is based on a VM as the primary router and a physical machine as a +backup, using VRRP, BGP, OSPF, and conntrack sharing. + +This document aims to walk you through setting everything up, so +at a point where you can reboot any machine and not lose more than a few +seconds worth of connectivity. + +## Design + +This is based on a real-life production design. One of the complex issues +is ensuring you have redundant data INTO your network. We do this with a pair +of Cisco Nexus switches and using Virtual PortChannels that are spanned across +them. As a bonus, this also allows for complete switch failure without +an outage. How you achieve this yourself is left as an exercise to the reader. +But our setup is documented here. + +### Walkthrough suggestion + +The `commit` command is implied after every section. If you make an error, +`commit` will warn you and you can fix it before getting too far into things. +Please ensure you commit early and commit often. + +If you are following through this document, it is strongly suggested you +complete the entire document, ONLY doing the virtual router1 steps, and then +come back and walk through it AGAIN on the backup hardware router. + +This ensures you don't go too fast or miss a step. However, it will make your +life easier to configure the fixed IP address and default route now on the +hardware router. + +### Example Network + +In this document, we have been allocated 203.0.113.0/24 by our upstream +provider, which we are publishing on VLAN100. + +They want us to establish a BGP session to their routers on 192.0.2.11 and +192.0.2.12 from our routers 192.0.2.21 and 192.0.2.22. They are AS 65550 and +we are AS 65551. + +Our routers are going to have a floating IP address of 203.0.113.1, and use +.2 and .3 as their fixed IPs. + +We are going to use 10.200.201.0/24 for an 'internal' network on VLAN201. + +When traffic is originated from the 10.200.201.0/24 network, it will be +masqueraded to 203.0.113.1 + +For connection between sites, we are running a WireGuard link to two REMOTE +routers and using OSPF over those links to distribute routes. That remote +site is expected to send traffic from anything in 10.201.0.0/16 + +### VLANs + +These are the vlans we will be using: + +- 50: Upstream, using the 192.0.2.0/24 network allocated by them. +- 100: 'Public' network, using our 203.0.113.0/24 network. +- 201: 'Internal' network, using 10.200.201.0/24 + +### Hardware + +- switch1 (Nexus 10gb Switch) +- switch2 (Nexus 10gb Switch) +- compute1 (VMware ESXi 6.5) +- compute2 (VMware ESXi 6.5) +- compute3 (VMware ESXi 6.5) +- router2 (Random 1RU machine with 4 NICs) + +Note that router1 is a VM that runs on one of the compute nodes. + +### Network Cabling + +- From Datacenter - This connects into port 1 on both switches, and is tagged + as VLAN 50 +- Cisco VPC Crossconnect - Ports 39 and 40 bonded between each switch +- Hardware Router - Port 8 of each switch +- compute1 - Port 9 of each switch +- compute2 - Port 10 of each switch +- compute3 - Port 11 of each switch + +This is ignoring the extra Out-of-band management networking, which should be +on totally different switches, and a different feed into the rack, and is out +of scope of this. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Our implementation uses VMware's Distributed Port Groups, which allows +VMware to use LACP. This is a part of the ENTERPRISE licence, and is not +available on a free licence. If you are implementing this and do not have +access to DPGs, you should not use VMware, and use some other virtualization +platform instead. + +</div> + +## Basic Setup (via console) + +Create your router1 VM. So it can withstand a VM Host failing or a +network link failing. Using VMware, this is achieved by enabling vSphere DRS, +vSphere Availability, and creating a Distributed Port Group that uses LACP. + +Many other Hypervisors do this, and I'm hoping that this document will be +expanded to document how to do this for others. + +Create an 'All VLANs' network group, that passes all trunked traffic through +to the VM. Attach this network group to router1 as eth0. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +VMware: You must DISABLE SECURITY on this Port group. Make sure that +`Promiscuous Mode`, `MAC address changes` and `Forged transmits` are +enabled. All of these will be done as part of failover. + +</div> + +### Bonding on Hardware Router + +Create a LACP bond on the hardware router. We are assuming that eth0 and eth1 +are connected to port 8 on both switches, and that those ports are configured +as a Port-Channel. + +``` none +set interfaces bonding bond0 description 'Switch Port-Channel' +set interfaces bonding bond0 hash-policy 'layer2' +set interfaces bonding bond0 member interface 'eth0' +set interfaces bonding bond0 member interface 'eth1' +set interfaces bonding bond0 mode '802.3ad' +``` + +### Assign external IP addresses + +VLAN 100 and 201 will have floating IP addresses, but VLAN50 does not, as this +is talking directly to upstream. Create our IP address on vlan50. + +For the hardware router, replace `eth0` with `bond0`. As (almost) every +command is identical, this will not be specified unless different things need +to be performed on different hosts. + +``` none +set interfaces ethernet eth0 vif 50 address '192.0.2.21/24' +``` + +In this case, the hardware router has a different IP, so it would be + +``` none +set interfaces ethernet bond0 vif 50 address '192.0.2.22/24' +``` + +### Add (temporary) default route + +It is assumed that the routers provided by upstream are capable of acting as a +default router, add that as a static route. + +``` none +set protocols static route 0.0.0.0/0 next-hop 192.0.2.11 +commit +save +``` + +### Enable SSH + +Enable SSH so you can now SSH into the routers, rather than using the console. + +``` none +set service ssh +commit +save +``` + +At this point, you should be able to SSH into both of them, and will no longer +need access to the console (unless you break something!) + +## VRRP Configuration + +We are setting up VRRP so that it does NOT fail back when a machine returns into +service, and it prioritizes router1 over router2. + +### Internal Network + +This has a floating IP address of 10.200.201.1/24, using virtual router ID 201. +The difference between them is the interface name, hello-source-address, and +peer-address. + +**router1** + +``` none +set interfaces ethernet eth0 vif 201 address 10.200.201.2/24 +set high-availability vrrp group int hello-source-address '10.200.201.2' +set high-availability vrrp group int interface 'eth0.201' +set high-availability vrrp group int peer-address '10.200.201.3' +set high-availability vrrp group int no-preempt +set high-availability vrrp group int priority '200' +set high-availability vrrp group int address '10.200.201.1/24' +set high-availability vrrp group int vrid '201' +``` + +**router2** + +``` none +set interfaces ethernet bond0 vif 201 address 10.200.201.3/24 +set high-availability vrrp group int hello-source-address '10.200.201.3' +set high-availability vrrp group int interface 'bond0.201' +set high-availability vrrp group int peer-address '10.200.201.2' +set high-availability vrrp group int no-preempt +set high-availability vrrp group int priority '100' +set high-availability vrrp group int address '10.200.201.1/24' +set high-availability vrrp group int vrid '201' +``` + +### Public Network + +This has a floating IP address of 203.0.113.1/24, using virtual router ID 113. +The virtual router ID is just a random number between 1 and 254, and can be set +to whatever you want. Best practices suggest you try to keep them unique +enterprise-wide. + +**router1** + +``` none +set interfaces ethernet eth0 vif 100 address 203.0.113.2/24 +set high-availability vrrp group public hello-source-address '203.0.113.2' +set high-availability vrrp group public interface 'eth0.100' +set high-availability vrrp group public peer-address '203.0.113.3' +set high-availability vrrp group public no-preempt +set high-availability vrrp group public priority '200' +set high-availability vrrp group public address '203.0.113.1/24' +set high-availability vrrp group public vrid '113' +``` + +**router2** + +``` none +set interfaces ethernet bond0 vif 100 address 203.0.113.3/24 +set high-availability vrrp group public hello-source-address '203.0.113.3' +set high-availability vrrp group public interface 'bond0.100' +set high-availability vrrp group public peer-address '203.0.113.2' +set high-availability vrrp group public no-preempt +set high-availability vrrp group public priority '100' +set high-availability vrrp group public address '203.0.113.1/24' +set high-availability vrrp group public vrid '113' +``` + +### Create VRRP sync-group + +The sync group is used to replicate connection tracking. It needs to be assigned +to a random VRRP group, and we are creating a sync group called `sync` using +the vrrp group `int`. + +``` none +set high-availability vrrp sync-group sync member 'int' +``` + +### Testing + +At this point, you should be able to see both IP addresses when you run +`show interfaces`, and `show vrrp` should show both interfaces in MASTER +state (and SLAVE state on router2). + +``` none +vyos@router1:~$ show vrrp +Name Interface VRID State Last Transition +-------- ----------- ------ ------- ----------------- +int eth0.201 201 MASTER 100s +public eth0.100 113 MASTER 200s +vyos@router1:~$ +``` + +You should be able to ping to and from all the IPs you have allocated. + +## NAT and conntrack-sync + +Masquerade Traffic originating from 10.200.201.0/24 that is heading out the +public interface. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +We explicitly exclude the primary upstream network so that BGP or +OSPF traffic doesn't accidentally get NAT'ed. + +</div> + +``` none +set nat source rule 10 destination address '!192.0.2.0/24' +set nat source rule 10 outbound-interface 'eth0.50' +set nat source rule 10 source address '10.200.201.0/24' +set nat source rule 10 translation address '203.0.113.1' +``` + +### Configure conntrack-sync and enable helpers + +Conntrack helper modules are enabled by default, but they tend to cause more +problems than they're worth in complex networks. You can disable all of them +at one go. + +``` none +delete system conntrack modules +``` + +Now enable replication between nodes. Replace eth0.201 with bond0.201 on the +hardware router. + +``` none +set service conntrack-sync accept-protocol 'tcp,udp,icmp' +set service conntrack-sync event-listen-queue-size '8' +set service conntrack-sync failover-mechanism vrrp sync-group 'sync' +set service conntrack-sync interface eth0.201 +set service conntrack-sync mcast-group '224.0.0.50' +set service conntrack-sync sync-queue-size '8' +``` + +### Testing + +The simplest way to test is to look at the connection tracking stats on the +standby hardware router with the command `show conntrack-sync statistics`. +The numbers should be very close to the numbers on the primary router. + +When you have both routers up, you should be able to establish a connection +from a NAT'ed machine out to the internet, reboot the active machine, and that +connection should be preserved, and will not drop out. + +## OSPF Over WireGuard + +Wireguard doesn't have the concept of an up or down link, due to its design. +This complicates AND simplifies using it for network transport, as for reliable +state detection you need to use SOMETHING to detect when the link is down. + +If you use a routing protocol itself, you solve two problems at once. This is +only a basic example, and is provided as a starting point. + +### Configure Wireguard + +There is plenty of instructions and documentation on setting up Wireguard. The +only important thing you need to remember is to only use one WireGuard +interface per OSPF connection. + +We use small /30's from 10.254.60/24 for the point-to-point links. + +**router1** + +Replace the 203.0.113.3 with whatever the other router's IP address is. + +``` none +set interfaces wireguard wg01 address '10.254.60.1/30' +set interfaces wireguard wg01 description 'router1-to-offsite1' +set interfaces wireguard wg01 peer OFFSITE1 allowed-ips '0.0.0.0/0' +set interfaces wireguard wg01 peer OFFSITE1 endpoint '203.0.113.3:50001' +set interfaces wireguard wg01 peer OFFSITE1 persistent-keepalive '15' +set interfaces wireguard wg01 peer OFFSITE1 pubkey 'GEFMOWzAyau42/HwdwfXnrfHdIISQF8YHj35rOgSZ0o=' +set interfaces wireguard wg01 port '50001' +set protocols ospf interface wg01 authentication md5 key-id 1 md5-key 'i360KoCwUGZvPq7e' +set protocols ospf interface wg01 cost '11' +set protocols ospf interface wg01 dead-interval '5' +set protocols ospf interface wg01 hello-interval '1' +set protocols ospf interface wg01 network 'point-to-point' +set protocols ospf interface wg01 priority '1' +set protocols ospf interface wg01 retransmit-interval '5' +set protocols ospf interface wg01 transmit-delay '1' +``` + +**offsite1** + +This is connecting back to the STATIC IP of router1, not the floating. + +``` none +set interfaces wireguard wg01 address '10.254.60.2/30' +set interfaces wireguard wg01 description 'offsite1-to-router1' +set interfaces wireguard wg01 peer ROUTER1 allowed-ips '0.0.0.0/0' +set interfaces wireguard wg01 peer ROUTER1 endpoint '192.0.2.21:50001' +set interfaces wireguard wg01 peer ROUTER1 persistent-keepalive '15' +set interfaces wireguard wg01 peer ROUTER1 pubkey 'CKwMV3ZaLntMule2Kd3G7UyVBR7zE8/qoZgLb82EE2Q=' +set interfaces wireguard wg01 port '50001' +set protocols ospf interface wg01 authentication md5 key-id 1 md5-key 'i360KoCwUGZvPq7e' +set protocols ospf interface wg01 cost '11' +set protocols ospf interface wg01 dead-interval '5' +set protocols ospf interface wg01 hello-interval '1' +set protocols ospf interface wg01 network 'point-to-point' +set protocols ospf interface wg01 priority '1' +set protocols ospf interface wg01 retransmit-interval '5' +set protocols ospf interface wg01 transmit-delay '1' +``` + +### Test WireGuard + +Make sure you can ping 10.254.60.1 and .2 from both routers. + +### Create Export Filter + +We only want to export the networks we know. Always do a whitelist on your route +filters, both importing and exporting. A good rule of thumb is +**'If you are not the default router for a network, don't advertise +it'**. This means we explicitly do not want to advertise the 192.0.2.0/24 +network (but do want to advertise 10.200.201.0 and 203.0.113.0, which we ARE +the default route for). This filter is applied to `redistribute connected`. +If we WERE to advertise it, the remote machines would see 192.0.2.21 available +via their default route, establish the connection, and then OSPF would say +'192.0.2.0/24 is available via this tunnel', at which point the tunnel would +break, OSPF would drop the routes, and then 192.0.2.0/24 would be reachable via +default again. This is called 'flapping'. + +``` none +set policy access-list 150 description 'Outbound OSPF Redistribution' +set policy access-list 150 rule 10 action 'permit' +set policy access-list 150 rule 10 destination any +set policy access-list 150 rule 10 source inverse-mask '0.0.0.255' +set policy access-list 150 rule 10 source network '10.200.201.0' +set policy access-list 150 rule 20 action 'permit' +set policy access-list 150 rule 20 destination any +set policy access-list 150 rule 20 source inverse-mask '0.0.0.255' +set policy access-list 150 rule 20 source network '203.0.113.0' +set policy access-list 150 rule 100 action 'deny' +set policy access-list 150 rule 100 destination any +set policy access-list 150 rule 100 source any +``` + +### Create Import Filter + +We only want to import networks we know. Our OSPF peer should only be +advertising networks in the 10.201.0.0/16 range. Note that this is an INVERSE +MATCH. You deny in access-list 100 to accept the route. + +``` none +set policy access-list 100 description 'Inbound OSPF Routes from Peers' +set policy access-list 100 rule 10 action 'deny' +set policy access-list 100 rule 10 destination any +set policy access-list 100 rule 10 source inverse-mask '0.0.255.255' +set policy access-list 100 rule 10 source network '10.201.0.0' +set policy access-list 100 rule 100 action 'permit' +set policy access-list 100 rule 100 destination any +set policy access-list 100 rule 100 source any +set policy route-map PUBOSPF rule 100 action 'deny' +set policy route-map PUBOSPF rule 100 match ip address access-list '100' +set policy route-map PUBOSPF rule 500 action 'permit' +``` + +### Enable OSPF + +Every router **must** have a unique router-id. +The 'reference-bandwidth' is used because when OSPF was originally designed, +the idea of a link faster than 1gbit was unheard of, and it does not scale +correctly. + +``` none +set protocols ospf area 0.0.0.0 authentication 'md5' +set protocols ospf area 0.0.0.0 network '10.254.60.0/24' +set protocols ospf auto-cost reference-bandwidth '10000' +set protocols ospf log-adjacency-changes +set protocols ospf parameters abr-type 'cisco' +set protocols ospf parameters router-id '10.254.60.2' +set protocols ospf route-map PUBOSPF +``` + +### Test OSPF + +When you have enabled OSPF on both routers, you should be able to see each +other with the command `show ip ospf neighbour`. The state must be 'Full' +or '2-Way'. If it is not, then there is a network connectivity issue between the +hosts. This is often caused by NAT or MTU issues. You should not see any new +routes (unless this is the second pass) in the output of `show ip route` + +## Advertise connected routes + +As a reminder, only advertise routes that you are the default router for. This +is why we are NOT announcing the 192.0.2.0/24 network, because if that was +announced into OSPF, the other routers would try to connect to that network +over a tunnel that connects to that network! + +``` none +set protocols ospf access-list 150 export 'connected' +set protocols ospf redistribute connected +``` + +You should now be able to see the advertised network on the other host. + +### Duplicate configuration + +At this point, you now need to create the X link between all four routers. +Use a different /30 for each link. + +### Priorities + +Set the cost on the secondary links to be 200. This means that they will not +be used unless the primary links are down. + +``` none +set protocols ospf interface wg01 cost '10' +set protocols ospf interface wg01 cost '200' +``` + +This will be visible in 'show ip route'. + +## BGP + +BGP is an extremely complex network protocol. An example is provided here. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Router id's must be unique. + +</div> + +**router1** + +The `redistribute ospf` command is there purely as an example of how this can +be expanded. In this walkthrough, it will be filtered by BGPOUT rule 10000, as +it is not 203.0.113.0/24. + +``` none +set policy prefix-list BGPOUT description 'BGP Export List' +set policy prefix-list BGPOUT rule 10 action 'deny' +set policy prefix-list BGPOUT rule 10 description 'Do not advertise short masks' +set policy prefix-list BGPOUT rule 10 ge '25' +set policy prefix-list BGPOUT rule 10 prefix '0.0.0.0/0' +set policy prefix-list BGPOUT rule 100 action 'permit' +set policy prefix-list BGPOUT rule 100 description 'Our network' +set policy prefix-list BGPOUT rule 100 prefix '203.0.113.0/24' +set policy prefix-list BGPOUT rule 10000 action 'deny' +set policy prefix-list BGPOUT rule 10000 prefix '0.0.0.0/0' + +set policy route-map BGPOUT description 'BGP Export Filter' +set policy route-map BGPOUT rule 10 action 'permit' +set policy route-map BGPOUT rule 10 match ip address prefix-list 'BGPOUT' +set policy route-map BGPOUT rule 10000 action 'deny' +set policy route-map BGPPREPENDOUT description 'BGP Export Filter' +set policy route-map BGPPREPENDOUT rule 10 action 'permit' +set policy route-map BGPPREPENDOUT rule 10 set as-path prepend '65551 65551 65551' +set policy route-map BGPPREPENDOUT rule 10 match ip address prefix-list 'BGPOUT' +set policy route-map BGPPREPENDOUT rule 10000 action 'deny' + +set protocols bgp system-as 65551 +set protocols bgp address-family ipv4-unicast network 192.0.2.0/24 +set protocols bgp address-family ipv4-unicast redistribute connected metric '50' +set protocols bgp address-family ipv4-unicast redistribute ospf metric '50' +set protocols bgp neighbor 192.0.2.11 address-family ipv4-unicast route-map export 'BGPOUT' +set protocols bgp neighbor 192.0.2.11 address-family ipv4-unicast soft-reconfiguration inbound +set protocols bgp neighbor 192.0.2.11 remote-as '65550' +set protocols bgp neighbor 192.0.2.11 update-source '192.0.2.21' +set protocols bgp parameters router-id '192.0.2.21' +``` + +**router2** + +This is identical, but you use the BGPPREPENDOUT route-map to advertise the +route with a longer path. diff --git a/docs/configexamples/md-index.md b/docs/configexamples/md-index.md new file mode 100644 index 00000000..ec0a5077 --- /dev/null +++ b/docs/configexamples/md-index.md @@ -0,0 +1,54 @@ +# Configuration Blueprints + +This chapter contains various configuration examples: + +<div class="toctree" maxdepth="2"> + +firewall +bgp-ipv6-unnumbered +ospf-unnumbered +azure-vpn-bgp +azure-vpn-dual-bgp +ha +wan-load-balancing +pppoe-ipv6-basic +l3vpn-hub-and-spoke +lac-lns +inter-vrf-routing-vrf-lite +qos +segment-routing-isis +nmp +ipsec-cisco-policy-based +ipsec-cisco-route-based +ipsec-pa-route-based + +</div> + +# Configuration Blueprints (autotest) + +The next pages contains automatic full tested configuration examples. + +Each lab will build an test from an external script. +The page content will generate, so changes will not take an effect. + +A host `vyos-oobm` will use as a ssh proxy. This host is just +necessary for the Lab test. + +The process will do the following steps: + +1. create the lab on a eve-ng server +2. configure each host in the lab +3. do some defined tests +4. optional do an upgrade to a higher version and do step 3 again. +5. generate the documentation and include files +6. shutdown and destroy the lab, if there is no error + +<div class="toctree" maxdepth="1"> + +autotest/DHCPRelay_through_GRE/DHCPRelay_through_GRE +autotest/tunnelbroker/tunnelbroker +autotest/L3VPN_EVPN/L3VPN_EVPN +autotest/Wireguard/Wireguard +autotest/OpenVPN_with_LDAP/OpenVPN_with_LDAP + +</div> diff --git a/docs/configexamples/md-inter-vrf-routing-vrf-lite.md b/docs/configexamples/md-inter-vrf-routing-vrf-lite.md new file mode 100644 index 00000000..62eec937 --- /dev/null +++ b/docs/configexamples/md-inter-vrf-routing-vrf-lite.md @@ -0,0 +1,910 @@ +# Inter-VRF Routing over VRF Lite + +**Virtual Routing and Forwarding** is a technology that allow multiple instance +of a routing table to exist within a single device. One of the key aspect of +**VRFs** is that do not share the same routes or interfaces, therefore packets +are forwarded between interfaces that belong to the same VRF only. + +Any information related to a VRF is not exchanged between devices -or in the +same device- by default, this is a technique called **VRF-Lite**. + +Keep networks isolated is -in general- a good principle, but there are cases +where you might need that some network can access other in a different VRF. + +The scope of this document is to cover such cases in a dynamic way without the +use of MPLS-LDP. + +General information about L3VPNs can be found in the `configuration/vrf/index:L3VPN VRFs` chapter. + +## Overview + +Let’s say we have a requirement to have multiple networks. + +- LAN 1 +- LAN 2 +- Management +- Internet + +Both LANs have to be able to route between each other, both will have managed +devices through a dedicated management network and both will need Internet +access yet the LAN2 will need access to some set of outside networks, not all. +The management network will need access to both LANs but cannot have access +to/from the outside. + +This scenario could be a nightmare applying regular routing and might need +filtering in multiple interfaces. + +A simple solution could be using different routing tables, or VRFs +for all the networks so we can keep the routing restrictions. +But for us to route between the different VRFs we would need a cable or a +logical connection between each other: + +- One cable/logical connection between LAN1 and LAN2 +- One cable/logical connection between LAN1 and Internet +- One cable/logical connection between LAN2 and Internet +- One cable/logical connection between LAN1 and Management +- One cable/logical connection between LAN2 and Management + +As we can see this is unpractical. + +To address this scenario we will use to our advantage an extension of the BGP +routing protocol that will help us in the “Export” between VRFs without the +need for MPLS. + +MP-BGP or MultiProtocol BGP introduces two main concepts to solve this +limitation: +- Route Distinguisher (RD): Is used to distinguish between different VRFs +–called VPNs- inside the BGP Process. The RD is appended to each IPv4 Network +that is advertised into BGP for that VPN making it a unique VPNv4 route. +- Route Target (RT): This is an extended BGP community append to the VPNv4 route +in the Import/Export process. When a route passes from the VRF routing table +into the BGP process it will add the configured export extended community(ies) +for that VPN. When that route needs to go from BGP into the VRF routing table +will only pass if that given VPN import policy matches any of the appended +community(ies) into that prefix. + +## Topology + +<img src="/_static/images/inter-vrf-routing-vrf-lite.webp" class="align-center" style="width:70.0%" alt="Network Topology Diagram" /> + +### IP Schema + +<table style="width:83%;"> +<colgroup> +<col style="width: 15%" /> +<col style="width: 18%" /> +<col style="width: 23%" /> +<col style="width: 26%" /> +</colgroup> +<tbody> +<tr> +<td>Device-A</td> +<td><blockquote> +<p>Device-B</p> +</blockquote></td> +<td><blockquote> +<p>IPv4 Network</p> +</blockquote></td> +<td><blockquote> +<p>IPv6 Network</p> +</blockquote></td> +</tr> +<tr> +<td><blockquote> +<p>Core</p> +</blockquote></td> +<td><blockquote> +<p>LAN1</p> +</blockquote></td> +<td><blockquote> +<p>10.1.1.0/30</p> +</blockquote></td> +<td><blockquote> +<p>2001:db8::/127</p> +</blockquote></td> +</tr> +<tr> +<td><blockquote> +<p>Core</p> +</blockquote></td> +<td><blockquote> +<p>LAN2</p> +</blockquote></td> +<td>172.16.2.0/30</td> +<td><blockquote> +<p>2001:db8::2/127</p> +</blockquote></td> +</tr> +<tr> +<td><blockquote> +<p>Core</p> +</blockquote></td> +<td>Management</td> +<td>192.168.3.0/30</td> +<td><blockquote> +<p>2001:db8::4/127</p> +</blockquote></td> +</tr> +<tr> +<td><blockquote> +<p>Core</p> +</blockquote></td> +<td><blockquote> +<p>ISP</p> +</blockquote></td> +<td><blockquote> +<p>10.2.2.0/30</p> +</blockquote></td> +<td><blockquote> +<p>2001:db8::6/127</p> +</blockquote></td> +</tr> +</tbody> +</table> + +### RD & RT Schema + +<table style="width:51%;"> +<colgroup> +<col style="width: 18%" /> +<col style="width: 16%" /> +<col style="width: 16%" /> +</colgroup> +<tbody> +<tr> +<td><blockquote> +<p>VRF</p> +</blockquote></td> +<td><blockquote> +<p>RD</p> +</blockquote></td> +<td><blockquote> +<p>RT</p> +</blockquote></td> +</tr> +<tr> +<td><blockquote> +<p>LAN1</p> +</blockquote></td> +<td><blockquote> +<p>64496:1</p> +</blockquote></td> +<td><blockquote> +<p>64496:1</p> +</blockquote></td> +</tr> +<tr> +<td><blockquote> +<p>LAN2</p> +</blockquote></td> +<td><blockquote> +<p>64496:2</p> +</blockquote></td> +<td><blockquote> +<p>64496:2</p> +</blockquote></td> +</tr> +<tr> +<td>Management</td> +<td>64496:50</td> +<td>64496:50</td> +</tr> +<tr> +<td><blockquote> +<p>Internet</p> +</blockquote></td> +<td>64496:100</td> +<td>64496:100</td> +</tr> +</tbody> +</table> + +## Configurations + +<div class="note"> + +<div class="title"> + +Note + +</div> + +We use a static route configuration in between the Core and each +LAN and Management router, and BGP between the Core router and the ISP router +but any dynamic routing protocol can be used. + +</div> + +### Remote Networks + +The following template configuration can be used in each remote router based +in our topology. + +``` none +# Interface Configuration +set interface eth eth<N> address <IP ADDRESS/CIDR> + +# Static default route back to Core +set procotols static route 0.0.0.0/0 next-hop <CORE IP ADDRESS> +``` + +### Core Router + +#### Step 1: VRF and Configurations to remote networks + +- Configuration + +Set the VRF name and Table ID, set interface address and bind it to the VRF. +Last add the static route to the remote network. + +``` none +# VRF name and table ID (MANDATORY) +set vrf name <VRF> table <ID> + +# Interface Configuration +set interface eth eth<N> address <IP ADDRESS/CIDR> + +# Assign interface to VRF +set interface eth eth<N> vrf <VRF> + +# Static route to remote Network +set vrf name <VRF> protocols static route <NETWORK/CIDR> next-hop <REMOTE IP ADDRESS> +``` + +- Verification + +Checking the routing table of the VRF should reveal both static and connected +entries active. A PING test between the Core and remote router is a way to +validate connectivity within the VRF. + +``` none +# show ip route vrf <VRF> +# show ipv6 route vrf <VRF> + +vyos@Core:~$ show ip route vrf LAN1 +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +VRF LAN1: +S>* 10.0.0.0/24 [1/0] via 10.1.1.2, eth0, weight 1, 00:05:41 +C>* 10.1.1.0/30 is directly connected, eth0, 00:05:44 + +vyos@Core:~$ show ipv6 route vrf LAN1 +Codes: K - kernel route, C - connected, S - static, R - RIPng, + O - OSPFv3, I - IS-IS, B - BGP, N - NHRP, T - Table, + v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +VRF LAN1: +C>* 2001:db8::/127 is directly connected, eth0, 00:18:43 +S>* 2001:db8:0:1::/64 [1/0] via 2001:db8::1, eth0, weight 1, 00:16:03 +C>* fe80::/64 is directly connected, eth0, 00:18:43 + +# ping <DESTINATION> vrf <VRF> + +vyos@Core:~$ ping 10.1.1.2 vrf LAN1 +PING 10.1.1.2 (10.1.1.2) 56(84) bytes of data. +64 bytes from 10.1.1.2: icmp_seq=1 ttl=64 time=1.52 ms +64 bytes from 10.1.1.2: icmp_seq=2 ttl=64 time=0.830 ms +^C +--- 10.1.1.2 ping statistics --- +2 packets transmitted, 2 received, 0% packet loss, time 1002ms +rtt min/avg/max/mdev = 0.830/1.174/1.518/0.344 ms +vyos@Core:~$ ping 10.0.0.1 vrf LAN1 +PING 10.0.0.1 (10.0.0.1) 56(84) bytes of data. +64 bytes from 10.0.0.1: icmp_seq=1 ttl=64 time=0.785 ms +64 bytes from 10.0.0.1: icmp_seq=2 ttl=64 time=0.948 ms +^C +--- 10.0.0.1 ping statistics --- +2 packets transmitted, 2 received, 0% packet loss, time 1002ms +rtt min/avg/max/mdev = 0.785/0.866/0.948/0.081 ms + +vyos@Core:~$ ping 2001:db8:0:1::1 vrf LAN1 +PING 2001:db8:0:1::1(2001:db8:0:1::1) 56 data bytes +64 bytes from 2001:db8:0:1::1: icmp_seq=1 ttl=64 time=3.04 ms +64 bytes from 2001:db8:0:1::1: icmp_seq=2 ttl=64 time=1.04 ms +64 bytes from 2001:db8:0:1::1: icmp_seq=3 ttl=64 time=0.925 ms +^C +--- 2001:db8:0:1::1 ping statistics --- +3 packets transmitted, 3 received, 0% packet loss, time 2004ms +rtt min/avg/max/mdev = 0.925/1.665/3.035/0.969 ms +``` + +#### Step 2: BGP Configuration for VRF-Lite + +- Configuration + +Setting BGP global local-as as well inside the VRF. Redistribute static routes +to inject configured networks into the BGP process but still inside the VRF. + +``` none +# set BGP global local-as +set protocols bgp system-as <ASN> + +# set BGP VRF local-as and redistribution +set vrf name <VRF> protocols bgp system-as <ASN> +set vrf name <VRF> protocols bgp address-family <AF IPv4/IPv6> redistribute static +``` + +- Verification + +Check the BGP VRF table and verify if the static routes are injected showing +the correct next-hop information. + +``` none +# show ip bgp vrf <VRF> +# show bgp vrf <VRF> ipv6 + +vyos@Core:~$ show ip bgp vrf LAN1 +BGP table version is 3, local router ID is 10.1.1.1, vrf id 8 +Default local pref 100, local AS 64496 +Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, + i internal, r RIB-failure, S Stale, R Removed +Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self +Origin codes: i - IGP, e - EGP, ? - incomplete +RPKI validation codes: V valid, I invalid, N Not found + + Network Next Hop Metric LocPrf Weight Path +*> 10.0.0.0/24 10.1.1.2 0 32768 ? + +vyos@Core# run show bgp vrf LAN1 ipv6 +BGP table version is 13, local router ID is 10.1.1.1, vrf id 8 +Default local pref 100, local AS 64496 +Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, + i internal, r RIB-failure, S Stale, R Removed +Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self +Origin codes: i - IGP, e - EGP, ? - incomplete +RPKI validation codes: V valid, I invalid, N Not found + + Network Next Hop Metric LocPrf Weight Path +*> 2001:db8:0:1::/64 + 2001:db8::1 0 32768 ? +``` + +#### Step 3: VPN Configuration + +- Configuration + +Within the VRF we set the Route-Distinguisher (RD) and Route-Targets (RT), then +we enable the export/import VPN. + +``` none +# set Route-distinguisher +set vrf name <VRF> protocols bgp address-family <AF IPv4/IPv6> rd vpn export '<RD>' + +# set route-target for import/export +# Note: RT are a list that can be more than one community between apostrophe +# and separated by blank space. Ex: '<RT:1> <RT:2> <RT:3>' +set vrf name <VRF> protocols bgp address-family <AF IPv4/IPv6> route-target vpn export '<RT:Export>' +set vrf name <VRF> protocols bgp address-family <AF IPv4/IPv6> route-target vpn import '<RT:Import>' + +# Enable VPN export/import under this VRF +set vrf name <VRF> protocols bgp address-family <AF IPv4/IPv6> export vpn +set vrf name <VRF> protocols bgp address-family <AF IPv4/IPv6> import vpn +``` + +A key point to understand is that if we need two VRFs to communicate between +each other EXPORT rt from VRF1 has to be in the IMPORT rt list from VRF2. But +this is only in ONE direction, to complete the communication the EXPORT rt from +VRF2 has to be in the IMPORT rt list from VRF1. + +There are some cases where this is not needed -for example, in some +DDoS appliance- but most inter-vrf routing designs use the above configurations. + +- Verification + +After configured all the VRFs involved in this topology we take a deeper look +at both BGP and Routing table for the VRF LAN1 + +``` none +# show ip bgp vrf <VRF> +# show bgp vrf <VRF> ipv6 + +vyos@Core# run show ip bgp vrf LAN1 +BGP table version is 53, local router ID is 10.1.1.1, vrf id 8 +Default local pref 100, local AS 64496 +Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, + i internal, r RIB-failure, S Stale, R Removed +Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self +Origin codes: i - IGP, e - EGP, ? - incomplete +RPKI validation codes: V valid, I invalid, N Not found + + Network Next Hop Metric LocPrf Weight Path +*> 0.0.0.0/0 10.2.2.2@7< 0 64497 i +*> 10.0.0.0/24 10.1.1.2 0 32768 ? +*> 10.2.2.0/30 10.2.2.2@7< 0 0 64497 ? +*> 192.0.2.0/24 10.2.2.2@7< 0 0 64497 ? +*> 192.168.0.0/24 192.168.3.2@11< 0 32768 ? +*> 198.51.100.0/24 10.2.2.2@7< 0 0 64497 ? +*> 203.0.113.0/24 10.2.2.2@7< 0 0 64497 ? + +vyos@Core# run show bgp vrf LAN1 ipv6 +BGP table version is 13, local router ID is 10.1.1.1, vrf id 8 +Default local pref 100, local AS 64496 +Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, + i internal, r RIB-failure, S Stale, R Removed +Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self +Origin codes: i - IGP, e - EGP, ? - incomplete +RPKI validation codes: V valid, I invalid, N Not found + +Network Next Hop Metric LocPrf Weight Path +*> ::/0 fe80::5200:ff:fe02:3@7< + 0 64497 i +*> 2001:db8::6/127 fe80::5200:ff:fe02:3@7< + 0 0 64497 ? +*> 2001:db8:0:1::/64 + 2001:db8::1 0 32768 ? +*> 2001:db8:0:3::/64 + 2001:db8::5@11< 0 32768 ? +*> 2001:db8:1::/48 fe80::5200:ff:fe02:3@7< + 0 0 64497 ? +*> 2001:db8:2::/48 fe80::5200:ff:fe02:3@7< + 0 0 64497 ? +*> 2001:db8:3::/48 fe80::5200:ff:fe02:3@7< + 0 0 64497 ? + + +# show ip route vrf <VRF> +# show ipv6 route vrf <VRF> + +vyos@Core:~$ show ip route vrf LAN1 +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +VRF LAN1: +B>* 0.0.0.0/0 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:00:38 +S>* 10.0.0.0/24 [1/0] via 10.1.1.2, eth0, weight 1, 00:29:57 +C>* 10.1.1.0/30 is directly connected, eth0, 00:29:59 +B 10.2.2.0/30 [20/0] via 10.2.2.2 (vrf Internet) inactive, weight 1, 00:00:38 +B>* 172.16.0.0/24 [20/0] via 172.16.2.2, eth1 (vrf LAN2), weight 1, 00:00:38 +B>* 192.0.2.0/24 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:00:38 +B>* 198.51.100.0/24 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:00:38 +B>* 203.0.113.0/24 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:00:38 + +vyos@Core# run show ipv6 route vrf LAN1 +Codes: K - kernel route, C - connected, S - static, R - RIPng, + O - OSPFv3, I - IS-IS, B - BGP, N - NHRP, T - Table, + v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +VRF LAN1: +B>* ::/0 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:07:50 +C>* 2001:db8::/127 is directly connected, eth0, 05:33:43 +B>* 2001:db8::6/127 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:07:50 +S>* 2001:db8:0:1::/64 [1/0] via 2001:db8::1, eth0, weight 1, 05:31:03 +B>* 2001:db8:0:3::/64 [20/0] via 2001:db8::5, eth2 (vrf Management), weight 1, 00:07:50 +B>* 2001:db8:1::/48 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:07:50 +B>* 2001:db8:2::/48 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:07:50 +B>* 2001:db8:3::/48 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:07:50 +C>* fe80::/64 is directly connected, eth0, 05:33:43 +``` + +As we can see in the BGP table any imported route has been injected with a "@" +followed by the VPN id; In the routing table of the VRF, if the route was +installed, we can see -between round brackets- the exported VRF table. + +#### Step 4: End to End verification + +Now we perform some end-to-end testing + +- From Management to LAN1/LAN2 + +``` none +vyos@Management:~$ ping 10.0.0.1 source-address 192.168.0.1 +PING 10.0.0.1 (10.0.0.1) from 192.168.0.1 : 56(84) bytes of data. +64 bytes from 10.0.0.1: icmp_seq=1 ttl=63 time=1.93 ms +64 bytes from 10.0.0.1: icmp_seq=2 ttl=63 time=2.12 ms +64 bytes from 10.0.0.1: icmp_seq=3 ttl=63 time=2.12 ms +^C +--- 10.0.0.1 ping statistics --- +3 packets transmitted, 3 received, 0% packet loss, time 2005ms +rtt min/avg/max/mdev = 1.931/2.056/2.123/0.088 ms +vyos@Management:~$ ping 172.16.0.1 source-address 192.168.0.1 +PING 172.16.0.1 (172.16.0.1) from 192.168.0.1 : 56(84) bytes of data. +64 bytes from 172.16.0.1: icmp_seq=1 ttl=63 time=1.62 ms +64 bytes from 172.16.0.1: icmp_seq=2 ttl=63 time=1.75 ms +^C +--- 172.16.0.1 ping statistics --- +2 packets transmitted, 2 received, 0% packet loss, time 1001ms +rtt min/avg/max/mdev = 1.621/1.686/1.752/0.065 ms +vyos@Management:~$ ping 2001:db8:0:1::1 source-address 2001:db8:0:3::1 +PING 2001:db8:0:1::1(2001:db8:0:1::1) from 2001:db8:0:3::1 : 56 data bytes +64 bytes from 2001:db8:0:1::1: icmp_seq=1 ttl=63 time=2.44 ms +64 bytes from 2001:db8:0:1::1: icmp_seq=2 ttl=63 time=2.40 ms +64 bytes from 2001:db8:0:1::1: icmp_seq=3 ttl=63 time=2.41 ms +^C +--- 2001:db8:0:1::1 ping statistics --- +3 packets transmitted, 3 received, 0% packet loss, time 2003ms +rtt min/avg/max/mdev = 2.399/2.418/2.442/0.017 ms +vyos@Management:~$ ping 2001:db8:0:2::1 source-address 2001:db8:0:3::1 +PING 2001:db8:0:2::1(2001:db8:0:2::1) from 2001:db8:0:3::1 : 56 data bytes +64 bytes from 2001:db8:0:2::1: icmp_seq=1 ttl=63 time=1.66 ms +64 bytes from 2001:db8:0:2::1: icmp_seq=2 ttl=63 time=1.99 ms +64 bytes from 2001:db8:0:2::1: icmp_seq=3 ttl=63 time=1.88 ms +64 bytes from 2001:db8:0:2::1: icmp_seq=4 ttl=63 time=2.32 ms +^C +--- 2001:db8:0:2::1 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 3005ms +rtt min/avg/max/mdev = 1.660/1.960/2.315/0.236 ms +``` + +- From Management to Outside (fails as intended) + +``` none +vyos@Management:~$ show ip route +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +S>* 0.0.0.0/0 [1/0] via 192.168.3.1, eth2, weight 1, 00:01:58 +C>* 192.168.0.0/24 is directly connected, dum0, 00:02:05 +C>* 192.168.3.0/30 is directly connected, eth2, 00:02:03 +vyos@Management:~$ ping 192.0.2.1 +PING 192.0.2.1 (192.0.2.1) 56(84) bytes of data. +From 192.168.3.1 icmp_seq=1 Destination Net Unreachable +From 192.168.3.1 icmp_seq=2 Destination Net Unreachable +^C +--- 192.0.2.1 ping statistics --- +2 packets transmitted, 0 received, +2 errors, 100% packet loss, time 1002ms + +vyos@Management:~$ ping 195.51.100.1 +PING 195.51.100.1 (195.51.100.1) 56(84) bytes of data. +From 192.168.3.1 icmp_seq=1 Destination Net Unreachable +From 192.168.3.1 icmp_seq=2 Destination Net Unreachable +From 192.168.3.1 icmp_seq=3 Destination Net Unreachable +^C +--- 195.51.100.1 ping statistics --- +3 packets transmitted, 0 received, +3 errors, 100% packet loss, time 2003ms + +vyos@Management:~$ ping 2001:db8:1::1 +PING 2001:db8:1::1(2001:db8:1::1) 56 data bytes +From 2001:db8::4 icmp_seq=1 Destination unreachable: No route +From 2001:db8::4 icmp_seq=2 Destination unreachable: No route +^C +--- 2001:db8:1::1 ping statistics --- +2 packets transmitted, 0 received, +2 errors, 100% packet loss, time 1002ms + +vyos@Management:~$ ping 2001:db8:2::1 +PING 2001:db8:2::1(2001:db8:2::1) 56 data bytes +From 2001:db8::4 icmp_seq=1 Destination unreachable: No route +From 2001:db8::4 icmp_seq=2 Destination unreachable: No route +^C +--- 2001:db8:2::1 ping statistics --- +2 packets transmitted, 0 received, +2 errors, 100% packet loss, time 1002ms +``` + +- LAN1 to Outside + +``` none +vyos@LAN1:~$ ping 192.0.2.1 source-address 10.0.0.1 +PING 192.0.2.1 (192.0.2.1) from 10.0.0.1 : 56(84) bytes of data. +64 bytes from 192.0.2.1: icmp_seq=1 ttl=63 time=1.47 ms +64 bytes from 192.0.2.1: icmp_seq=2 ttl=63 time=1.41 ms +64 bytes from 192.0.2.1: icmp_seq=3 ttl=63 time=1.80 ms +^C +--- 192.0.2.1 ping statistics --- +3 packets transmitted, 3 received, 0% packet loss, time 2004ms +rtt min/avg/max/mdev = 1.414/1.563/1.803/0.171 ms +vyos@LAN1:~$ ping 198.51.100.1 source-address 10.0.0.1 +PING 198.51.100.1 (198.51.100.1) from 10.0.0.1 : 56(84) bytes of data. +64 bytes from 198.51.100.1: icmp_seq=1 ttl=63 time=1.71 ms +64 bytes from 198.51.100.1: icmp_seq=2 ttl=63 time=1.83 ms +^C +--- 198.51.100.1 ping statistics --- +2 packets transmitted, 2 received, 0% packet loss, time 1002ms +rtt min/avg/max/mdev = 1.705/1.766/1.828/0.061 ms +vyos@LAN1:~$ ping 203.0.113.1 source-address 10.0.0.1 +PING 203.0.113.1 (203.0.113.1) from 10.0.0.1 : 56(84) bytes of data. +64 bytes from 203.0.113.1: icmp_seq=1 ttl=63 time=1.25 ms +64 bytes from 203.0.113.1: icmp_seq=2 ttl=63 time=1.88 ms +^C +--- 203.0.113.1 ping statistics --- +2 packets transmitted, 2 received, 0% packet loss, time 1003ms +rtt min/avg/max/mdev = 1.249/1.566/1.884/0.317 ms +vyos@LAN1:~$ ping 2001:db8:1::1 source-address 2001:db8:0:1::1 +PING 2001:db8:1::1(2001:db8:1::1) from 2001:db8:0:1::1 : 56 data bytes +64 bytes from 2001:db8:1::1: icmp_seq=1 ttl=63 time=2.35 ms +64 bytes from 2001:db8:1::1: icmp_seq=2 ttl=63 time=2.29 ms +64 bytes from 2001:db8:1::1: icmp_seq=3 ttl=63 time=2.22 ms +^C +--- 2001:db8:1::1 ping statistics --- +3 packets transmitted, 3 received, 0% packet loss, time 2004ms +rtt min/avg/max/mdev = 2.215/2.285/2.352/0.055 ms +vyos@LAN1:~$ ping 2001:db8:2::1 source-address 2001:db8:0:1::1 +PING 2001:db8:2::1(2001:db8:2::1) from 2001:db8:0:1::1 : 56 data bytes +64 bytes from 2001:db8:2::1: icmp_seq=1 ttl=63 time=1.37 ms +64 bytes from 2001:db8:2::1: icmp_seq=2 ttl=63 time=2.68 ms +64 bytes from 2001:db8:2::1: icmp_seq=3 ttl=63 time=2.00 ms +^C +--- 2001:db8:2::1 ping statistics --- +3 packets transmitted, 3 received, 0% packet loss, time 2003ms +rtt min/avg/max/mdev = 1.367/2.015/2.679/0.535 ms +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +we are using "source-address" option cause we are not redistributing +connected interfaces into BGP on the Core router hence there is no comeback +route and ping will fail. + +</div> + +- LAN1 to LAN2 + +``` none +vyos@LAN1:~$ ping 172.16.0.1 source-address 10.0.0.1 +PING 172.16.0.1 (172.16.0.1) from 10.0.0.1 : 56(84) bytes of data. +64 bytes from 172.16.0.1: icmp_seq=1 ttl=63 time=3.00 ms +64 bytes from 172.16.0.1: icmp_seq=2 ttl=63 time=2.20 ms +^C +--- 172.16.0.1 ping statistics --- +2 packets transmitted, 2 received, 0% packet loss, time 1002ms +rtt min/avg/max/mdev = 2.199/2.600/3.001/0.401 ms +vyos@LAN1:~$ ping 2001:db8:0:2::1 source 2001:db8:0:1::1 +PING 2001:db8:0:2::1(2001:db8:0:2::1) from 2001:db8:0:1::1 : 56 data bytes +64 bytes from 2001:db8:0:2::1: icmp_seq=1 ttl=63 time=4.82 ms +64 bytes from 2001:db8:0:2::1: icmp_seq=2 ttl=63 time=1.95 ms +64 bytes from 2001:db8:0:2::1: icmp_seq=3 ttl=63 time=1.98 ms +^C +--- 2001:db8:0:2::1 ping statistics --- +3 packets transmitted, 3 received, 0% packet loss, time 2003ms +rtt min/avg/max/mdev = 1.949/2.915/4.815/1.343 ms +``` + +## Conclusions + +Inter-VRF routing is a well-known solution to address complex routing scenarios +that enable -in a dynamic way- to leak routes between VRFs. Is recommended to +take special consideration while designing route-targets and its application as +it can minimize future interventions while creating a new VRF will automatically +take the desired effect in its propagation. + +## Appendix-A + +### Full configuration from all devices + +- Core + +``` none +set interfaces ethernet eth0 address '10.1.1.1/30' +set interfaces ethernet eth0 address '2001:db8::/127' +set interfaces ethernet eth0 vrf 'LAN1' +set interfaces ethernet eth1 address '172.16.2.1/30' +set interfaces ethernet eth1 address '2001:db8::2/127' +set interfaces ethernet eth1 vrf 'LAN2' +set interfaces ethernet eth2 address '192.168.3.1/30' +set interfaces ethernet eth2 address '2001:db8::4/127' +set interfaces ethernet eth2 vrf 'Management' +set interfaces ethernet eth3 address '10.2.2.1/30' +set interfaces ethernet eth3 address '2001:db8::6/127' +set interfaces ethernet eth3 vrf 'Internet' +set protocols bgp address-family ipv4-unicast +set protocols bgp system-as '64496' +set vrf name Internet protocols bgp address-family ipv4-unicast export vpn +set vrf name Internet protocols bgp address-family ipv4-unicast import vpn +set vrf name Internet protocols bgp address-family ipv4-unicast rd vpn export '64496:100' +set vrf name Internet protocols bgp address-family ipv4-unicast route-target vpn export '64496:100' +set vrf name Internet protocols bgp address-family ipv4-unicast route-target vpn import '64496:1 64496:2' +set vrf name Internet protocols bgp address-family ipv6-unicast export vpn +set vrf name Internet protocols bgp address-family ipv6-unicast import vpn +set vrf name Internet protocols bgp address-family ipv6-unicast rd vpn export '64496:100' +set vrf name Internet protocols bgp address-family ipv6-unicast route-target vpn export '64496:100' +set vrf name Internet protocols bgp address-family ipv6-unicast route-target vpn import '64496:1 64496:2' +set vrf name Internet protocols bgp system-as '64496' +set vrf name Internet protocols bgp neighbor 10.2.2.2 address-family ipv4-unicast +set vrf name Internet protocols bgp neighbor 10.2.2.2 remote-as '64497' +set vrf name Internet protocols bgp neighbor 2001:db8::7 address-family ipv6-unicast +set vrf name Internet protocols bgp neighbor 2001:db8::7 remote-as '64497' +set vrf name Internet table '104' +set vrf name LAN1 protocols bgp address-family ipv4-unicast export vpn +set vrf name LAN1 protocols bgp address-family ipv4-unicast import vpn +set vrf name LAN1 protocols bgp address-family ipv4-unicast rd vpn export '64496:1' +set vrf name LAN1 protocols bgp address-family ipv4-unicast redistribute static +set vrf name LAN1 protocols bgp address-family ipv4-unicast route-target vpn export '64496:1' +set vrf name LAN1 protocols bgp address-family ipv4-unicast route-target vpn import '64496:100 64496:50 64496:2' +set vrf name LAN1 protocols bgp address-family ipv6-unicast export vpn +set vrf name LAN1 protocols bgp address-family ipv6-unicast import vpn +set vrf name LAN1 protocols bgp address-family ipv6-unicast rd vpn export '64496:1' +set vrf name LAN1 protocols bgp address-family ipv6-unicast redistribute static +set vrf name LAN1 protocols bgp address-family ipv6-unicast route-target vpn export '64496:1' +set vrf name LAN1 protocols bgp address-family ipv6-unicast route-target vpn import '64496:100 64496:50 64496:2' +set vrf name LAN1 protocols bgp system-as '64496' +set vrf name LAN1 protocols static route 10.0.0.0/24 next-hop 10.1.1.2 +set vrf name LAN1 protocols static route6 2001:db8:0:1::/64 next-hop 2001:db8::1 +set vrf name LAN1 table '101' +set vrf name LAN2 protocols bgp address-family ipv4-unicast export vpn +set vrf name LAN2 protocols bgp address-family ipv4-unicast import vpn +set vrf name LAN2 protocols bgp address-family ipv4-unicast rd vpn export '64496:2' +set vrf name LAN2 protocols bgp address-family ipv4-unicast redistribute static +set vrf name LAN2 protocols bgp address-family ipv4-unicast route-target vpn export '64496:2' +set vrf name LAN2 protocols bgp address-family ipv4-unicast route-target vpn import '64496:100 64496:50 64496:1' +set vrf name LAN2 protocols bgp address-family ipv6-unicast export vpn +set vrf name LAN2 protocols bgp address-family ipv6-unicast import vpn +set vrf name LAN2 protocols bgp address-family ipv6-unicast rd vpn export '64496:2' +set vrf name LAN2 protocols bgp address-family ipv6-unicast redistribute static +set vrf name LAN2 protocols bgp address-family ipv6-unicast route-target vpn export '64496:2' +set vrf name LAN2 protocols bgp address-family ipv6-unicast route-target vpn import '64496:100 64496:50 64496:1' +set vrf name LAN2 protocols bgp system-as '64496' +set vrf name LAN2 protocols static route 172.16.0.0/24 next-hop 172.16.2.2 +set vrf name LAN2 protocols static route6 2001:db8:0:2::/64 next-hop 2001:db8::3 +set vrf name LAN2 table '102' +set vrf name Management protocols bgp address-family ipv4-unicast export vpn +set vrf name Management protocols bgp address-family ipv4-unicast import vpn +set vrf name Management protocols bgp address-family ipv4-unicast rd vpn export '64496:50' +set vrf name Management protocols bgp address-family ipv4-unicast redistribute static +set vrf name Management protocols bgp address-family ipv4-unicast route-target vpn export '64496:50' +set vrf name Management protocols bgp address-family ipv4-unicast route-target vpn import '64496:1 64496:2' +set vrf name Management protocols bgp address-family ipv6-unicast export vpn +set vrf name Management protocols bgp address-family ipv6-unicast import vpn +set vrf name Management protocols bgp address-family ipv6-unicast rd vpn export '64496:50' +set vrf name Management protocols bgp address-family ipv6-unicast redistribute static +set vrf name Management protocols bgp address-family ipv6-unicast route-target vpn export '64496:50' +set vrf name Management protocols bgp address-family ipv6-unicast route-target vpn import '64496:1 64496:2' +set vrf name Management protocols bgp system-as '64496' +set vrf name Management protocols static route 192.168.0.0/24 next-hop 192.168.3.2 +set vrf name Management protocols static route6 2001:db8:0:3::/64 next-hop 2001:db8::5 +set vrf name Management table '103' +``` + +- LAN1 + +``` none +set interfaces dummy dum0 address '10.0.0.1/24' +set interfaces dummy dum0 address '2001:db8:0:1::1/64' +set interfaces ethernet eth0 address '10.1.1.2/30' +set interfaces ethernet eth0 address '2001:db8::1/127' +set protocols static route 0.0.0.0/0 next-hop 10.1.1.1 +set protocols static route6 ::/0 next-hop 2001:db8::1 +``` + +- LAN2 + +``` none +set interfaces dummy dum0 address '172.16.0.1/24' +set interfaces dummy dum0 address '2001:db8:0:2::1/64' +set interfaces ethernet eth0 hw-id '50:00:00:03:00:00' +set interfaces ethernet eth1 address '172.16.2.2/30' +set interfaces ethernet eth1 address '2001:db8::3/127' +set protocols static route 0.0.0.0/0 next-hop 172.16.2.1 +set protocols static route6 ::/0 next-hop 2001:db8::2 +``` + +- Management + +``` none +set interfaces dummy dum0 address '192.168.0.1/24' +set interfaces dummy dum0 address '2001:db8:0:3::1/64' +set interfaces ethernet eth2 address '192.168.3.2/30' +set interfaces ethernet eth2 address '2001:db8::5/127' +set protocols static route 0.0.0.0/0 next-hop 192.168.3.1 +set protocols static route6 ::/0 next-hop 2001:db8::4 +``` + +- ISP + +``` none +set interfaces dummy dum0 address '192.0.2.1/24' +set interfaces dummy dum0 address '2001:db8:1::1/48' +set interfaces dummy dum1 address '198.51.100.1/24' +set interfaces dummy dum1 address '2001:db8:2::1/48' +set interfaces dummy dum2 address '203.0.113.1/24' +set interfaces dummy dum2 address '2001:db8:3::1/48' +set interfaces ethernet eth3 address '10.2.2.2/30' +set interfaces ethernet eth3 address '2001:db8::7/127' +set protocols bgp address-family ipv4-unicast redistribute connected +set protocols bgp address-family ipv6-unicast redistribute connected +set protocols bgp system-as '64497' +set protocols bgp neighbor 10.2.2.1 address-family ipv4-unicast default-originate +set protocols bgp neighbor 10.2.2.1 remote-as '64496' +set protocols bgp neighbor 2001:db8::6 address-family ipv6-unicast default-originate +set protocols bgp neighbor 2001:db8::6 remote-as '64496' +set protocols static route 0.0.0.0/0 next-hop 10.2.2.1 +set protocols static route6 ::/0 next-hop 2001:db8::6 +``` + +## Appendix-B + +### Route-Filtering + +When importing routes using MP-BGP it is possible to filter a subset of them +before are injected in the BGP table. One of the most common case is to use a +route-map with an prefix-list. + +- Configuration + +We create a prefix-list first and add all the routes we need to. + +``` none +# set both ipv4 and ipv6 policies + +set policy prefix-list LAN2-Internet rule 1 action 'permit' +set policy prefix-list LAN2-Internet rule 1 le '24' +set policy prefix-list LAN2-Internet rule 1 prefix '198.51.0.0/16' +set policy prefix-list LAN2-Internet rule 2 action 'permit' +set policy prefix-list LAN2-Internet rule 2 prefix '192.0.2.0/24' +set policy prefix-list LAN2-Internet rule 3 action 'permit' +set policy prefix-list LAN2-Internet rule 3 prefix '192.168.0.0/24' +set policy prefix-list LAN2-Internet rule 4 action 'permit' +set policy prefix-list LAN2-Internet rule 4 prefix '10.0.0.0/24' + +set policy prefix-list6 LAN2-Internet-v6 rule 1 action 'permit' +set policy prefix-list6 LAN2-Internet-v6 rule 1 prefix '2001:db8:1::/48' +set policy prefix-list6 LAN2-Internet-v6 rule 2 action 'permit' +set policy prefix-list6 LAN2-Internet-v6 rule 2 prefix '2001:db8:2::/48' +set policy prefix-list6 LAN2-Internet-v6 rule 3 action 'permit' +set policy prefix-list6 LAN2-Internet-v6 rule 3 prefix '2001:db8:0:3::/64' +set policy prefix-list6 LAN2-Internet-v6 rule 4 action 'permit' +set policy prefix-list6 LAN2-Internet-v6 rule 4 prefix '2001:db8:0:1::/64' +``` + +Then add a route-map and reference to above prefix. Consider that the actions +taken inside the prefix will MATCH the routes that will be affected by the +actions inside the rules of the route-map. + +``` none +set policy route-map LAN2-Internet rule 1 action 'permit' +set policy route-map LAN2-Internet rule 1 match ip address prefix-list 'LAN2-Internet' + +set policy route-map LAN2-Internet-v6 rule 1 action 'permit' +set policy route-map LAN2-Internet-v6 rule 1 match ipv6 address prefix-list 'LAN2-Internet-v6' +``` + +We are using a "white list" approach by allowing only what is necessary. In case +that need to implement a "black list" approach then you will need to change the +action in the route-map for a deny BUT you need to add a rule that permits the +rest due to the implicit deny in the route-map. + +Then we need to attach the policy to the BGP process. This needs to be under +the import statement in the vrf we need to filter. + +``` none +set vrf name LAN2 protocols bgp address-family ipv4-unicast route-map vpn import 'LAN2-Internet' +set vrf name LAN2 protocols bgp address-family ipv6-unicast route-map vpn import 'LAN2-Internet-v6' +``` + +- Verification + +``` none +# show ip route vrf LAN2 + +B>* 10.0.0.0/24 [20/0] via 10.1.1.2, eth0 (vrf LAN1), weight 1, 00:45:28 +S>* 172.16.0.0/24 [1/0] via 172.16.2.2, eth1, weight 1, 00:45:32 +C>* 172.16.2.0/30 is directly connected, eth1, 00:45:39 +B>* 192.0.2.0/24 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:45:24 +B>* 192.168.0.0/24 [20/0] via 192.168.3.2, eth2 (vrf Managment), weight 1, 00:45:27 +B>* 198.51.100.0/24 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:45:24 + +# show ipv6 route vrf LAN2 + +C>* 2001:db8::2/127 is directly connected, eth1, 00:46:26 +B>* 2001:db8:0:1::/64 [20/0] via 2001:db8::1, eth0 (vrf LAN1), weight 1, 00:46:17 +S>* 2001:db8:0:2::/64 [1/0] via 2001:db8::3, eth1, weight 1, 00:46:21 +B>* 2001:db8:0:3::/64 [20/0] via 2001:db8::5, eth2 (vrf Managment), weight 1, 00:46:16 +B>* 2001:db8:1::/48 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:46:13 +B>* 2001:db8:2::/48 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:46:13 +C>* fe80::/64 is directly connected, eth1, 00:46:27 +``` + +As we can see even if both VRF LAN1 and LAN2 has the same import RTs we are able +to select which routes are effectively imported and installed. diff --git a/docs/configexamples/md-ipsec-cisco-policy-based.md b/docs/configexamples/md-ipsec-cisco-policy-based.md new file mode 100644 index 00000000..7410a43f --- /dev/null +++ b/docs/configexamples/md-ipsec-cisco-policy-based.md @@ -0,0 +1,423 @@ +lastproofread +2025-06-26 + +# Policy-based Site-to-Site VPN IPsec between VyOS and Cisco + +This document is to describe a basic setup using policy-based +site-to-site VPN IPsec. In this example we use VyOS 1.5 and +Cisco IOS. Cisco initiates IPsec connection only if interesting +traffic present. For stable work we recommend configuring an +initiator role on VyOS side. + +## Network Topology + +<img src="/_static/images/cisco-vpn-ipsec.webp" class="align-center" alt="Network Topology Diagram" /> + +## Prerequirements + +**VyOS:** + +<table style="width:38%;"> +<colgroup> +<col style="width: 13%" /> +<col style="width: 23%" /> +</colgroup> +<tbody> +<tr> +<td>WAN IP</td> +<td><blockquote> +<p>10.0.1.2/30</p> +</blockquote></td> +</tr> +<tr> +<td>LAN1 IP</td> +<td>192.168.0.1/24</td> +</tr> +<tr> +<td>LAN2 IP</td> +<td>192.168.1.1/24</td> +</tr> +</tbody> +</table> + +**Cisco:** + +<table style="width:39%;"> +<colgroup> +<col style="width: 13%" /> +<col style="width: 25%" /> +</colgroup> +<tbody> +<tr> +<td>WAN IP</td> +<td>10.0.2.2/30</td> +</tr> +<tr> +<td>LAN1 IP</td> +<td>192.168.10.1/24</td> +</tr> +<tr> +<td>LAN2 IP</td> +<td>192.168.11.1/24</td> +</tr> +</tbody> +</table> + +**IKE parameters:** + +<table style="width:42%;"> +<colgroup> +<col style="width: 27%" /> +<col style="width: 13%" /> +</colgroup> +<tbody> +<tr> +<td>Encryption</td> +<td>AES-256</td> +</tr> +<tr> +<td>HASH</td> +<td>SHA-1</td> +</tr> +<tr> +<td>Diff-Helman Group</td> +<td>14</td> +</tr> +<tr> +<td>Life-Time</td> +<td>28800</td> +</tr> +<tr> +<td>IKE Version</td> +<td>2</td> +</tr> +</tbody> +</table> + +**IPsec parameters:** + +<table style="width:32%;"> +<colgroup> +<col style="width: 18%" /> +<col style="width: 13%" /> +</colgroup> +<tbody> +<tr> +<td>Encryption</td> +<td>AES-256</td> +</tr> +<tr> +<td>HASH</td> +<td>SHA-256</td> +</tr> +<tr> +<td>Life-Time</td> +<td>3600</td> +</tr> +<tr> +<td>PFS</td> +<td>disable</td> +</tr> +</tbody> +</table> + +**Traffic Selectors** +192.168.0.0/24 \<==\> 192.168.10.0/24 + +192.168.1.0/24 \<==\> 192.168.11.0/24 + +**Hosts configuration** + +<table style="width:33%;"> +<colgroup> +<col style="width: 12%" /> +<col style="width: 20%" /> +</colgroup> +<tbody> +<tr> +<td>PC1 IP</td> +<td>192.168.0.2</td> +</tr> +<tr> +<td>PC2 IP</td> +<td>192.168.1.2</td> +</tr> +<tr> +<td>PC3 IP</td> +<td>192.168.10.2</td> +</tr> +<tr> +<td>PC4 IP</td> +<td>192.168.11.2</td> +</tr> +</tbody> +</table> + +## Configuration + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Pfs is disabled in Cisco by default. + +</div> + +### VyOS + +``` none +set interfaces ethernet eth0 address '10.0.1.2/30' +set interfaces ethernet eth1 address '192.168.0.1/24' +set interfaces ethernet eth2 address '192.168.1.1/24' +set protocols static route 0.0.0.0/0 next-hop 10.0.1.1 +set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' +set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' +set vpn ipsec authentication psk AUTH-PSK secret 'dGVzdA==' +set vpn ipsec authentication psk AUTH-PSK secret-type 'base64' +set vpn ipsec esp-group ESP-GROUP lifetime '3600' +set vpn ipsec esp-group ESP-GROUP pfs 'disable' +set vpn ipsec esp-group ESP-GROUP proposal 10 encryption 'aes256' +set vpn ipsec esp-group ESP-GROUP proposal 10 hash 'sha256' +set vpn ipsec ike-group IKE-GROUP close-action 'start' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'restart' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '10' +set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev2' +set vpn ipsec ike-group IKE-GROUP lifetime '28800' +set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' +set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256' +set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' +set vpn ipsec site-to-site peer CISCO authentication local-id '10.0.1.2' +set vpn ipsec site-to-site peer CISCO authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer CISCO authentication remote-id '10.0.2.2' +set vpn ipsec site-to-site peer CISCO connection-type 'initiate' +set vpn ipsec site-to-site peer CISCO default-esp-group 'ESP-GROUP' +set vpn ipsec site-to-site peer CISCO ike-group 'IKE-GROUP' +set vpn ipsec site-to-site peer CISCO local-address '10.0.1.2' +set vpn ipsec site-to-site peer CISCO remote-address '10.0.2.2' +set vpn ipsec site-to-site peer CISCO tunnel 1 local prefix '192.168.0.0/24' +set vpn ipsec site-to-site peer CISCO tunnel 1 remote prefix '192.168.10.0/24' +set vpn ipsec site-to-site peer CISCO tunnel 2 local prefix '192.168.1.0/24' +set vpn ipsec site-to-site peer CISCO tunnel 2 remote prefix '192.168.11.0/24' +``` + +### Cisco + +``` none +crypto ikev2 proposal aes-cbc-256-proposal + encryption aes-cbc-256 + integrity sha1 + group 14 +! +crypto ikev2 policy policy1 + match address local 10.0.2.2 + proposal aes-cbc-256-proposal +! +crypto ikev2 keyring keys + peer VyOS + address 10.0.1.2 + pre-shared-key local test + pre-shared-key remote test +! +crypto ikev2 profile IKEv2-profile + match identity remote address 10.0.1.2 255.255.255.255 + authentication remote pre-share + authentication local pre-share + keyring local keys + lifetime 28800 +! +crypto ipsec transform-set TS esp-aes 256 esp-sha256-hmac + mode tunnel +! +crypto map IPSEC-map 10 ipsec-isakmp + set peer 10.0.1.2 + set security-association lifetime seconds 3600 + set transform-set TS + set ikev2-profile IKEv2-profile + match address cryptoacl +! +interface GigabitEthernet0/0 + ip address 10.0.2.2 255.255.255.252 + crypto map IPSEC-map +! +interface GigabitEthernet0/1 + ip address 192.168.10.1 255.255.255.0 +! +interface GigabitEthernet0/2 + ip address 192.168.11.1 255.255.255.0 +! +ip route 0.0.0.0 0.0.0.0 10.0.2.1 +! +ip access-list extended cryptoacl + permit ip 192.168.10.0 0.0.0.255 192.168.0.0 0.0.0.255 + permit ip 192.168.11.0 0.0.0.255 192.168.1.0 0.0.0.255 +``` + +## Monitoring + +### Monitoring on VyOS side + +IKE SAs: + +``` none +vyos@vyos:~$ show vpn ike sa +Peer ID / IP Local ID / IP +------------ ------------- +10.0.2.2 10.0.2.2 10.0.1.2 10.0.1.2 + + State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time + ----- ------ ------- ---- --------- ----- ------ ------ + up IKEv2 AES_CBC_256 HMAC_SHA1_96 MODP_2048 no 304 26528 +``` + +IPsec SAs: + +``` none +vyos@vyos:~$ show vpn ipsec sa +Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal +-------------- ------- -------- -------------- ---------------- ---------------- ----------- ----------------------------- +CISCO-tunnel-1 up 6m6s 0B/0B 0/0 10.0.2.2 10.0.2.2 AES_CBC_256/HMAC_SHA2_256_128 +CISCO-tunnel-2 up 6m6s 0B/0B 0/0 10.0.2.2 10.0.2.2 AES_CBC_256/HMAC_SHA2_256_128 +``` + +### Monitoring on Cisco side + +IKE SAs: + +``` none +Cisco#show crypto ikev2 sa + IPv4 Crypto IKEv2 SA + +Tunnel-id Local Remote fvrf/ivrf Status +1 10.0.2.2/4500 10.0.1.2/4500 none/none READY + Encr: AES-CBC, keysize: 256, PRF: SHA1, Hash: SHA96, DH Grp:14, Auth sign: PSK, Auth verify: PSK + Life/Active Time: 28800/471 sec + + IPv6 Crypto IKEv2 SA +``` + +IPsec SAs: + +``` none +Cisco#show crypto ipsec sa + +interface: GigabitEthernet0/0 + Crypto map tag: IPSEC-map, local addr 10.0.2.2 + + protected vrf: (none) + local ident (addr/mask/prot/port): (192.168.11.0/255.255.255.0/0/0) + remote ident (addr/mask/prot/port): (192.168.1.0/255.255.255.0/0/0) + current_peer 10.0.1.2 port 4500 + PERMIT, flags={origin_is_acl,} + #pkts encaps: 0, #pkts encrypt: 0, #pkts digest: 0 + #pkts decaps: 0, #pkts decrypt: 0, #pkts verify: 0 + #pkts compressed: 0, #pkts decompressed: 0 + #pkts not compressed: 0, #pkts compr. failed: 0 + #pkts not decompressed: 0, #pkts decompress failed: 0 + #send errors 0, #recv errors 0 + + local crypto endpt.: 10.0.2.2, remote crypto endpt.: 10.0.1.2 + plaintext mtu 1438, path mtu 1500, ip mtu 1500, ip mtu idb GigabitEthernet0/0 + current outbound spi: 0xC81F83DA(3357508570) + PFS (Y/N): N, DH group: none + + inbound esp sas: + spi: 0x8C63C51E(2355348766) + transform: esp-256-aes esp-sha256-hmac , + in use settings ={Tunnel, } + conn id: 23, flow_id: SW:23, sibling_flags 80000040, crypto map: IPSEC-map + sa timing: remaining key lifetime (k/sec): (4231729/3585) + IV size: 16 bytes + replay detection support: Y + Status: ACTIVE(ACTIVE) + + inbound ah sas: + + inbound pcp sas: + + outbound esp sas: + spi: 0xC81F83DA(3357508570) + transform: esp-256-aes esp-sha256-hmac , + in use settings ={Tunnel, } + conn id: 24, flow_id: SW:24, sibling_flags 80000040, crypto map: IPSEC-map + sa timing: remaining key lifetime (k/sec): (4231729/3585) + IV size: 16 bytes + replay detection support: Y + Status: ACTIVE(ACTIVE) + + outbound ah sas: + + outbound pcp sas: + + protected vrf: (none) + local ident (addr/mask/prot/port): (192.168.10.0/255.255.255.0/0/0) + remote ident (addr/mask/prot/port): (192.168.0.0/255.255.255.0/0/0) + current_peer 10.0.1.2 port 4500 + PERMIT, flags={origin_is_acl,} + #pkts encaps: 0, #pkts encrypt: 0, #pkts digest: 0 + #pkts decaps: 0, #pkts decrypt: 0, #pkts verify: 0 + #pkts compressed: 0, #pkts decompressed: 0 + #pkts not compressed: 0, #pkts compr. failed: 0 + #pkts not decompressed: 0, #pkts decompress failed: 0 + #send errors 0, #recv errors 0 + + local crypto endpt.: 10.0.2.2, remote crypto endpt.: 10.0.1.2 + plaintext mtu 1438, path mtu 1500, ip mtu 1500, ip mtu idb GigabitEthernet0/0 + current outbound spi: 0xC40C7A20(3289152032) + PFS (Y/N): N, DH group: none + + inbound esp sas: + spi: 0x2948B6CB(692631243) + transform: esp-256-aes esp-sha256-hmac , + in use settings ={Tunnel, } + conn id: 21, flow_id: SW:21, sibling_flags 80000040, crypto map: IPSEC-map + sa timing: remaining key lifetime (k/sec): (4194891/3581) + IV size: 16 bytes + replay detection support: Y + Status: ACTIVE(ACTIVE) + + inbound ah sas: + + inbound pcp sas: + + outbound esp sas: + spi: 0xC40C7A20(3289152032) + transform: esp-256-aes esp-sha256-hmac , + in use settings ={Tunnel, } + conn id: 22, flow_id: SW:22, sibling_flags 80000040, crypto map: IPSEC-map + sa timing: remaining key lifetime (k/sec): (4194891/3581) + IV size: 16 bytes + replay detection support: Y + Status: ACTIVE(ACTIVE) + + outbound ah sas: + + outbound pcp sas: +``` + +### Checking Connectivity + +ICMP packets from PC1 to PC3. + +``` none +PC1> ping 192.168.10.2 + +84 bytes from 192.168.10.2 icmp_seq=1 ttl=62 time=8.479 ms +84 bytes from 192.168.10.2 icmp_seq=2 ttl=62 time=3.344 ms +84 bytes from 192.168.10.2 icmp_seq=3 ttl=62 time=3.139 ms +84 bytes from 192.168.10.2 icmp_seq=4 ttl=62 time=3.176 ms +84 bytes from 192.168.10.2 icmp_seq=5 ttl=62 time=3.978 ms +``` + +ICMP packets from PC2 to PC4. + +``` none +PC2> ping 192.168.11.2 + +84 bytes from 192.168.11.2 icmp_seq=1 ttl=62 time=9.687 ms +84 bytes from 192.168.11.2 icmp_seq=2 ttl=62 time=3.286 ms +84 bytes from 192.168.11.2 icmp_seq=3 ttl=62 time=2.972 ms +``` diff --git a/docs/configexamples/md-ipsec-cisco-route-based.md b/docs/configexamples/md-ipsec-cisco-route-based.md new file mode 100644 index 00000000..181a9d56 --- /dev/null +++ b/docs/configexamples/md-ipsec-cisco-route-based.md @@ -0,0 +1,469 @@ +lastproofread +2025-06-26 + +# Route-based Site-to-Site VPN IPsec between VyOS and Cisco + +This document is to describe a basic setup using route-based +site-to-site VPN IPsec. In this example we use VyOS 1.5 and +Cisco IOS. Cisco initiates IPsec connection only if interesting +traffic present. For stable work we recommend configuring an +initiator role on VyOS side. OSPF is selected as routing protocol +inside the tunnel. + +## Network Topology + +<img src="/_static/images/cisco-vpn-ipsec.webp" class="align-center" alt="Network Topology Diagram" /> + +## Prerequirements + +**VyOS:** + +<table style="width:38%;"> +<colgroup> +<col style="width: 13%" /> +<col style="width: 23%" /> +</colgroup> +<tbody> +<tr> +<td>WAN IP</td> +<td><blockquote> +<p>10.0.1.2/30</p> +</blockquote></td> +</tr> +<tr> +<td>LAN1 IP</td> +<td>192.168.0.1/24</td> +</tr> +<tr> +<td>LAN2 IP</td> +<td>192.168.1.1/24</td> +</tr> +</tbody> +</table> + +**Cisco:** + +<table style="width:39%;"> +<colgroup> +<col style="width: 13%" /> +<col style="width: 25%" /> +</colgroup> +<tbody> +<tr> +<td>WAN IP</td> +<td>10.0.2.2/30</td> +</tr> +<tr> +<td>LAN1 IP</td> +<td>192.168.10.1/24</td> +</tr> +<tr> +<td>LAN2 IP</td> +<td>192.168.11.1/24</td> +</tr> +</tbody> +</table> + +**IKE parameters:** + +<table style="width:42%;"> +<colgroup> +<col style="width: 27%" /> +<col style="width: 13%" /> +</colgroup> +<tbody> +<tr> +<td>Encryption</td> +<td>AES-128</td> +</tr> +<tr> +<td>HASH</td> +<td>SHA-1</td> +</tr> +<tr> +<td>Diff-Helman Group</td> +<td>14</td> +</tr> +<tr> +<td>Life-Time</td> +<td>28800</td> +</tr> +<tr> +<td>IKE Version</td> +<td>1</td> +</tr> +</tbody> +</table> + +**IPsec parameters:** + +<table style="width:32%;"> +<colgroup> +<col style="width: 18%" /> +<col style="width: 13%" /> +</colgroup> +<tbody> +<tr> +<td>Encryption</td> +<td>AES-256</td> +</tr> +<tr> +<td>HASH</td> +<td>SHA-256</td> +</tr> +<tr> +<td>Life-Time</td> +<td>3600</td> +</tr> +<tr> +<td>PFS</td> +<td>disable</td> +</tr> +</tbody> +</table> + +**Hosts configuration** + +<table style="width:33%;"> +<colgroup> +<col style="width: 12%" /> +<col style="width: 20%" /> +</colgroup> +<tbody> +<tr> +<td>PC1 IP</td> +<td>192.168.0.2</td> +</tr> +<tr> +<td>PC2 IP</td> +<td>192.168.1.2</td> +</tr> +<tr> +<td>PC3 IP</td> +<td>192.168.10.2</td> +</tr> +<tr> +<td>PC4 IP</td> +<td>192.168.11.2</td> +</tr> +</tbody> +</table> + +## Configuration + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Pfs is disabled in Cisco by default. + +</div> + +### VyOS + +``` none +set interfaces ethernet eth0 address '10.0.1.2/30' +set interfaces ethernet eth1 address '192.168.0.1/24' +set interfaces ethernet eth2 address '192.168.1.1/24' +set interfaces vti vti1 address '10.100.100.1/30' +set interfaces vti vti1 mtu '1438' +set protocols ospf area 0 network '10.100.100.0/30' +set protocols ospf area 0 network '192.168.0.0/24' +set protocols ospf area 0 network '192.168.1.0/24' +set protocols ospf interface eth1 passive +set protocols ospf interface eth2 passive +set protocols ospf interface vti1 network 'point-to-point' +set protocols ospf parameters router-id '2.2.2.2' +set protocols static route 0.0.0.0/0 next-hop 10.0.1.1 +set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' +set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' +set vpn ipsec authentication psk AUTH-PSK secret 'dGVzdA==' +set vpn ipsec authentication psk AUTH-PSK secret-type 'base64' +set vpn ipsec esp-group ESP-GROUP lifetime '3600' +set vpn ipsec esp-group ESP-GROUP pfs 'disable' +set vpn ipsec esp-group ESP-GROUP proposal 10 encryption 'aes256' +set vpn ipsec esp-group ESP-GROUP proposal 10 hash 'sha256' +set vpn ipsec ike-group IKE-GROUP close-action 'start' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'restart' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '10' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection timeout '30' +set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev1' +set vpn ipsec ike-group IKE-GROUP lifetime '28800' +set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' +set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes128' +set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' +set vpn ipsec options disable-route-autoinstall +set vpn ipsec site-to-site peer CISCO authentication local-id '10.0.1.2' +set vpn ipsec site-to-site peer CISCO authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer CISCO authentication remote-id '10.0.2.2' +set vpn ipsec site-to-site peer CISCO connection-type 'initiate' +set vpn ipsec site-to-site peer CISCO default-esp-group 'ESP-GROUP' +set vpn ipsec site-to-site peer CISCO ike-group 'IKE-GROUP' +set vpn ipsec site-to-site peer CISCO local-address '10.0.1.2' +set vpn ipsec site-to-site peer CISCO remote-address '10.0.2.2' +set vpn ipsec site-to-site peer CISCO vti bind 'vti1' +``` + +### Cisco + +``` none +crypto isakmp policy 10 + encr aes + authentication pre-share + group 14 + lifetime 28800 +crypto isakmp key test address 10.0.1.2 +! +! +crypto ipsec transform-set TS esp-aes 256 esp-sha256-hmac + mode transport +! +crypto ipsec profile IPsec-profile + set transform-set TS +! +! +! +! +! +! +! +interface Loopback0 + ip address 1.1.1.1 255.255.255.255 +! +interface Tunnel10 + ip address 10.100.100.2 255.255.255.252 + ip ospf network point-to-point + tunnel source GigabitEthernet0/0 + tunnel mode ipsec ipv4 + tunnel destination 10.0.1.2 + tunnel protection ipsec profile IPsec-profile +! +interface GigabitEthernet0/0 + ip address 10.0.2.2 255.255.255.252 + duplex auto + speed auto + media-type rj45 +! +interface GigabitEthernet0/1 + ip address 192.168.10.1 255.255.255.0 + duplex auto + speed auto + media-type rj45 +! +interface GigabitEthernet0/2 + ip address 192.168.11.1 255.255.255.0 + duplex auto + speed auto + media-type rj45 +! +router ospf 1 + router-id 1.1.1.1 + passive-interface GigabitEthernet0/1 + passive-interface GigabitEthernet0/2 + network 10.100.100.0 0.0.0.3 area 0 + network 192.168.10.0 0.0.0.255 area 0 + network 192.168.11.0 0.0.0.255 area 0 +! +ip route 0.0.0.0 0.0.0.0 10.0.2.1 +``` + +## Monitoring + +### Monitoring on VyOS side + +IKE SAs: + +``` none +vyos@vyos:~$ show vpn ike sa +Peer ID / IP Local ID / IP +------------ ------------- +10.0.2.2 10.0.2.2 10.0.1.2 10.0.1.2 + + State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time + ----- ------ ------- ---- --------- ----- ------ ------ + up IKEv1 AES_CBC_128 HMAC_SHA1_96 MODP_2048 no 8175 18439 +``` + +IPsec SAs: + +``` none +vyos@vyos:~$ show vpn ipsec sa +Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal +------------ ------- -------- -------------- ---------------- ---------------- ----------- ----------------------------- +CISCO-vti up 34m59s 17K/14K 224/213 10.0.2.2 10.0.2.2 AES_CBC_256/HMAC_SHA2_256_128 +``` + +OSPF Neighbor Status: + +``` none +vyos@vyos:~$ show ip ospf neighbor + +Neighbor ID Pri State Up Time Dead Time Address Interface RXmtL RqstL DBsmL +1.1.1.1 1 Full/- 1h29m37s 39.317s 10.100.100.2 vti1:10.100.100.1 0 0 0 +``` + +Routing Table: + +``` none +vyos@vyos:~$ show ip route +Codes: K - kernel route, C - connected, L - local, S - static, + R - RIP, O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, t - Table-Direct, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + + +S>* 0.0.0.0/0 [1/0] via 10.0.1.1, eth0, weight 1, 00:07:54 +C>* 10.0.1.0/30 is directly connected, eth0, weight 1, 00:07:59 +L>* 10.0.1.2/32 is directly connected, eth0, weight 1, 00:07:59 +O 10.100.100.0/30 [110/1] is directly connected, vti1, weight 1, 00:07:50 +C>* 10.100.100.0/30 is directly connected, vti1, weight 1, 00:07:50 +L>* 10.100.100.1/32 is directly connected, vti1, weight 1, 00:07:50 +O 192.168.0.0/24 [110/1] is directly connected, eth1, weight 1, 00:07:54 +C>* 192.168.0.0/24 is directly connected, eth1, weight 1, 00:07:59 +L>* 192.168.0.1/32 is directly connected, eth1, weight 1, 00:07:59 +O 192.168.1.0/24 [110/1] is directly connected, eth2, weight 1, 00:07:54 +C>* 192.168.1.0/24 is directly connected, eth2, weight 1, 00:07:59 +L>* 192.168.1.1/32 is directly connected, eth2, weight 1, 00:07:59 +O>* 192.168.10.0/24 [110/2] via 10.100.100.2, vti1, weight 1, 00:07:34 +O>* 192.168.11.0/24 [110/2] via 10.100.100.2, vti1, weight 1, 00:07:34 +``` + +### Monitoring on Cisco side + +IKE SAs: + +``` none +Cisco#show crypto isakmp sa +IPv4 Crypto ISAKMP SA +dst src state conn-id status +10.0.1.2 10.0.2.2 QM_IDLE 1002 ACTIVE + +IPv6 Crypto ISAKMP SA +``` + +IPsec SAs: + +``` none +Cisco#show crypto ipsec sa + +interface: Tunnel10 + Crypto map tag: Tunnel10-head-0, local addr 10.0.2.2 + + protected vrf: (none) + local ident (addr/mask/prot/port): (0.0.0.0/0.0.0.0/0/0) + remote ident (addr/mask/prot/port): (0.0.0.0/0.0.0.0/0/0) + current_peer 10.0.1.2 port 500 + PERMIT, flags={origin_is_acl,} + #pkts encaps: 1295, #pkts encrypt: 1295, #pkts digest: 1295 + #pkts decaps: 1238, #pkts decrypt: 1238, #pkts verify: 1238 + #pkts compressed: 0, #pkts decompressed: 0 + #pkts not compressed: 0, #pkts compr. failed: 0 + #pkts not decompressed: 0, #pkts decompress failed: 0 + #send errors 0, #recv errors 0 + + local crypto endpt.: 10.0.2.2, remote crypto endpt.: 10.0.1.2 + plaintext mtu 1438, path mtu 1500, ip mtu 1500, ip mtu idb GigabitEthernet0/0 + current outbound spi: 0xC3E9B307(3286872839) + PFS (Y/N): N, DH group: none + + inbound esp sas: + spi: 0x2740C328(658555688) + transform: esp-256-aes esp-sha256-hmac , + in use settings ={Tunnel, } + conn id: 7, flow_id: SW:7, sibling_flags 80000040, crypto map: Tunnel10-head-0 + sa timing: remaining key lifetime (k/sec): (4173824/1401) + IV size: 16 bytes + replay detection support: Y + Status: ACTIVE(ACTIVE) + + inbound ah sas: + + inbound pcp sas: + + outbound esp sas: + spi: 0xC3E9B307(3286872839) + transform: esp-256-aes esp-sha256-hmac , + in use settings ={Tunnel, } + conn id: 8, flow_id: SW:8, sibling_flags 80000040, crypto map: Tunnel10-head-0 + sa timing: remaining key lifetime (k/sec): (4173819/1401) + IV size: 16 bytes + replay detection support: Y + Status: ACTIVE(ACTIVE) + + outbound ah sas: + + outbound pcp sas: +``` + +OSPF Neighbor Status: + +``` none +Cisco# show ip ospf neighbor + +Neighbor ID Pri State Dead Time Address Interface +2.2.2.2 0 FULL/ - 00:00:35 10.100.100.1 Tunnel10 +``` + +Routing Table: + +``` none +Cisco#show ip route +Codes: L - local, C - connected, S - static, R - RIP, M - mobile, B - BGP + D - EIGRP, EX - EIGRP external, O - OSPF, IA - OSPF inter area + N1 - OSPF NSSA external type 1, N2 - OSPF NSSA external type 2 + E1 - OSPF external type 1, E2 - OSPF external type 2 + i - IS-IS, su - IS-IS summary, L1 - IS-IS level-1, L2 - IS-IS level-2 + ia - IS-IS inter area, * - candidate default, U - per-user static route + o - ODR, P - periodic downloaded static route, H - NHRP, l - LISP + a - application route + + - replicated route, % - next hop override, p - overrides from PfR + +Gateway of last resort is 10.0.2.1 to network 0.0.0.0 + +S* 0.0.0.0/0 [1/0] via 10.0.2.1 + 1.0.0.0/32 is subnetted, 1 subnets +C 1.1.1.1 is directly connected, Loopback0 + 10.0.0.0/8 is variably subnetted, 4 subnets, 2 masks +C 10.0.2.0/30 is directly connected, GigabitEthernet0/0 +L 10.0.2.2/32 is directly connected, GigabitEthernet0/0 +C 10.100.100.0/30 is directly connected, Tunnel10 +L 10.100.100.2/32 is directly connected, Tunnel10 +O 192.168.0.0/24 [110/1001] via 10.100.100.1, 00:09:36, Tunnel10 +O 192.168.1.0/24 [110/1001] via 10.100.100.1, 00:09:36, Tunnel10 + 192.168.10.0/24 is variably subnetted, 2 subnets, 2 masks +C 192.168.10.0/24 is directly connected, GigabitEthernet0/1 +L 192.168.10.1/32 is directly connected, GigabitEthernet0/1 + 192.168.11.0/24 is variably subnetted, 2 subnets, 2 masks +C 192.168.11.0/24 is directly connected, GigabitEthernet0/2 +L 192.168.11.1/32 is directly connected, GigabitEthernet0/2 +``` + +### Checking Connectivity + +ICMP packets from PC1 to PC3. + +``` none +PC1> ping 192.168.10.2 + +84 bytes from 192.168.10.2 icmp_seq=1 ttl=62 time=8.479 ms +84 bytes from 192.168.10.2 icmp_seq=2 ttl=62 time=3.344 ms +84 bytes from 192.168.10.2 icmp_seq=3 ttl=62 time=3.139 ms +84 bytes from 192.168.10.2 icmp_seq=4 ttl=62 time=3.176 ms +84 bytes from 192.168.10.2 icmp_seq=5 ttl=62 time=3.978 ms +``` + +ICMP packets from PC2 to PC4. + +``` none +PC2> ping 192.168.11.2 + +84 bytes from 192.168.11.2 icmp_seq=1 ttl=62 time=9.687 ms +84 bytes from 192.168.11.2 icmp_seq=2 ttl=62 time=3.286 ms +84 bytes from 192.168.11.2 icmp_seq=3 ttl=62 time=2.972 ms +``` diff --git a/docs/configexamples/md-ipsec-pa-route-based.md b/docs/configexamples/md-ipsec-pa-route-based.md new file mode 100644 index 00000000..191d59f9 --- /dev/null +++ b/docs/configexamples/md-ipsec-pa-route-based.md @@ -0,0 +1,462 @@ +lastproofread +2025-06-26 + +# Route-based Site-to-Site VPN IPsec between VyOS and Palo Alto + +This document is to describe a basic setup using route-based +site-to-site VPN IPsec. In this example we use VyOS 1.5 and +PA 11.0.0. OSPF is selected as routing protocol inside the +tunnel. + +Since this example focuses on IPsec configuration it does not +include firewall configuration. + +## Network Topology + +<img src="/_static/images/ipsec-vyos-pa.webp" class="align-center" alt="Network Topology Diagram" /> + +## Prerequirements + +**VyOS:** + +<table style="width:38%;"> +<colgroup> +<col style="width: 13%" /> +<col style="width: 23%" /> +</colgroup> +<tbody> +<tr> +<td>WAN IP</td> +<td><blockquote> +<p>10.0.1.2/30</p> +</blockquote></td> +</tr> +<tr> +<td>LAN1 IP</td> +<td>192.168.0.1/24</td> +</tr> +<tr> +<td>LAN2 IP</td> +<td>192.168.1.1/24</td> +</tr> +</tbody> +</table> + +**Palo Alto:** + +<table style="width:39%;"> +<colgroup> +<col style="width: 13%" /> +<col style="width: 25%" /> +</colgroup> +<tbody> +<tr> +<td>WAN IP</td> +<td>10.0.2.2/30</td> +</tr> +<tr> +<td>LAN1 IP</td> +<td>192.168.10.1/24</td> +</tr> +<tr> +<td>LAN2 IP</td> +<td>192.168.11.1/24</td> +</tr> +</tbody> +</table> + +**IKE parameters:** + +<table style="width:42%;"> +<colgroup> +<col style="width: 27%" /> +<col style="width: 13%" /> +</colgroup> +<tbody> +<tr> +<td>Encryption</td> +<td>AES-128</td> +</tr> +<tr> +<td>HASH</td> +<td>SHA-1</td> +</tr> +<tr> +<td>Diff-Helman Group</td> +<td>14</td> +</tr> +<tr> +<td>Life-Time</td> +<td>28800</td> +</tr> +<tr> +<td>IKE Version</td> +<td>1</td> +</tr> +</tbody> +</table> + +**IPsec parameters:** + +<table style="width:32%;"> +<colgroup> +<col style="width: 18%" /> +<col style="width: 13%" /> +</colgroup> +<tbody> +<tr> +<td>Encryption</td> +<td>AES-256</td> +</tr> +<tr> +<td>HASH</td> +<td>SHA-256</td> +</tr> +<tr> +<td>Life-Time</td> +<td>3600</td> +</tr> +<tr> +<td>PFS</td> +<td>disable</td> +</tr> +</tbody> +</table> + +**Hosts configuration** + +<table style="width:33%;"> +<colgroup> +<col style="width: 12%" /> +<col style="width: 20%" /> +</colgroup> +<tbody> +<tr> +<td>PC1 IP</td> +<td>192.168.0.2</td> +</tr> +<tr> +<td>PC2 IP</td> +<td>192.168.1.2</td> +</tr> +<tr> +<td>PC3 IP</td> +<td>192.168.10.2</td> +</tr> +<tr> +<td>PC4 IP</td> +<td>192.168.11.2</td> +</tr> +</tbody> +</table> + +## Configuration + +### VyOS + +``` none +set interfaces ethernet eth0 address '10.0.1.2/30' +set interfaces ethernet eth1 address '192.168.0.1/24' +set interfaces ethernet eth2 address '192.168.1.1/24' +set interfaces vti vti1 address '10.100.100.1/30' +set interfaces vti vti1 mtu '1438' +set protocols ospf area 0 network '10.100.100.0/30' +set protocols ospf area 0 network '192.168.0.0/24' +set protocols ospf area 0 network '192.168.1.0/24' +set protocols ospf interface eth1 passive +set protocols ospf interface eth2 passive +set protocols ospf interface vti1 network 'point-to-point' +set protocols ospf parameters router-id '2.2.2.2' +set protocols static route 0.0.0.0/0 next-hop 10.0.1.1 +set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' +set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' +set vpn ipsec authentication psk AUTH-PSK secret 'dGVzdA==' +set vpn ipsec authentication psk AUTH-PSK secret-type 'base64' +set vpn ipsec esp-group ESP-GROUP lifetime '3600' +set vpn ipsec esp-group ESP-GROUP pfs 'disable' +set vpn ipsec esp-group ESP-GROUP proposal 10 encryption 'aes256' +set vpn ipsec esp-group ESP-GROUP proposal 10 hash 'sha256' +set vpn ipsec ike-group IKE-GROUP close-action 'start' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'restart' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '10' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection timeout '30' +set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev1' +set vpn ipsec ike-group IKE-GROUP lifetime '28800' +set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' +set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes128' +set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' +set vpn ipsec options disable-route-autoinstall +set vpn ipsec site-to-site peer PA authentication local-id '10.0.1.2' +set vpn ipsec site-to-site peer PA authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer PA authentication remote-id '10.0.2.2' +set vpn ipsec site-to-site peer PA connection-type 'initiate' +set vpn ipsec site-to-site peer PA default-esp-group 'ESP-GROUP' +set vpn ipsec site-to-site peer PA ike-group 'IKE-GROUP' +set vpn ipsec site-to-site peer PA local-address '10.0.1.2' +set vpn ipsec site-to-site peer PA remote-address '10.0.2.2' +set vpn ipsec site-to-site peer PA vti bind 'vti1' +``` + +### Palo Alto + +GUI Configuration: +Network -\> Network Profiles -\> IKE Crypto + +<img src="/_static/images/PA-IKE-group.webp" class="align-center" alt="image" /> + +Network -\> Network Profiles -\> IKE Gateways + +<img src="/_static/images/PA-IKE-GW-1.webp" class="align-center" alt="image" /> + +<img src="/_static/images/PA-IKE-GW-2.webp" class="align-center" alt="image" /> + +Network -\> Network Profiles -\> IPSec Crypto + +<img src="/_static/images/PA-ESP-group.webp" class="align-center" alt="image" /> + +Network -\> Interfaces + +<img src="/_static/images/PA-tunnel-1.webp" class="align-center" alt="image" /> + +<img src="/_static/images/PA-tunnel-2.webp" class="align-center" alt="image" /> + +<img src="/_static/images/PA-tunnel-3.webp" class="align-center" alt="image" /> + +Network -\> IPSec Tunnels + +<img src="/_static/images/PA-IPsec-tunnel.webp" class="align-center" alt="image" /> + +CLI configuration with OSPF: + +``` none +set network interface ethernet ethernet1/1 layer3 ip 10.0.2.2/30 +set network interface ethernet ethernet1/1 layer3 interface-management-profile Allow +set network interface ethernet ethernet1/2 layer3 ip 192.168.10.1/24 +set network interface ethernet ethernet1/1 layer3 interface-management-profile Allow +set network interface ethernet ethernet1/3 layer3 ip 192.168.11.1/24 +set network interface ethernet ethernet1/1 layer3 interface-management-profile Allow +set network interface tunnel units tunnel.1 ip 10.100.100.2/30 +set network interface tunnel units tunnel.1 interface-management-profile Allow +set network interface tunnel units tunnel.1 mtu 1438 +set network profiles interface-management-profile Allow ping yes +set network ike crypto-profiles ike-crypto-profiles IKE-GROUP hash sha1 +set network ike crypto-profiles ike-crypto-profiles IKE-GROUP dh-group group14 +set network ike crypto-profiles ike-crypto-profiles IKE-GROUP encryption aes-128-cbc +set network ike crypto-profiles ike-crypto-profiles IKE-GROUP lifetime seconds 28800 +set network ike crypto-profiles ipsec-crypto-profiles ESP-GROUP esp authentication sha256 +set network ike crypto-profiles ipsec-crypto-profiles ESP-GROUP esp encryption aes-256-cbc +set network ike crypto-profiles ipsec-crypto-profiles ESP-GROUP lifetime seconds 3600 +set network ike crypto-profiles ipsec-crypto-profiles ESP-GROUP dh-group no-pfs +set network ike gateway VyOS authentication pre-shared-key key test +set network ike gateway VyOS protocol ikev1 dpd enable yes +set network ike gateway VyOS protocol ikev1 exchange-mode main +set network ike gateway VyOS protocol ikev1 ike-crypto-profile IKE-GROUP +set network ike gateway VyOS protocol ikev2 dpd enable yes +set network ike gateway VyOS protocol version ikev1 +set network ike gateway VyOS protocol-common nat-traversal enable yes +set network ike gateway VyOS protocol-common fragmentation enable no +set network ike gateway VyOS protocol-common passive-mode yes +set network ike gateway VyOS local-address interface ethernet1/1 +set network ike gateway VyOS peer-address ip 10.0.1.2 +set network ike gateway VyOS local-id id 10.0.2.2 +set network ike gateway VyOS local-id type ipaddr +set network ike gateway VyOS peer-id id 10.0.1.2 +set network ike gateway VyOS peer-id type ipaddr +set network tunnel ipsec VyOS-tunnel auto-key ike-gateway VyOS +set network tunnel ipsec VyOS-tunnel auto-key ipsec-crypto-profile ESP-GROUP +set network tunnel ipsec VyOS-tunnel tunnel-monitor enable no +set network tunnel ipsec VyOS-tunnel tunnel-interface tunnel.1 +set network tunnel ipsec VyOS-tunnel anti-replay no +set network virtual-router default protocol ospf enable yes +set network virtual-router default protocol ospf area 0.0.0.0 type normal +set network virtual-router default protocol ospf area 0.0.0.0 interface tunnel.1 enable yes +set network virtual-router default protocol ospf area 0.0.0.0 interface tunnel.1 passive no +set network virtual-router default protocol ospf area 0.0.0.0 interface tunnel.1 link-type p2p +set network virtual-router default protocol ospf area 0.0.0.0 interface ethernet1/2 enable yes +set network virtual-router default protocol ospf area 0.0.0.0 interface ethernet1/2 passive yes +set network virtual-router default protocol ospf area 0.0.0.0 interface ethernet1/2 link-type broadcast +set network virtual-router default protocol ospf area 0.0.0.0 interface ethernet1/3 enable yes +set network virtual-router default protocol ospf area 0.0.0.0 interface ethernet1/3 passive yes +set network virtual-router default protocol ospf area 0.0.0.0 interface ethernet1/3 link-type broadcast +set network virtual-router default protocol ospf router-id 1.1.1.1 +set network virtual-router default interface [ ethernet1/1 ethernet1/2 ethernet1/3 tunnel.1 ] +``` + +## Monitoring + +### Monitoring on VyOS side + +IKE SAs: + +``` none +vyos@vyos:~$ show vpn ike sa +Peer ID / IP Local ID / IP +------------ ------------- +10.0.2.2 10.0.2.2 10.0.1.2 10.0.1.2 + + State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time + ----- ------ ------- ---- --------- ----- ------ ------ + up IKEv1 AES_CBC_128 HMAC_SHA1_96 MODP_2048 no 1372 25802 +``` + +IPsec SAs: + +``` none +vyos@vyos:~$ show vpn ipsec sa +Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal +------------ ------- -------- -------------- ---------------- ---------------- ----------- ----------------------------- +PA-vti up 23m27s 9K/10K 149/151 10.0.2.2 10.0.2.2 AES_CBC_256/HMAC_SHA2_256_128 +``` + +OSPF Neighbor Status: + +``` none +vyos@vyos:~$ show ip ospf neighbor + +Neighbor ID Pri State Up Time Dead Time Address Interface RXmtL RqstL DBsmL +1.1.1.1 1 Full/- 23m56s 37.948s 10.100.100.2 vti1:10.100.100.1 0 0 0 +``` + +Routing Table: + +``` none +vyos@vyos:~$ show ip route +Codes: K - kernel route, C - connected, L - local, S - static, + R - RIP, O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, t - Table-Direct, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +S>* 0.0.0.0/0 [1/0] via 10.0.1.1, eth0, weight 1, 00:27:30 +C>* 10.0.1.0/30 is directly connected, eth0, weight 1, 00:27:34 +L>* 10.0.1.2/32 is directly connected, eth0, weight 1, 00:27:34 +O 10.100.100.0/30 [110/1] is directly connected, vti1, weight 1, 00:24:34 +C>* 10.100.100.0/30 is directly connected, vti1, weight 1, 00:24:34 +L>* 10.100.100.1/32 is directly connected, vti1, weight 1, 00:24:34 +O 192.168.0.0/24 [110/1] is directly connected, eth1, weight 1, 00:27:29 +C>* 192.168.0.0/24 is directly connected, eth1, weight 1, 00:27:34 +L>* 192.168.0.1/32 is directly connected, eth1, weight 1, 00:27:34 +O 192.168.1.0/24 [110/1] is directly connected, eth2, weight 1, 00:27:29 +C>* 192.168.1.0/24 is directly connected, eth2, weight 1, 00:27:34 +L>* 192.168.1.1/32 is directly connected, eth2, weight 1, 00:27:34 +O>* 192.168.10.0/24 [110/11] via 10.100.100.2, vti1, weight 1, 00:24:19 +O>* 192.168.11.0/24 [110/11] via 10.100.100.2, vti1, weight 1, 00:24:19 +``` + +### Monitoring on Palo Alto side + +IKE SAs: + +``` none +admin@PA-VM> show vpn ike-sa + +IKEv1 phase-1 SAs +GwID/client IP Peer-Address Gateway Name Role Mode Algorithm Established Expiration V ST Xt Phase2 +-------------- ------------ ------------ ---- ---- --------- ----------- ---------- - -- -- ------ +1 10.0.1.2 VyOS Resp Main PSK/DH14/A128/SHA1 Jul.31 01:35:00 Jul.31 09:35:00 v1 13 1 1 + +Show IKEv1 IKE SA: Total 1 gateways found. 1 ike sa found. + + +IKEv1 phase-2 SAs +Gateway Name TnID Tunnel GwID/IP Role Algorithm SPI(in) SPI(out) MsgID ST Xt +------------ ---- ------ ------- ---- --------- ------- -------- ----- -- -- +VyOS 1 VyOS-tunnel 1 Resp ESP/ /tunl/SHA2 8827A3D9 C204F4FA BD202829 9 1 + +Show IKEv1 phase2 SA: Total 1 gateways found. 1 ike sa found. + + +There is no IKEv2 SA found. +``` + +IPsec SAs: + +``` none +admin@PA-VM> show vpn ipsec-sa + +GwID/client IP TnID Peer-Address Tunnel(Gateway) Algorithm SPI(in) SPI(out) life(Sec/KB) remain-time(Sec) +-------------- ---- ------------ --------------- --------- ------- -------- ------------ ---------------- +1 1 10.0.1.2 VyOS-tunnel(VyOS) ESP/A256/SHA256 8827A3D9 C204F4FA 3600/Unlimited 2733 + +Show IPSec SA: Total 1 tunnels found. 1 ipsec sa found. +``` + +OSPF Neighbor Status: + +``` none +admin@PA-VM> show routing protocol ospf neighbor + + Options: 0x80:reserved, O:Opaq-LSA capability, DC:demand circuits, EA:Ext-Attr LSA capability, + N/P:NSSA option, MC:multicase, E:AS external LSA capability, T:TOS capability + ========== + virtual router: default + neighbor address: 10.100.100.1 + local address binding: 0.0.0.0 + type: dynamic + status: full + neighbor router ID: 2.2.2.2 + area id: 0.0.0.0 + neighbor priority: 1 + lifetime remain: 32 + messages pending: 0 + LSA request pending: 0 + options: 0x02: E + hello suppressed: no + restart helper status: not helping + restart helper time remaining: 0 + restart helper exit reason: none +``` + +Routing Table: + +``` none +admin@PA-VM> show routing route + +flags: A:active, ?:loose, C:connect, H:host, S:static, ~:internal, R:rip, O:ospf, B:bgp, + Oi:ospf intra-area, Oo:ospf inter-area, O1:ospf ext-type-1, O2:ospf ext-type-2, E:ecmp, M:multicast + + +VIRTUAL ROUTER: default (id 1) + ========== +destination nexthop metric flags age interface next-AS +0.0.0.0/0 10.0.2.1 10 A S ethernet1/1 +10.0.2.0/30 10.0.2.2 0 A C ethernet1/1 +10.0.2.2/32 0.0.0.0 0 A H +10.100.100.0/30 0.0.0.0 10 Oi 1273 tunnel.1 +10.100.100.0/30 10.100.100.2 0 A C tunnel.1 +10.100.100.2/32 0.0.0.0 0 A H +192.168.0.0/24 10.100.100.1 11 A Oi 1253 tunnel.1 +192.168.1.0/24 10.100.100.1 11 A Oi 1253 tunnel.1 +192.168.10.0/24 0.0.0.0 10 Oi 1273 ethernet1/2 +192.168.10.0/24 192.168.10.1 0 A C ethernet1/2 +192.168.10.1/32 0.0.0.0 0 A H +192.168.11.0/24 0.0.0.0 10 Oi 1273 ethernet1/3 +192.168.11.0/24 192.168.11.1 0 A C ethernet1/3 +192.168.11.1/32 0.0.0.0 0 A H +total routes shown: 14 +``` + +### Checking Connectivity + +ICMP packets from PC1 to PC3. + +``` none +PC1> ping 192.168.10.2 + +84 bytes from 192.168.10.2 icmp_seq=1 ttl=62 time=8.479 ms +84 bytes from 192.168.10.2 icmp_seq=2 ttl=62 time=3.344 ms +84 bytes from 192.168.10.2 icmp_seq=3 ttl=62 time=3.139 ms +84 bytes from 192.168.10.2 icmp_seq=4 ttl=62 time=3.176 ms +84 bytes from 192.168.10.2 icmp_seq=5 ttl=62 time=3.978 ms +``` + +ICMP packets from PC2 to PC4. + +``` none +PC2> ping 192.168.11.2 + +84 bytes from 192.168.11.2 icmp_seq=1 ttl=62 time=9.687 ms +84 bytes from 192.168.11.2 icmp_seq=2 ttl=62 time=3.286 ms +84 bytes from 192.168.11.2 icmp_seq=3 ttl=62 time=2.972 ms +``` diff --git a/docs/configexamples/md-l3vpn-hub-and-spoke.md b/docs/configexamples/md-l3vpn-hub-and-spoke.md new file mode 100644 index 00000000..02269386 --- /dev/null +++ b/docs/configexamples/md-l3vpn-hub-and-spoke.md @@ -0,0 +1,1135 @@ +# L3VPN for Hub-and-Spoke connectivity with VyOS + +IP/MPLS technology is widely used by various service providers and large +enterprises in order to achieve better network scalability, manageability +and flexibility. It also provides the possibility to deliver different +services for the customers in a seamless manner. +Layer 3 VPN (L3VPN) is a type of VPN mode that is built and delivered +through OSI layer 3 networking technologies. Often the border gateway +protocol (BGP) is used to send and receive VPN-related data that is +responsible for the control plane. L3VPN utilizes virtual routing and +forwarding (VRF) techniques to receive and deliver user data as well as +separate data planes of the end-users. It is built using a combination of +IP- and MPLS-based information. Generally, L3VPNs are used to send data +on back-end VPN infrastructures, such as for VPN connections between data +centres, HQs and branches. + +An L3VPN consists of multiple access links, multiple VPN routing and +forwarding (VRF) tables, and multiple MPLS paths or multiple P2MP LSPs. +An L3VPN can be configured to connect two or more customer sites. +In hub-and-spoke MPLS L3VPN environments, the spoke routers need to have +unique Route Distinguishers (RDs). In order to use the hub site as a +transit point for connectivity in such an environment, the spoke sites +export their routes to the hub. Spokes can talk to hubs, but never have +direct paths to other spokes. All traffic between spokes is controlled +and delivered over the hub site. + +To deploy a Layer3 VPN with MPLS on VyOS, we should meet a couple +requirements in order to properly implement the solution. +We'll use the following nodes in our LAB environment: + +- 2 x Route reflectors (VyOS-RRx) +- 4 x Provider routers (VyOS-Px) +- 3 x Provider Edge (VyOs-PEx) +- 3 x Customer Edge (VyOS-CEx) + +The following software was used in the creation of this document: + +- Operating system: VyOS +- Version: 1.4-rolling-202110310317 +- Image name: vyos-1.4-rolling-202110310317-amd64.iso + +**NOTE:** VyOS Router (tested with VyOS 1.4-rolling-202110310317) +– The configurations below are specifically for VyOS 1.4.x. + +General information can be found in the `configuration/vrf/index:L3VPN VRFs` chapter. + +## Topology + +<img src="/_static/images/L3VPN_hub_and_spoke.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +## How does it work? + +As we know the main assumption of L3VPN “Hub and Spoke” is, that the traffic +between spokes have to pass via hub, in our scenario VyOS-PE2 is the Hub PE +and the VyOS-CE1-HUB is the central customer office device that is responsible +for controlling access between all spokes and announcing its network prefixes +(10.0.0.100/32). VyOS-PE2 has the main VRF (its name is BLUE_HUB), its +own Route-Distinguisher(RD) and route-target import/export lists. +Multiprotocol-BGP(MP-BGP) delivers L3VPN related control-plane information to +the nodes across network where PEs Spokes import the route-target 60535:1030 +(this is export route-target of vrf BLUE_HUB) and export its own route-target +60535:1011(this is vrf BLUE_SPOKE export route-target). Therefore, the +Customer edge nodes can only learn the network prefixes of the HUB site +\[10.0.0.100/32\]. For this example VyOS-CE1 has network prefixes +\[10.0.0.80/32\] / VyOS-CE2 has network prefixes \[10.0.0.90/32\]. +Route-Reflector devices VyOS-RR1 and VyOS-RR2 are used to simplify network +routes exchange and minimize iBGP peerings between devices. + +L3VPN configuration parameters table: + +<table style="width:95%;"> +<colgroup> +<col style="width: 13%" /> +<col style="width: 9%" /> +<col style="width: 15%" /> +<col style="width: 21%" /> +<col style="width: 17%" /> +<col style="width: 17%" /> +</colgroup> +<tbody> +<tr> +<td><blockquote> +<p>Node</p> +</blockquote></td> +<td><blockquote> +<p>Role</p> +</blockquote></td> +<td><blockquote> +<p>VRF</p> +</blockquote></td> +<td><blockquote> +<p>RD</p> +</blockquote></td> +<td><blockquote> +<p>RT import</p> +</blockquote></td> +<td><blockquote> +<p>RT export</p> +</blockquote></td> +</tr> +<tr> +<td>VyOS-PE2</td> +<td>Hub</td> +<td>BLUE_HUB</td> +<td>10.80.80.1:1011</td> +<td>65035:1011 +65035:1030</td> +<td>65035:1030</td> +</tr> +<tr> +<td>VyOS-PE1</td> +<td>Spoke</td> +<td>BLUE_SPOKE</td> +<td>10.50.50.1:1011</td> +<td>65035:1030</td> +<td>65035:1011</td> +</tr> +<tr> +<td>VyOS-PE3</td> +<td>Spoke</td> +<td>BLUE_SPOKE</td> +<td>10.60.60.1:1011</td> +<td>65035:1030</td> +<td>65035:1011</td> +</tr> +</tbody> +</table> + +## Configuration + +### Step-1: Configuring IGP and enabling MPLS LDP + +At the first step we need to configure the IP/MPLS backbone network using OSPF +as IGP protocol and LDP as label-switching protocol for the base connectivity +between **P** (rovider), **P** (rovider) **E** (dge) and **R** (oute) **R** +(eflector) nodes: + +- VyOS-P1: + +``` none +# interfaces +set interfaces dummy dum10 address '10.0.0.3/32' +set interfaces ethernet eth0 address '172.16.30.1/24' +set interfaces ethernet eth1 address '172.16.40.1/24' +set interfaces ethernet eth2 address '172.16.90.1/24' +set interfaces ethernet eth3 address '172.16.10.1/24' +set interfaces ethernet eth5 address '172.16.100.1/24' + +# protocols ospf+ldp +set protocols mpls interface 'eth1' +set protocols mpls interface 'eth2' +set protocols mpls interface 'eth3' +set protocols mpls interface 'eth5' +set protocols mpls interface 'eth0' +set protocols mpls ldp discovery transport-ipv4-address '10.0.0.3' +set protocols mpls ldp interface 'eth0' +set protocols mpls ldp interface 'eth1' +set protocols mpls ldp interface 'eth2' +set protocols mpls ldp interface 'eth3' +set protocols mpls ldp interface 'eth5' +set protocols mpls ldp router-id '10.0.0.3' +set protocols ospf area 0 network '0.0.0.0/0' +set protocols ospf parameters abr-type 'cisco' +set protocols ospf parameters router-id '10.0.0.3' +``` + +- VyOS-P2: + +``` none +# interfaces +set interfaces dummy dum10 address '10.0.0.4/32' +set interfaces ethernet eth0 address '172.16.30.2/24' +set interfaces ethernet eth1 address '172.16.20.1/24' +set interfaces ethernet eth2 address '172.16.120.1/24' +set interfaces ethernet eth3 address '172.16.60.1/24' + +# protocols ospf+ldp +set protocols mpls interface 'eth1' +set protocols mpls interface 'eth2' +set protocols mpls interface 'eth3' +set protocols mpls interface 'eth0' +set protocols mpls ldp discovery transport-ipv4-address '10.0.0.4' +set protocols mpls ldp interface 'eth0' +set protocols mpls ldp interface 'eth1' +set protocols mpls ldp interface 'eth2' +set protocols mpls ldp interface 'eth3' +set protocols mpls ldp router-id '10.0.0.4' +set protocols ospf area 0 network '0.0.0.0/0' +set protocols ospf parameters abr-type 'cisco' +set protocols ospf parameters router-id '10.0.0.4' +``` + +- VyOS-P3: + +``` none +# interfaces +set interfaces dummy dum10 address '10.0.0.5/32' +set interfaces ethernet eth0 address '172.16.110.1/24' +set interfaces ethernet eth1 address '172.16.40.2/24' +set interfaces ethernet eth2 address '172.16.50.1/24' +set interfaces ethernet eth3 address '172.16.70.1/24' + +# protocols ospf + ldp +set protocols mpls interface 'eth1' +set protocols mpls interface 'eth2' +set protocols mpls interface 'eth3' +set protocols mpls interface 'eth0' +set protocols mpls ldp discovery transport-ipv4-address '10.0.0.5' +set protocols mpls ldp interface 'eth0' +set protocols mpls ldp interface 'eth1' +set protocols mpls ldp interface 'eth2' +set protocols mpls ldp interface 'eth3' +set protocols mpls ldp router-id '10.0.0.5' +set protocols ospf area 0 network '0.0.0.0/0' +set protocols ospf parameters abr-type 'cisco' +set protocols ospf parameters router-id '10.0.0.5' +``` + +- VyOS-P4: + +``` none +# interfaces +set interfaces dummy dum10 address '10.0.0.6/32' +set interfaces ethernet eth0 address '172.16.80.2/24' +set interfaces ethernet eth1 address '172.16.130.1/24' +set interfaces ethernet eth2 address '172.16.50.2/24' +set interfaces ethernet eth3 address '172.16.60.2/24' +set interfaces ethernet eth5 address '172.16.140.1/24' + + +# protocols ospf + ldp +set protocols mpls interface 'eth1' +set protocols mpls interface 'eth2' +set protocols mpls interface 'eth3' +set protocols mpls interface 'eth0' +set protocols mpls interface 'eth5' +set protocols mpls ldp discovery transport-ipv4-address '10.0.0.6' +set protocols mpls ldp interface 'eth0' +set protocols mpls ldp interface 'eth1' +set protocols mpls ldp interface 'eth2' +set protocols mpls ldp interface 'eth3' +set protocols mpls ldp interface 'eth5' +set protocols mpls ldp router-id '10.0.0.6' +set protocols ospf area 0 network '0.0.0.0/0' +set protocols ospf parameters abr-type 'cisco' +set protocols ospf parameters router-id '10.0.0.6' +``` + +- VyOS-PE1: + +``` none +# interfaces +set interfaces dummy dum10 address '10.0.0.7/32' +set interfaces ethernet eth0 address '172.16.90.2/24' + +# protocols ospf + ldp +set protocols mpls interface 'eth0' +set protocols mpls ldp discovery transport-ipv4-address '10.0.0.7' +set protocols mpls ldp interface 'eth0' +set protocols mpls ldp router-id '10.0.0.7' +set protocols ospf area 0 network '0.0.0.0/0' +set protocols ospf parameters abr-type 'cisco' +set protocols ospf parameters router-id '10.0.0.7' +``` + +- VyOS-PE2: + +``` none +# interfaces +set interfaces dummy dum10 address '10.0.0.8/32' +set interfaces ethernet eth0 address '172.16.110.2/24' +set interfaces ethernet eth1 address '172.16.100.2/24' +set interfaces ethernet eth2 address '172.16.80.1/24' + +# protocols ospf + ldp +set protocols mpls interface 'eth0' +set protocols mpls interface 'eth1' +set protocols mpls ldp discovery transport-ipv4-address '10.0.0.8' +set protocols mpls ldp interface 'eth0' +set protocols mpls ldp interface 'eth1' +set protocols mpls ldp router-id '10.0.0.8' +set protocols ospf area 0 network '0.0.0.0/0' +set protocols ospf parameters abr-type 'cisco' +set protocols ospf parameters router-id '10.0.0.8' +``` + +- VyOS-PE3: + +``` none +# interfaces +set interfaces dummy dum10 address '10.0.0.10/32' +set interfaces ethernet eth0 address '172.16.140.2/24' + +# protocols ospf + ldp +set protocols mpls interface 'eth0' +set protocols mpls ldp discovery transport-ipv4-address '10.0.0.10' +set protocols mpls ldp interface 'eth0' +set protocols mpls ldp router-id '10.0.0.10' +set protocols ospf area 0 network '0.0.0.0/0' +set protocols ospf parameters abr-type 'cisco' +set protocols ospf parameters router-id '10.0.0.10' +``` + +- VyOS-RR1: + +``` none +# interfaces +set interfaces ethernet eth1 address '172.16.20.2/24' +set interfaces ethernet eth2 address '172.16.10.2/24' +set interfaces dummy dum10 address '10.0.0.1/32' + +# protocols ospf + ldp +set protocols mpls interface 'eth1' +set protocols mpls interface 'eth2' +set protocols mpls ldp discovery transport-ipv4-address '10.0.0.1' +set protocols mpls ldp interface 'eth1' +set protocols mpls ldp interface 'eth2' +set protocols mpls ldp router-id '10.0.0.1' +set protocols ospf area 0 network '0.0.0.0/0' +set protocols ospf parameters abr-type 'cisco' +set protocols ospf parameters router-id '10.0.0.1' +``` + +- VyOS-RR2: + +``` none +# interfaces +set interfaces ethernet eth0 address '172.16.80.1/24' +set interfaces ethernet eth1 address '172.16.70.2/24' +set interfaces dummy dum10 address '10.0.0.2/32' + +# protocols ospf + ldp +set protocols mpls interface 'eth0' +set protocols mpls interface 'eth1' +set protocols mpls ldp discovery transport-ipv4-address '10.0.0.2' +set protocols mpls ldp interface 'eth1' +set protocols mpls ldp interface 'eth0' +set protocols mpls ldp router-id '10.0.0.2' +set protocols ospf area 0 network '0.0.0.0/0' +set protocols ospf parameters abr-type 'cisco' +set protocols ospf parameters router-id '10.0.0.2' +``` + +### Step-2: Configuring iBGP for L3VPN control-plane + +At this step we are going to enable iBGP protocol on MPLS nodes and +Route Reflectors (two routers for redundancy) that will deliver IPv4 +VPN (L3VPN) routes between them: + +- VyOS-RR1: + +``` none +set protocols bgp system-as '65001' +set protocols bgp neighbor 10.0.0.7 address-family ipv4-vpn route-reflector-client +set protocols bgp neighbor 10.0.0.7 peer-group 'RR_VPNv4' +set protocols bgp neighbor 10.0.0.8 address-family ipv4-vpn route-reflector-client +set protocols bgp neighbor 10.0.0.8 peer-group 'RR_VPNv4' +set protocols bgp neighbor 10.0.0.10 address-family ipv4-vpn route-reflector-client +set protocols bgp neighbor 10.0.0.10 peer-group 'RR_VPNv4' +set protocols bgp parameters cluster-id '10.0.0.1' +set protocols bgp parameters log-neighbor-changes +set protocols bgp parameters router-id '10.0.0.1' +set protocols bgp peer-group RR_VPNv4 remote-as '65001' +set protocols bgp peer-group RR_VPNv4 update-source 'dum10' +``` + +- VyOS-RR2: + +``` none +set protocols bgp system-as '65001' +set protocols bgp neighbor 10.0.0.7 address-family ipv4-vpn route-reflector-client +set protocols bgp neighbor 10.0.0.7 peer-group 'RR_VPNv4' +set protocols bgp neighbor 10.0.0.8 address-family ipv4-vpn route-reflector-client +set protocols bgp neighbor 10.0.0.8 peer-group 'RR_VPNv4' +set protocols bgp neighbor 10.0.0.10 address-family ipv4-vpn route-reflector-client +set protocols bgp neighbor 10.0.0.10 peer-group 'RR_VPNv4' +set protocols bgp parameters cluster-id '10.0.0.1' +set protocols bgp parameters log-neighbor-changes +set protocols bgp parameters router-id '10.0.0.2' +set protocols bgp peer-group RR_VPNv4 remote-as '65001' +set protocols bgp peer-group RR_VPNv4 update-source 'dum10' +``` + +- VyOS-PE1: + +``` none +set protocols bgp system-as '65001' +set protocols bgp neighbor 10.0.0.1 address-family ipv4-vpn nexthop-self +set protocols bgp neighbor 10.0.0.1 peer-group 'RR_VPNv4' +set protocols bgp neighbor 10.0.0.2 address-family ipv4-vpn nexthop-self +set protocols bgp neighbor 10.0.0.2 peer-group 'RR_VPNv4' +set protocols bgp parameters log-neighbor-changes +set protocols bgp parameters router-id '10.0.0.7' +set protocols bgp peer-group RR_VPNv4 remote-as '65001' +set protocols bgp peer-group RR_VPNv4 update-source 'dum10' +``` + +- VyOS-PE2: + +``` none +set protocols bgp system-as '65001' +set protocols bgp neighbor 10.0.0.1 address-family ipv4-vpn nexthop-self +set protocols bgp neighbor 10.0.0.1 peer-group 'RR_VPNv4' +set protocols bgp neighbor 10.0.0.2 address-family ipv4-vpn nexthop-self +set protocols bgp neighbor 10.0.0.2 peer-group 'RR_VPNv4' +set protocols bgp parameters log-neighbor-changes +set protocols bgp parameters router-id '10.0.0.8' +set protocols bgp peer-group RR_VPNv4 remote-as '65001' +set protocols bgp peer-group RR_VPNv4 update-source 'dum10' +``` + +- VyOS-PE3: + +``` none +set protocols bgp system-as '65001' +set protocols bgp neighbor 10.0.0.1 address-family ipv4-vpn nexthop-self +set protocols bgp neighbor 10.0.0.1 peer-group 'RR_VPNv4' +set protocols bgp neighbor 10.0.0.2 address-family ipv4-vpn nexthop-self +set protocols bgp neighbor 10.0.0.2 peer-group 'RR_VPNv4' +set protocols bgp parameters log-neighbor-changes +set protocols bgp parameters router-id '10.0.0.10' +set protocols bgp peer-group RR_VPNv4 remote-as '65001' +set protocols bgp peer-group RR_VPNv4 update-source 'dum10' +``` + +### Step-3: Configuring L3VPN VRFs on PE nodes + +This section provides configuration steps for setting up VRFs on our +PE nodes including CE facing interfaces, BGP, rd and route-target +import/export based on the pre-defined parameters. + +- VyOS-PE1: + +``` none +# VRF settings +set vrf name BLUE_SPOKE table '200' +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast export vpn +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast import vpn +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast label vpn export 'auto' +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast network 10.50.50.0/24 +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast rd vpn export '10.50.50.1:1011' +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast redistribute connected +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast route-target vpn export '65035:1011' +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast route-target vpn import '65035:1030' +set vrf name BLUE_SPOKE protocols bgp system-as '65001' +set vrf name BLUE_SPOKE protocols bgp neighbor 10.50.50.2 address-family ipv4-unicast as-override +set vrf name BLUE_SPOKE protocols bgp neighbor 10.50.50.2 remote-as '65035' + +# interfaces +set interfaces ethernet eth3 address '10.50.50.1/24' +set interfaces ethernet eth3 vrf 'BLUE_SPOKE' +``` + +- VyOS-PE2: + +``` none +# VRF settings +set vrf name BLUE_HUB table '400' +set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast export vpn +set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast import vpn +set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast label vpn export 'auto' +set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast network 10.80.80.0/24 +set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast rd vpn export '10.80.80.1:1011' +set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast redistribute connected +set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast route-target vpn export '65035:1030' +set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast route-target vpn import '65035:1011 65050:2011 65035:1030' +set vrf name BLUE_HUB protocols bgp system-as '65001' +set vrf name BLUE_HUB protocols bgp neighbor 10.80.80.2 address-family ipv4-unicast as-override +set vrf name BLUE_HUB protocols bgp neighbor 10.80.80.2 remote-as '65035' + +# interfaces +set interfaces ethernet eth3 address '10.80.80.1/24' +set interfaces ethernet eth3 vrf 'BLUE_HUB' +``` + +- VyOS-PE3: + +``` none +# VRF settings +set vrf name BLUE_SPOKE table '200' +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast export vpn +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast import vpn +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast label vpn export 'auto' +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast network 10.60.60.0/24 +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast rd vpn export '10.60.60.1:1011' +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast redistribute connected +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast route-target vpn export '65035:1011' +set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast route-target vpn import '65035:1030' +set vrf name BLUE_SPOKE protocols bgp system-as '65001' +set vrf name BLUE_SPOKE protocols bgp neighbor 10.60.60.2 address-family ipv4-unicast as-override +set vrf name BLUE_SPOKE protocols bgp neighbor 10.60.60.2 remote-as '65035' + +# interfaces +set interfaces ethernet eth3 address '10.60.60.1/24' +set interfaces ethernet eth3 vrf 'BLUE_SPOKE' +``` + +### Step-4: Configuring CE nodes + +Dynamic routing used between CE and PE nodes and eBGP peering +established for the route exchanging between them. All routes +received by PEs are then exported to L3VPN and delivered from +Spoke sites to Hub and vise-versa based on previously +configured L3VPN parameters. + +- VyOS-CE1-SPOKE: + +``` none +# interfaces +set interfaces dummy dum20 address '10.0.0.80/32' +set interfaces ethernet eth0 address '10.50.50.2/24' + +# BGP for peering with PE +set protocols bgp system-as 65035 +set protocols bgp address-family ipv4-unicast network 10.0.0.80/32 +set protocols bgp neighbor 10.50.50.1 ebgp-multihop '2' +set protocols bgp neighbor 10.50.50.1 remote-as '65001' +set protocols bgp neighbor 10.50.50.1 update-source 'eth0' +set protocols bgp parameters log-neighbor-changes +set protocols bgp parameters router-id '10.50.50.2' +``` + +- VyOS-CE1-HUB: + +``` none +# interfaces +set interfaces dummy dum20 address '10.0.0.100/32' +set interfaces ethernet eth0 address '10.80.80.2/24' + +# BGP for peering with PE +set protocols bgp system-as 65035 +set protocols bgp address-family ipv4-unicast network 10.0.0.100/32 +set protocols bgp address-family ipv4-unicast redistribute connected +set protocols bgp neighbor 10.80.80.1 ebgp-multihop '2' +set protocols bgp neighbor 10.80.80.1 remote-as '65001' +set protocols bgp neighbor 10.80.80.1 update-source 'eth0' +set protocols bgp parameters log-neighbor-changes +set protocols bgp parameters router-id '10.80.80.2' +``` + +- VyOS-CE2-SPOKE: + +``` none +# interfaces +set interfaces dummy dum20 address '10.0.0.90/32' +set interfaces ethernet eth0 address '10.60.60.2/24' + +# BGP for peering with PE +set protocols bgp system-as 65035 +set protocols bgp address-family ipv4-unicast network 10.0.0.90/32 +set protocols bgp neighbor 10.60.60.1 ebgp-multihop '2' +set protocols bgp neighbor 10.60.60.1 remote-as '65001' +set protocols bgp neighbor 10.60.60.1 update-source 'eth0' +set protocols bgp parameters log-neighbor-changes +set protocols bgp parameters router-id '10.60.60.2' +``` + +### Step-5: Verification + +This section describes verification commands for MPLS/BGP/LDP +protocols and L3VPN related routes as well as diagnosis and +reachability checks between CE nodes. + +Let’s check IPv4 routing and MPLS information on provider nodes +(same procedure for all P nodes): + +- “show ip ospf neighbor” for checking ospf relationship + +``` none +vyos@VyOS-P1:~$ show ip ospf neighbor + +Neighbor ID Pri State Dead Time Address Interface RXmtL RqstL DBsmL +10.0.0.4 1 Full/Backup 34.718s 172.16.30.2 eth0:172.16.30.1 0 0 0 +10.0.0.5 1 Full/Backup 35.132s 172.16.40.2 eth1:172.16.40.1 0 0 0 +10.0.0.7 1 Full/Backup 34.764s 172.16.90.2 eth2:172.16.90.1 0 0 0 +10.0.0.1 1 Full/Backup 35.642s 172.16.10.2 eth3:172.16.10.1 0 0 0 +10.0.0.8 1 Full/Backup 35.484s 172.16.100.2 eth5:172.16.100.1 0 0 0 +``` + +- “show mpls ldp neighbor “ for checking ldp neighbors + +``` none +vyos@VyOS-P1:~$ show mpls ldp neighbor +AF ID State Remote Address Uptime +ipv4 10.0.0.1 OPERATIONAL 10.0.0.1 07w5d06h +ipv4 10.0.0.4 OPERATIONAL 10.0.0.4 09w3d00h +ipv4 10.0.0.5 OPERATIONAL 10.0.0.5 09w2d23h +ipv4 10.0.0.7 OPERATIONAL 10.0.0.7 03w0d01h +ipv4 10.0.0.8 OPERATIONAL 10.0.0.8 01w3d02h +``` + +- “show mpls ldp binding” for checking mpls label assignment + +``` none +vyos@VyOS-P1:~$ show mpls ldp discovery +AF Destination Nexthop Local Label Remote Label In Use +ipv4 10.0.0.1/32 10.0.0.1 23 imp-null yes +ipv4 10.0.0.1/32 10.0.0.4 23 20 no +ipv4 10.0.0.1/32 10.0.0.5 23 17 no +ipv4 10.0.0.1/32 10.0.0.7 23 16 no +ipv4 10.0.0.1/32 10.0.0.8 23 16 no +ipv4 10.0.0.2/32 10.0.0.1 20 16 no +ipv4 10.0.0.2/32 10.0.0.4 20 22 no +ipv4 10.0.0.2/32 10.0.0.5 20 24 yes +ipv4 10.0.0.2/32 10.0.0.7 20 17 no +ipv4 10.0.0.2/32 10.0.0.8 20 17 no +ipv4 10.0.0.3/32 10.0.0.1 imp-null 17 no +ipv4 10.0.0.3/32 10.0.0.4 imp-null 16 no +ipv4 10.0.0.3/32 10.0.0.5 imp-null 18 no +ipv4 10.0.0.3/32 10.0.0.7 imp-null 18 no +ipv4 10.0.0.3/32 10.0.0.8 imp-null 18 no +ipv4 10.0.0.4/32 10.0.0.1 16 18 no +ipv4 10.0.0.4/32 10.0.0.4 16 imp-null yes +ipv4 10.0.0.4/32 10.0.0.5 16 19 no +ipv4 10.0.0.4/32 10.0.0.7 16 19 no +ipv4 10.0.0.4/32 10.0.0.8 16 19 no +ipv4 10.0.0.5/32 10.0.0.1 21 19 no +ipv4 10.0.0.5/32 10.0.0.4 21 17 no +ipv4 10.0.0.5/32 10.0.0.5 21 imp-null yes +ipv4 10.0.0.5/32 10.0.0.7 21 20 no +ipv4 10.0.0.5/32 10.0.0.8 21 20 no +ipv4 10.0.0.6/32 10.0.0.1 17 20 no +ipv4 10.0.0.6/32 10.0.0.4 17 23 yes +ipv4 10.0.0.6/32 10.0.0.5 17 21 yes +ipv4 10.0.0.6/32 10.0.0.7 17 21 no +ipv4 10.0.0.6/32 10.0.0.8 17 21 no +ipv4 10.0.0.7/32 10.0.0.1 22 21 no +ipv4 10.0.0.7/32 10.0.0.4 22 18 no +ipv4 10.0.0.7/32 10.0.0.5 22 20 no +ipv4 10.0.0.7/32 10.0.0.7 22 imp-null yes +ipv4 10.0.0.7/32 10.0.0.8 22 22 no +ipv4 10.0.0.8/32 10.0.0.1 24 22 no +ipv4 10.0.0.8/32 10.0.0.4 24 19 no +ipv4 10.0.0.8/32 10.0.0.5 24 16 no +ipv4 10.0.0.8/32 10.0.0.7 24 22 no +ipv4 10.0.0.8/32 10.0.0.8 24 imp-null yes +ipv4 10.0.0.9/32 10.0.0.1 18 23 no +ipv4 10.0.0.9/32 10.0.0.4 18 21 yes +ipv4 10.0.0.9/32 10.0.0.5 18 22 no +ipv4 10.0.0.9/32 10.0.0.7 18 23 no +ipv4 10.0.0.9/32 10.0.0.8 18 23 no +ipv4 10.0.0.10/32 10.0.0.1 19 24 no +ipv4 10.0.0.10/32 10.0.0.4 19 24 yes +ipv4 10.0.0.10/32 10.0.0.5 19 23 yes +ipv4 10.0.0.10/32 10.0.0.7 19 24 no +ipv4 10.0.0.10/32 10.0.0.8 19 24 no +``` + +Now we’re checking iBGP status and routes from route-reflector +nodes to other devices: + +- “show bgp ipv4 vpn summary” for checking BGP VPNv4 neighbors: + +``` none +vyos@VyOS-RR1:~$ show bgp ipv4 vpn summary +BGP router identifier 10.0.0.1, local AS number 65001 vrf-id 0 +BGP table version 0 +RIB entries 9, using 1728 bytes of memory +Peers 4, using 85 KiB of memory +Peer groups 1, using 64 bytes of memory + +Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd PfxSnt +10.0.0.7 4 65001 7719 7733 0 0 0 5d07h56m 2 10 +10.0.0.8 4 65001 7715 7724 0 0 0 5d08h28m 4 10 +10.0.0.9 4 65001 7713 7724 0 0 0 5d08h28m 2 10 +10.0.0.10 4 65001 7713 7724 0 0 0 5d08h28m 2 10 + +Total number of neighbors 4 +``` + +- “show bgp ipv4 vpn” for checking all VPNv4 prefixes information: + +``` none +vyos@VyOS-RR1:~$ show bgp ipv4 vpn +BGP table version is 2, local router ID is 10.0.0.1, vrf id 0 +Default local pref 100, local AS 65001 +Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, + i internal, r RIB-failure, S Stale, R Removed +Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self +Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path +Route Distinguisher: 10.50.50.1:1011 +*>i10.50.50.0/24 10.0.0.7 0 100 0 i + UN=10.0.0.7 EC{65035:1011} label=80 type=bgp, subtype=0 +*>i80.80.80.80/32 10.0.0.7 0 100 0 65035 i + UN=10.0.0.7 EC{65035:1011} label=80 type=bgp, subtype=0 +Route Distinguisher: 10.60.60.1:1011 +*>i10.60.60.0/24 10.0.0.10 0 100 0 i + UN=10.0.0.10 EC{65035:1011} label=80 type=bgp, subtype=0 +*>i90.90.90.90/32 10.0.0.10 0 100 0 65035 i + UN=10.0.0.10 EC{65035:1011} label=80 type=bgp, subtype=0 +Route Distinguisher: 10.80.80.1:1011 +*>i10.80.80.0/24 10.0.0.8 0 100 0 i + UN=10.0.0.8 EC{65035:1030} label=80 type=bgp, subtype=0 +*>i100.100.100.100/32 + 10.0.0.8 0 100 0 65035 i + UN=10.0.0.8 EC{65035:1030} label=80 type=bgp, subtype=0 +Route Distinguisher: 172.16.80.1:2011 +*>i10.110.110.0/24 10.0.0.8 0 100 0 65050 i + UN=10.0.0.8 EC{65050:2011} label=81 type=bgp, subtype=0 +*>i172.16.80.0/24 10.0.0.8 0 100 0 i + UN=10.0.0.8 EC{65050:2011} label=81 type=bgp, subtype=0 +Route Distinguisher: 172.16.100.1:2011 +*>i10.210.210.0/24 10.0.0.9 0 100 0 65050 i + UN=10.0.0.9 EC{65050:2011} label=80 type=bgp, subtype=0 +*>i172.16.100.0/24 10.0.0.9 0 100 0 i + UN=10.0.0.9 EC{65050:2011} label=80 type=bgp, subtype=0 +``` + +- “show bgp ipv4 vpn x.x.x.x/x” for checking best path selected + for specific VPNv4 destination + +``` none +vyos@VyOS-RR1:~$ show bgp ipv4 vpn 10.0.0.100/32 +BGP routing table entry for 10.80.80.1:1011:10.0.0.100/32 +not allocated +Paths: (1 available, best #1) + Advertised to non peer-group peers: + 10.0.0.7 10.0.0.8 10.0.0.9 10.0.0.10 + 65035, (Received from a RR-client) + 10.0.0.8 from 10.0.0.8 (10.0.0.8) + Origin incomplete, metric 0, localpref 100, valid, internal, best (First path received) + Extended Community: RT:65035:1030 + Remote label: 80 + Last update: Tue Oct 19 13:45:32 202 +``` + +Also we can verify how PE devices receives VPNv4 networks from the RRs +and installing them to the specific customer VRFs: + +- “show bgp ipv4 vpn summary” for checking iBGP neighbors against + route-reflector devices: + +``` none +vyos@VyOS-PE1:~$ show bgp ipv4 vpn summary +BGP router identifier 10.0.0.7, local AS number 65001 vrf-id 0 +BGP table version 0 +RIB entries 9, using 1728 bytes of memory +Peers 2, using 43 KiB of memory +Peer groups 1, using 64 bytes of memory + +Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd PfxSnt +10.0.0.1 4 65001 8812 8794 0 0 0 01:18:42 8 2 +10.0.0.2 4 65001 8800 8792 0 0 0 6d02h27m 8 2 +``` + +- “show bgp vrf all” for checking all the prefix learning on BGP + within VRFs: + +``` none +vyos@VyOS-PE1:~$ show bgp vrf all + +Instance default: +No BGP prefixes displayed, 0 exist + +Instance BLUE_SPOKE: +BGP table version is 8, local router ID is 10.50.50.1, vrf id 6 +Default local pref 100, local AS 65001 +Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, + i internal, r RIB-failure, S Stale, R Removed +Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self +Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path +* 10.50.50.0/24 0.0.0.0 0 32768 ? +*> 0.0.0.0 0 32768 i +*> 10.80.80.0/24 10.0.0.8@0< 0 100 0 i +* 10.0.0.8@0< 0 100 0 i +*> 10.0.0.80/32 10.50.50.2 0 0 65035 i +*> 10.0.0.100/32 + 10.0.0.8@0< 0 100 0 65035 ? +* 10.0.0.8@0< 0 100 0 65035 ? +``` + +- “show bgp vrf BLUE_SPOKE summary” for checking EBGP neighbor + information between PE and CE: + +``` none +vyos@VyOS-PE1:~$ show bgp vrf BLUE_SPOKE summary + + +IPv4 Unicast Summary: +BGP router identifier 10.50.50.1, local AS number 65001 vrf-id 6 +BGP table version 8 +RIB entries 7, using 1344 bytes of memory +Peers 1, using 21 KiB of memory + +Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd PfxSnt +10.50.50.2 4 65035 9019 9023 0 0 0 6d06h12m 1 4 + +Total number of neighbors 1 +``` + +- “show ip route vrf BLUE_SPOKE” for viewing the RIB in our Spoke PE. + Using this command we are also able to check the transport and + customer label (inner/outer) for Hub network prefix (10.0.0.100/32): + +``` none +vyos@VyOS-PE1:~$ show ip route vrf BLUE_SPOKE + +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + +VRF BLUE_SPOKE: +K>* 0.0.0.0/0 [255/8192] unreachable (ICMP unreachable), 03w0d23h +C>* 10.50.50.0/24 is directly connected, eth3, 03w0d23h +B> 10.80.80.0/24 [200/0] via 10.0.0.8 (vrf default) (recursive), label 80, weight 1, 04:22:00 + * via 172.16.90.1, eth0 (vrf default), label 24/80, weight 1, 04:22:00 +B>* 10.0.0.80/32 [20/0] via 10.50.50.2, eth3, weight 1, 6d05h30m +B> 10.0.0.100/32 [200/0] via 10.0.0.8 (vrf default) (recursive), label 80, weight 1, 04:22:00 + * via 172.16.90.1, eth0 (vrf default), label 24/80, weight 1, 04:22:00 +``` + +- “show bgp ipv4 vpn x.x.x.x/32” for checking the best-path to the + specific VPNv4 destination including extended community and + remotelabel information. This procedure is the same on all Spoke nodes: + +``` none +vyos@VyOS-PE1:~$ show bgp ipv4 vpn 10.0.0.100/32 +BGP routing table entry for 10.80.80.1:1011:10.0.0.100/32 +not allocated +Paths: (2 available, best #1) + Not advertised to any peer + 65035 + 10.0.0.8 from 10.0.0.1 (10.0.0.8) + Origin incomplete, metric 0, localpref 100, valid, internal, best (Neighbor IP) + Extended Community: RT:65035:1030 + Originator: 10.0.0.8, Cluster list: 10.0.0.1 + Remote label: 80 + Last update: Tue Oct 19 13:45:26 2021 + 65035 + 10.0.0.8 from 10.0.0.2 (10.0.0.8) + Origin incomplete, metric 0, localpref 100, valid, internal + Extended Community: RT:65035:1030 + Originator: 10.0.0.8, Cluster list: 10.0.0.1 + Remote label: 80 + Last update: Wed Oct 13 12:39:34 202 +``` + +Now, let’s check routing information on out Hub PE: + +- “show bgp ipv4 vpn summary” for checking iBGP neighbors again + VyOS-RR1/RR2 + +``` none +vyos@VyOS-PE2:~$ show bgp ipv4 vpn summary +BGP router identifier 10.0.0.8, local AS number 65001 vrf-id 0 +BGP table version 0 +RIB entries 9, using 1728 bytes of memory +Peers 2, using 43 KiB of memory +Peer groups 1, using 64 bytes of memory + +Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd PfxSnt +10.0.0.1 4 65001 15982 15949 0 0 0 05:41:28 6 4 +10.0.0.2 4 65001 9060 9054 0 0 0 6d06h47m 6 4 + +Total number of neighbors +``` + +- “show bgp vrf all” for checking all the prefixes learning on BGP + +``` none +vyos@VyOS-PE2:~$ show bgp vrf all + +Instance default: +No BGP prefixes displayed, 0 exist + +Instance BLUE_HUB: +BGP table version is 50, local router ID is 10.80.80.1, vrf id 8 +Default local pref 100, local AS 65001 +Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, + i internal, r RIB-failure, S Stale, R Removed +Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self +Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path +*> 10.50.50.0/24 10.0.0.7@0< 0 100 0 i +* 10.0.0.7@0< 0 100 0 i +*> 10.60.60.0/24 10.0.0.10@0< 0 100 0 i +* 10.0.0.10@0< 0 100 0 i +* 10.80.80.0/24 10.80.80.2 0 0 65035 ? +* 0.0.0.0 0 32768 i +*> 0.0.0.0 0 32768 ? +*> 10.110.110.0/24 172.16.80.2@9< 0 0 65050 i +*> 10.210.210.0/24 10.0.0.9@0< 0 100 0 65050 i +* 10.0.0.9@0< 0 100 0 65050 i +*> 10.0.0.80/32 10.0.0.7@0< 0 100 0 65035 i +* 10.0.0.7@0< 0 100 0 65035 i +*> 10.0.0.90/32 10.0.0.10@0< 0 100 0 65035 i +* 10.0.0.10@0< 0 100 0 65035 i +*> 10.0.0.100/32 + 10.80.80.2 0 0 65035 ? +*> 172.16.80.0/24 0.0.0.0@9< 0 32768 ? + 0.0.0.0@9< 0 32768 i +*> 172.16.100.0/24 10.0.0.9@0< 0 100 0 i +* 10.0.0.9@0< 0 100 0 i +``` + +- “show bgp vrf BLUE_HUB summary” for checking EBGP neighbor + CE Hub device + +``` none +vyos@VyOS-PE2:~$ show bgp vrf BLUE_HUB summary + +IPv4 Unicast Summary: +BGP router identifier 10.80.80.1, local AS number 65001 vrf-id 8 +BGP table version 50 +RIB entries 19, using 3648 bytes of memory +Peers 1, using 21 KiB of memory + +Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd PfxSnt +10.80.80.2 4 65035 15954 15972 0 0 0 01w4d01h 2 10 +``` + +- “show ip route vrf BLUE_HUB” to view the RIB in our Hub PE. + With this command we are able to check the transport and + customer label (inner/outer) for network spokes prefixes + 10.0.0.80/32 - 10.0.0.90/32 + +``` none +vyos@VyOS-PE2:~$ show ip route vrf BLUE_HUB +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup +VRF BLUE_HUB: +K>* 0.0.0.0/0 [255/8192] unreachable (ICMP unreachable), 01w4d01h +B> 10.50.50.0/24 [200/0] via 10.0.0.7 (vrf default) (recursive), label 144, weight 1, 05:53:15 + * via 172.16.100.1, eth1 (vrf default), label 22/144, weight 1, 05:53:15 +B> 10.60.60.0/24 [200/0] via 10.0.0.10 (vrf default) (recursive), label 144, weight 1, 05:53:15 + * via 172.16.110.1, eth0 (vrf default), label 23/144, weight 1, 05:53:15 +C>* 10.80.80.0/24 is directly connected, eth3, 01w4d01h +B>* 10.110.110.0/24 [200/0] via 172.16.80.2, eth2 (vrf GREEN), weight 1, 01w4d01h +B> 10.210.210.0/24 [200/0] via 10.0.0.9 (vrf default) (recursive), label 144, weight 1, 05:53:15 + * via 172.16.100.1, eth1 (vrf default), label 18/144, weight 1, 05:53:15 + * via 172.16.110.1, eth0 (vrf default), label 22/144, weight 1, 05:53:15 +B> 10.0.0.80/32 [200/0] via 10.0.0.7 (vrf default) (recursive), label 144, weight 1, 05:53:15 + * via 172.16.100.1, eth1 (vrf default), label 22/144, weight 1, 05:53:15 +B> 10.0.0.90/32 [200/0] via 10.0.0.10 (vrf default) (recursive), label 144, weight 1, 05:53:15 + * via 172.16.110.1, eth0 (vrf default), label 23/144, weight 1, 05:53:15 +B>* 10.0.0.100/32 [20/0] via 10.80.80.2, eth3, weight 1, 01w4d01h +B>* 172.16.80.0/24 [200/0] is directly connected, eth2 (vrf GREEN), weight 1, 01w4d01h +B> 172.16.100.0/24 [200/0] via 10.0.0.9 (vrf default) (recursive), label 144, weight 1, 05:53:15 + * via 172.16.100.1, eth1 (vrf default), label 18/144, weight 1, 05:53:15 + * via 172.16.110.1, eth0 (vrf default), label 22/144, weight 1, 05:53:15 +``` + +- “show bgp ipv4 vpn x.x.x.x/32” for checking best-path, + extended community and remote label of specific destination + +``` none +vyos@VyOS-PE2:~$ show bgp ipv4 vpn 10.0.0.80/32 +BGP routing table entry for 10.50.50.1:1011:10.0.0.80/32 +not allocated +Paths: (2 available, best #1) + Not advertised to any peer + 65035 + 10.0.0.7 from 10.0.0.1 (10.0.0.7) + Origin IGP, metric 0, localpref 100, valid, internal, best (Neighbor IP) + Extended Community: RT:65035:1011 + Originator: 10.0.0.7, Cluster list: 10.0.0.1 + Remote label: 144 + Last update: Tue Oct 19 13:45:30 2021 + 65035 + 10.0.0.7 from 10.0.0.2 (10.0.0.7) + Origin IGP, metric 0, localpref 100, valid, internal + Extended Community: RT:65035:1011 + Originator: 10.0.0.7, Cluster list: 10.0.0.1 + Remote label: 144 + Last update: Wed Oct 13 12:39:37 2021 + +vyos@VyOS-PE2:~$ show bgp ipv4 vpn 10.0.0.90/32 +BGP routing table entry for 10.60.60.1:1011:10.0.0.90/32 +not allocated +Paths: (2 available, best #1) + Not advertised to any peer + 65035 + 10.0.0.10 from 10.0.0.1 (10.0.0.10) + Origin IGP, metric 0, localpref 100, valid, internal, best (Neighbor IP) + Extended Community: RT:65035:1011 + Originator: 10.0.0.10, Cluster list: 10.0.0.1 + Remote label: 144 + Last update: Tue Oct 19 13:45:30 2021 + 65035 + 10.0.0.10 from 10.0.0.2 (10.0.0.10) + Origin IGP, metric 0, localpref 100, valid, internal + Extended Community: RT:65035:1011 + Originator: 10.0.0.10, Cluster list: 10.0.0.1 + Remote label: 144 + Last update: Wed Oct 13 12:45:44 2021 +``` + +Finally, let’s check the reachability between CEs: + +- VyOS-CE1-SPOKE -----\> VyOS-CE-HUB + +``` none +# check rib +vyos@VyOS-CE1-SPOKE:~$ show ip route +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + +B 10.50.50.0/24 [20/0] via 10.50.50.1 inactive, weight 1, 6d07h53m +C>* 10.50.50.0/24 is directly connected, eth0, 09w0d00h +B>* 10.80.80.0/24 [20/0] via 10.50.50.1, eth0, weight 1, 6d07h53m +C>* 10.0.0.80/32 is directly connected, dum20, 09w0d00h +B>* 10.0.0.100/32 [20/0] via 10.50.50.1, eth0, weight 1, 6d07h53m + +# check icmp +vyos@VyOS-CE1-SPOKE:~$ ping 10.0.0.100 interface 10.0.0.80 +PING 10.0.0.100 (10.0.0.100) from 10.0.0.80 : 56(84) bytes of data. +64 bytes from 10.0.0.100: icmp_seq=1 ttl=62 time=6.52 ms +64 bytes from 10.0.0.100: icmp_seq=2 ttl=62 time=4.13 ms +64 bytes from 10.0.0.100: icmp_seq=3 ttl=62 time=4.04 ms +64 bytes from 10.0.0.100: icmp_seq=4 ttl=62 time=4.03 ms +^C +--- 10.0.0.100 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 8ms +rtt min/avg/max/mdev = 4.030/4.680/6.518/1.064 ms + +# check network path +vyos@VyOS-CE1-SPOKE:~$ traceroute 10.0.0.100 +traceroute to 10.0.0.100 (10.0.0.100), 30 hops max, 60 byte packets + 1 10.50.50.1 (10.50.50.1) 1.041 ms 1.252 ms 1.835 ms + 2 * * * + 3 10.0.0.100 (10.0.0.100) 9.225 ms 9.159 ms 9.121 m +``` + +- VyOS-CE-HUB -------\> VyOS-CE1-SPOKE +- VyOS-CE-HUB -------\> VyOS-CE2-SPOKE + +``` none +# check rib +vyos@VyOS-CE-HUB:~$ show ip route +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + +B>* 10.50.50.0/24 [20/0] via 10.80.80.1, eth0, weight 1, 6d08h04m +B>* 10.60.60.0/24 [20/0] via 10.80.80.1, eth0, weight 1, 6d08h35m +C>* 10.80.80.0/24 is directly connected, eth0, 01w6d07h +B>* 10.110.110.0/24 [20/0] via 10.80.80.1, eth0, weight 1, 01w4d02h +B>* 10.210.210.0/24 [20/0] via 10.80.80.1, eth0, weight 1, 6d08h35m +B>* 10.0.0.80/32 [20/0] via 10.80.80.1, eth0, weight 1, 6d08h04m +B>* 10.0.0.90/32 [20/0] via 10.80.80.1, eth0, weight 1, 6d08h35m +C>* 10.0.0.100/32 is directly connected, dum20, 01w6d07h +B>* 172.16.80.0/24 [20/0] via 10.80.80.1, eth0, weight 1, 01w4d02h +B>* 172.16.100.0/24 [20/0] via 10.80.80.1, eth0, weight 1, 6d08h35m + +# check icmp +vyos@VyOS-CE-HUB:~$ ping 10.0.0.80 interface 10.0.0.100 c 4 +PING 10.0.0.80 (10.0.0.80) from 10.0.0.100 : 56(84) bytes of data. +64 bytes from 10.0.0.80: icmp_seq=1 ttl=62 time=3.31 ms +64 bytes from 10.0.0.80: icmp_seq=2 ttl=62 time=4.23 ms +64 bytes from 10.0.0.80: icmp_seq=3 ttl=62 time=3.89 ms +64 bytes from 10.0.0.80: icmp_seq=4 ttl=62 time=3.22 ms + +--- 10.0.0.80 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 9ms +rtt min/avg/max/mdev = 3.218/3.661/4.226/0.421 ms + +vyos@VyOS-CE-HUB:~$ ping 10.0.0.90 interface 10.0.0.100 c 4 +PING 10.0.0.90 (10.0.0.90) from 10.0.0.100 : 56(84) bytes of data. +64 bytes from 10.0.0.90: icmp_seq=1 ttl=62 time=7.46 ms +64 bytes from 10.0.0.90: icmp_seq=2 ttl=62 time=4.43 ms +64 bytes from 10.0.0.90: icmp_seq=3 ttl=62 time=4.60 ms +^C +--- 10.0.0.90 ping statistics --- +3 packets transmitted, 3 received, 0% packet loss, time 6ms +rtt min/avg/max/mdev = 4.430/5.498/7.463/1.391 ms + +# check network path +vyos@VyOS-CE-HUB:~$ traceroute 10.0.0.80 +traceroute to 10.0.0.80 (10.0.0.80), 30 hops max, 60 byte packets + 1 10.80.80.1 (10.80.80.1) 1.563 ms 1.341 ms 1.075 ms + 2 * * * + 3 10.0.0.80 (10.0.0.80) 8.125 ms 8.019 ms 7.781 ms + +vyos@VyOS-CE-HUB:~$ traceroute 10.0.0.90 +traceroute to 10.0.0.90 (10.0.0.90), 30 hops max, 60 byte packets + 1 10.80.80.1 (10.80.80.1) 1.305 ms 1.137 ms 1.097 ms + 2 * * * + 3 * * * + 4 10.0.0.90 (10.0.0.90) 9.358 ms 9.325 ms 9.292 ms +``` + +- VyOS-CE2-SPOKE -------\> VyOS-CE-HUB + +``` none +# check rib +vyos@rt-ce2-SPOKE:~$ show ip route +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + +B 10.60.60.0/24 [20/0] via 10.60.60.1 inactive, weight 1, 02w6d00h +C>* 10.60.60.0/24 is directly connected, eth0, 02w6d00h +B>* 10.80.80.0/24 [20/0] via 10.60.60.1, eth0, weight 1, 6d08h46m +C>* 10.0.0.90/32 is directly connected, dum20, 02w6d00h +B>* 10.0.0.100/32 [20/0] via 10.60.60.1, eth0, weight 1, 6d08h46m + +# check icmp +vyos@rt-ce2-SPOKE:~$ ping 10.0.0.100 interface 10.0.0.90 c 4 +PING 10.0.0.100 (10.0.0.100) from 10.0.0.90 : 56(84) bytes of data. +64 bytes from 10.0.0.100: icmp_seq=1 ttl=62 time=4.97 ms +64 bytes from 10.0.0.100: icmp_seq=2 ttl=62 time=4.45 ms +64 bytes from 10.0.0.100: icmp_seq=3 ttl=62 time=4.20 ms +64 bytes from 10.0.0.100: icmp_seq=4 ttl=62 time=4.29 ms + +--- 10.0.0.100 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 9ms +rtt min/avg/max/mdev = 4.201/4.476/4.971/0.309 ms + +# check network path +vyos@rt-ce2-SPOKE:~$ traceroute 10.0.0.100 +traceroute to 10.0.0.100 (10.0.0.100), 30 hops max, 60 byte packets + 1 10.60.60.1 (10.60.60.1) 1.343 ms 1.190 ms 1.152 ms + 2 * * * + 3 * * * + 4 10.0.0.100 (10.0.0.100) 7.504 ms 7.480 ms 7.488 ms +``` + +**Note:** At the moment, trace mpls doesn’t show labels/paths. So we’ll see \* \* \* for the transit routers of the mpls backbone. diff --git a/docs/configexamples/md-lac-lns.md b/docs/configexamples/md-lac-lns.md new file mode 100644 index 00000000..125f5ab6 --- /dev/null +++ b/docs/configexamples/md-lac-lns.md @@ -0,0 +1,167 @@ +lastproofread +2024-02-21 + +# PPPoE over L2TP + +This document is to describe a basic setup using PPPoE over L2TP. +LAC and LNS are components of the broadband topology. +LAC - L2TP access concentrator +LNS - L2TP Network Server +LAC and LNS forms L2TP tunnel. LAC receives packets from PPPoE clients and +forward them to LNS. LNS is the termination point that comes from PPP packets +from the remote client. + +In this example we use VyOS 1.5 as LNS and Cisco IOS as LAC. +All users with domain **vyos.io** will be tunneled to LNS via L2TP. + +## Network Topology + +<img src="/_static/images/lac-lns-diagram.webp" class="align-center" style="width:60.0%" alt="Network Topology Diagram" /> + +## Configurations + +### LAC + +``` none +aaa new-model +! +aaa authentication ppp default local +! +vpdn enable +vpdn aaa attribute nas-ip-address vpdn-nas +! +vpdn-group LAC + request-dialin + protocol l2tp + domain vyos.io + initiate-to ip 192.168.139.100 + source-ip 192.168.139.101 + local name LAC + l2tp tunnel password 0 test123 +! +bba-group pppoe MAIN-BBA + virtual-template 1 +! +interface GigabitEthernet0/0 + description To LNS + ip address 192.168.139.101 255.255.255.0 + duplex auto + speed auto + media-type rj45 +! +interface GigabitEthernet0/1 + description To PPPoE clients + no ip address + duplex auto + speed auto + media-type rj45 + pppoe enable group MAIN-BBA +! +interface Virtual-Template1 + description pppoe MAIN-BBA + no ip address + no peer default ip address + ppp mtu adaptive + ppp authentication chap +! +``` + +### LNS + +% stop_vyoslinter + +``` none +set interfaces ethernet eth0 address '192.168.139.100/24' +set nat source rule 100 outbound-interface name 'eth0' +set nat source rule 100 source address '10.0.0.0/24' +set nat source rule 100 translation address 'masquerade' +set protocols static route 0.0.0.0/0 next-hop 192.168.139.2 +set vpn l2tp remote-access authentication mode 'radius' +set vpn l2tp remote-access authentication radius server 192.168.139.110 key 'radiustest' +set vpn l2tp remote-access client-ip-pool TEST-POOL range '10.0.0.2-10.0.0.100' +set vpn l2tp remote-access default-pool 'TEST-POOL' +set vpn l2tp remote-access gateway-address '10.0.0.1' +set vpn l2tp remote-access lns host-name 'LAC' +set vpn l2tp remote-access lns shared-secret 'test123' +set vpn l2tp remote-access name-server '8.8.8.8' +set vpn l2tp remote-access ppp-options disable-ccp +``` + +% start_vyoslinter + +:::{note} +This setup requires the Compression Control Protocol (CCP) +being disabled, the command `set vpn l2tp remote-access ppp-options disable-ccp` +accomplishes that. +::: + +### Client + +In this lab we use Windows PPPoE client. + +<img src="/_static/images/lac-lns-winclient.webp" class="align-center" style="width:100.0%" alt="Window PPPoE Client Configuration" /> + +### Monitoring + +Monitoring on LNS side + +``` none +vyos@vyos:~$ show l2tp-server sessions + ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes +--------+--------------+----------+-----+--------+-----------------+------------+--------+----------+-----------+---------- + l2tp0 | test@vyos.io | 10.0.0.2 | | | 192.168.139.101 | | active | 00:00:35 | 188.4 KiB | 9.3 MiB +``` + +Monitoring on LAC side + +``` none +Router#show pppoe session + 1 session in FORWARDED (FWDED) State + 1 session total +Uniq ID PPPoE RemMAC Port VT VA State + SID LocMAC VA-st Type + 1 1 000c.290b.20a6 Gi0/1 1 N/A FWDED + 0c58.88ac.0001 + +Router#show l2tp +L2TP Tunnel and Session Information Total tunnels 1 sessions 1 + +LocTunID RemTunID Remote Name State Remote Address Sessn L2TP Class/ + Count VPDN Group +23238 2640 LAC est 192.168.139.100 1 LAC + +LocID RemID TunID Username, Intf/ State Last Chg Uniq ID + Vcid, Circuit +25641 25822 23238 test@vyos.io, Gi0/1 est 00:05:36 1 +``` + +Monitoring on RADIUS Server side + +``` none +root@Radius:~# cat /var/log/freeradius/radacct/192.168.139.100/detail-20240221 +Wed Feb 21 13:37:17 2024 + User-Name = "test@vyos.io" + NAS-Port = 0 + NAS-Port-Id = "l2tp0" + NAS-Port-Type = Virtual + Service-Type = Framed-User + Framed-Protocol = PPP + Calling-Station-Id = "192.168.139.101" + Called-Station-Id = "192.168.139.100" + Acct-Status-Type = Start + Acct-Authentic = RADIUS + Acct-Session-Id = "45c731e169d9a4f1" + Acct-Session-Time = 0 + Acct-Input-Octets = 0 + Acct-Output-Octets = 0 + Acct-Input-Packets = 0 + Acct-Output-Packets = 0 + Acct-Input-Gigawords = 0 + Acct-Output-Gigawords = 0 + Framed-IP-Address = 10.0.0.2 + NAS-IP-Address = 192.168.139.100 + Event-Timestamp = "Feb 21 2024 13:37:17 UTC" + Tmp-String-9 = "ai:" + Acct-Unique-Session-Id = "ea6a1089816f19c0d0f1819bc61c3318" + Timestamp = 1708522637 +``` diff --git a/docs/configexamples/md-nmp.md b/docs/configexamples/md-nmp.md new file mode 100644 index 00000000..79b096ce --- /dev/null +++ b/docs/configexamples/md-nmp.md @@ -0,0 +1,42 @@ +lastproofread +2023-03-26 + +# NMP example + +Consider how to quickly set up NMP and VyOS for monitoring. +NMP is multi-vendor network monitoring from 'SolarWinds' built to scale and expand with the needs of your network. + +## Configuration 'VyOS' + +First prepare our VyOS router for connection to NMP. We have to set up the SNMP protocol and connectivity between the router and NMP. + +% stop_vyoslinter + +``` none +set interfaces ethernet eth0 address 'dhcp' +set system name-server '8.8.8.8' +set service snmp community router authorization 'test' +set service snmp community router network '0.0.0.0/0' +``` + +% start_vyoslinter + +## Configuration 'NMP' + +Next, you should just follow the pictures: + +<img src="/_static/images/nmp1.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +<img src="/_static/images/nmp2.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +<img src="/_static/images/nmp3.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +<img src="/_static/images/nmp4.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +<img src="/_static/images/nmp5.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +<img src="/_static/images/nmp6.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +<img src="/_static/images/nmp7.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +In the end, you'll get a powerful instrument for monitoring the VyOS systems. diff --git a/docs/configexamples/md-ospf-unnumbered.md b/docs/configexamples/md-ospf-unnumbered.md new file mode 100644 index 00000000..8fe92b39 --- /dev/null +++ b/docs/configexamples/md-ospf-unnumbered.md @@ -0,0 +1,114 @@ +lastproofread +2021-06-29 + +# OSPF unnumbered with ECMP + +General information can be found in the `routing-ospf` chapter. + +## Configuration + +- Router A: + +``` none +set interfaces ethernet eth0 address '10.0.0.1/24' +set interfaces ethernet eth1 address '192.168.0.1/32' +set interfaces ethernet eth1 ip ospf authentication md5 key-id 1 md5-key 'yourpassword' +set interfaces ethernet eth1 ip ospf network 'point-to-point' +set interfaces ethernet eth2 address '192.168.0.1/32' +set interfaces ethernet eth2 ip ospf authentication md5 key-id 1 md5-key 'yourpassword' +set interfaces ethernet eth2 ip ospf network 'point-to-point' +set interfaces loopback lo address '192.168.0.1/32' +set protocols ospf area 0.0.0.0 authentication 'md5' +set protocols ospf area 0.0.0.0 network '192.168.0.1/32' +set protocols ospf parameters router-id '192.168.0.1' +set protocols ospf redistribute connected +``` + +- Router B: + +``` none +set interfaces ethernet eth0 address '10.0.0.2/24' +set interfaces ethernet eth1 address '192.168.0.2/32' +set interfaces ethernet eth1 ip ospf authentication md5 key-id 1 md5-key 'yourpassword' +set interfaces ethernet eth1 ip ospf network 'point-to-point' +set interfaces ethernet eth2 address '192.168.0.2/32' +set interfaces ethernet eth2 ip ospf authentication md5 key-id 1 md5-key 'yourpassword' +set interfaces ethernet eth2 ip ospf network 'point-to-point' +set interfaces loopback lo address '192.168.0.2/32' +set protocols ospf area 0.0.0.0 authentication 'md5' +set protocols ospf area 0.0.0.0 network '192.168.0.2/32' +set protocols ospf parameters router-id '192.168.0.2' +set protocols ospf redistribute connected +``` + +## Results + +- Router A: + +``` none +vyos@vyos:~$ show interfaces +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +eth0 10.0.0.1/24 u/u +eth1 192.168.0.1/32 u/u +eth2 192.168.0.1/32 u/u +lo 127.0.0.1/8 u/u + 192.168.0.1/32 + ::1/128 +``` + +``` none +vyos@vyos:~$ show ip route +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued route, r - rejected route + +S>* 0.0.0.0/0 [210/0] via 10.0.0.254, eth0, 00:57:34 +O 10.0.0.0/24 [110/20] via 192.168.0.2, eth1 onlink, 00:13:21 + via 192.168.0.2, eth2 onlink, 00:13:21 +C>* 10.0.0.0/24 is directly connected, eth0, 00:57:35 +O 192.168.0.1/32 [110/0] is directly connected, lo, 00:48:53 +C * 192.168.0.1/32 is directly connected, eth2, 00:56:31 +C * 192.168.0.1/32 is directly connected, eth1, 00:56:31 +C>* 192.168.0.1/32 is directly connected, lo, 00:57:36 +O>* 192.168.0.2/32 [110/1] via 192.168.0.2, eth1 onlink, 00:29:03 + * via 192.168.0.2, eth2 onlink, 00:29:03 +``` + +- Router B: + +``` none +vyos@vyos:~$ show interfaces +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +eth0 10.0.0.2/24 u/u +eth1 192.168.0.2/32 u/u +eth2 192.168.0.2/32 u/u +lo 127.0.0.1/8 u/u + 192.168.0.2/32 + ::1/128 +``` + +``` none +vyos@vyos:~$ show ip route +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued route, r - rejected route + +S>* 0.0.0.0/0 [210/0] via 10.0.0.254, eth0, 00:57:34 +O 10.0.0.0/24 [110/20] via 192.168.0.1, eth1 onlink, 00:13:21 + via 192.168.0.1, eth2 onlink, 00:13:21 +C>* 10.0.0.0/24 is directly connected, eth0, 00:57:35 +O 192.168.0.2/32 [110/0] is directly connected, lo, 00:48:53 +C * 192.168.0.2/32 is directly connected, eth2, 00:56:31 +C * 192.168.0.2/32 is directly connected, eth1, 00:56:31 +C>* 192.168.0.2/32 is directly connected, lo, 00:57:36 +O>* 192.168.0.1/32 [110/1] via 192.168.0.1, eth1 onlink, 00:29:03 + * via 192.168.0.1, eth2 onlink, 00:29:03 +``` diff --git a/docs/configexamples/md-pppoe-ipv6-basic.md b/docs/configexamples/md-pppoe-ipv6-basic.md new file mode 100644 index 00000000..7d158031 --- /dev/null +++ b/docs/configexamples/md-pppoe-ipv6-basic.md @@ -0,0 +1,104 @@ +lastproofread +2021-06-29 + +# PPPoE IPv6 Basic Setup for Home Network + +This document is to describe a basic setup using PPPoE with DHCPv6-PD + +SLAAC to construct a typical home network. The user can follow the steps +described here to quickly setup a working network and use this as a starting +point to further configure or fine-tune other settings. + +To achieve this, your ISP is required to support DHCPv6-PD. If you're not sure, +please contact your ISP for more information. + +## Network Topology + +<img src="/_static/images/pppoe-ipv6-pd-diagram.webp" class="align-center" style="width:60.0%" alt="Network Topology Diagram" /> + +## Configurations + +### PPPoE Setup + +``` none +set interfaces pppoe pppoe0 authentication password <YOUR PASSWORD> +set interfaces pppoe pppoe0 authentication username <YOUR USERNAME> +set interfaces pppoe pppoe0 service-name <YOUR SERVICENAME> +set interfaces pppoe pppoe0 source-interface 'eth0' +``` + +- Fill `password` and `user` with the credential provided by your ISP. +- `service-name` can be an arbitrary string. + +### DHCPv6-PD Setup + +During address configuration, in addition to assigning an address to the WAN +interface, ISP also provides a prefix to allow the router to configure addresses +of LAN interface and other nodes connecting to LAN, which is called prefix +delegation (PD). + +``` none +set interfaces pppoe pppoe0 ipv6 address autoconf +set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth1 address '100' +``` + +- Here we use the prefix to configure the address of eth1 (LAN) to form + `<prefix>::64`, where `64` is hexadecimal of address 100. +- For home network users, most of time ISP only provides /64 prefix, hence + there is no need to set SLA ID and prefix length. See `pppoe-interface` + for more information. + +### Router Advertisement + +We need to enable router advertisement for LAN network so that PC can receive +the prefix and use SLAAC to configure the address automatically. + +``` none +set service router-advert interface eth1 link-mtu '1492' +set service router-advert interface eth1 name-server <NAME SERVER> +set service router-advert interface eth1 prefix ::/64 valid-lifetime '172800' +``` + +- Set MTU in advertisement to 1492 because of PPPoE header overhead. +- Set DNS server address in the advertisement so that clients can obtain it by + using RDNSS option. Most operating systems (Windows, Linux, Mac) should + already support it. +- Here we set the prefix to `::/64` to indicate advertising any /64 prefix + the LAN interface is assigned. +- Since some ISPs disconnects continuous connection for every 2~3 days, we set + `valid-lifetime` to 2 days to allow PC for phasing out old address. + +### Basic Firewall + +To have basic protection while keeping IPv6 network functional, we need to: + +- Allow all established and related traffic for router and LAN +- Allow all icmpv6 packets for router and LAN +- Allow DHCPv6 packets for router + +``` none +set firewall ipv6 name WAN_IN default-action 'drop' +set firewall ipv6 name WAN_IN rule 10 action 'accept' +set firewall ipv6 name WAN_IN rule 10 state established 'enable' +set firewall ipv6 name WAN_IN rule 10 state related 'enable' +set firewall ipv6 name WAN_IN rule 20 action 'accept' +set firewall ipv6 name WAN_IN rule 20 protocol 'icmpv6' +set firewall ipv6 name WAN_LOCAL default-action 'drop' +set firewall ipv6 name WAN_LOCAL rule 10 action 'accept' +set firewall ipv6 name WAN_LOCAL rule 10 state established 'enable' +set firewall ipv6 name WAN_LOCAL rule 10 state related 'enable' +set firewall ipv6 name WAN_LOCAL rule 20 action 'accept' +set firewall ipv6 name WAN_LOCAL rule 20 protocol 'icmpv6' +set firewall ipv6 name WAN_LOCAL rule 30 action 'accept' +set firewall ipv6 name WAN_LOCAL rule 30 destination port '546' +set firewall ipv6 name WAN_LOCAL rule 30 protocol 'udp' +set firewall ipv6 name WAN_LOCAL rule 30 source port '547' +set firewall ipv6 forward filter rule 10 action jump +set firewall ipv6 forward filter rule 10 jump-target 'WAN_IN' +set firewall ipv6 forward filter rule 10 inbound-interface name 'pppoe0' +set firewall ipv6 input filter rule 10 action jump +set firewall ipv6 input filter rule 10 jump-target 'WAN_LOCAL' +set firewall ipv6 input filter rule 10 inbound-interface name 'pppoe0' +``` + +Note to allow the router to receive DHCPv6 response from ISP. We need to allow +packets with source port 547 (server) and destination port 546 (client). diff --git a/docs/configexamples/md-qos.md b/docs/configexamples/md-qos.md new file mode 100644 index 00000000..520200c5 --- /dev/null +++ b/docs/configexamples/md-qos.md @@ -0,0 +1,144 @@ +lastproofread +2023-02-18 + +# QoS example + +## Configuration 'dcsp' and shaper using QoS + +In this case, we'll try to make a simple lab using QoS and the general ability of the VyOS system. +We recommend you to go through the main article about [QoS](https://docs.vyos.io/en/latest/configuration/trafficpolicy/index.html) first. + +Using the general schema for example: + +<img src="/_static/images/qos1.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +We have four hosts on the local network 172.17.1.0/24. All hosts are labeled CS0 by default. We need to replace labels on all hosts except vpc8. +We will replace the labels on the nearest router “VyOS3” using the IP addresses of the sources. + +- 172.17.1.2 CS0 -\> CS4 +- 172.17.1.3 CS0 -\> CS5 +- 172.17.1.4 CS0 -\> CS6 +- 172.17.1.40 CS0 by default + +Next, we will replace only all CS4 labels on the “VyOS2” router. + +- CS4 -\> CS5 + +In the end, we will configure the traffic shaper using QoS mechanisms on the “VYOS2” router. + +## Configuration: + +Set IP addresses on all VPCs and a default gateway 172.17.1.1. We'll use in this case only static routes. +On the VyOS3 router, we need to change the 'dscp' labels for the VPCs. To do this, we use this configuration. + +``` none +set interfaces ethernet eth0 address '10.1.1.100/24' +set interfaces ethernet eth1 address '172.17.1.1/24' +set protocols static route 0.0.0.0/0 next-hop 10.1.1.1 +set qos policy shaper vyos3 class 10 match ADDRESS10 ip source address '172.17.1.2/32' +set qos policy shaper vyos3 class 10 set-dscp 'CS4' +set qos policy shaper vyos3 class 20 match ADDRESS20 ip source address '172.17.1.3/32' +set qos policy shaper vyos3 class 20 set-dscp 'CS5' +set qos policy shaper vyos3 class 30 match ADDRESS30 ip source address '172.17.1.4/32' +set qos policy shaper vyos3 class 30 set-dscp 'CS6' +set qos policy shaper vyos3 default bandwidth '10%' +set qos policy shaper vyos3 default ceiling '100%' +set qos policy shaper vyos3 default priority '7' +set qos policy shaper vyos3 default queue-type 'fair-queue' + set qos interface eth0 egress 'vyos3' +``` + +Main rules: + +- ADDRESS10 change CS0 -\> CS4 source 172.17.1.2/32 +- ADDRESS20 change CS0 -\> CS5 source 172.17.1.3/32 +- ADDRESS30 change CS0 -\> CS6 source 172.17.1.4/32 + +Check the result + +<img src="/_static/images/qos2.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +Before the interface eth0 on router VyOS3 + +<img src="/_static/images/qos3.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +After the interface eth0 on router VyOS3 + +<img src="/_static/images/qos4.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +On the router, VyOS4 set all traffic as CS4. We have to configure the default class and class for changing all labels from CS0 to CS4 + +``` none +set interfaces ethernet eth0 address '10.2.1.100/24' +set protocols static route 0.0.0.0/0 next-hop 10.2.1.1 +set qos policy shaper vyos4 class 10 bandwidth '100%' +set qos policy shaper vyos4 class 10 burst '15k' +set qos policy shaper vyos4 class 10 match ALL ether protocol 'all' +set qos policy shaper vyos4 class 10 queue-type 'fair-queue' +set qos policy shaper vyos4 class 10 set-dscp 'CS4' +set qos policy shaper vyos4 default bandwidth '10%' +set qos policy shaper vyos4 default burst '15k' +set qos policy shaper vyos4 default ceiling '100%' +set qos policy shaper vyos4 default priority '7' +set qos policy shaper vyos4 default queue-type 'fair-queue' + set qos interface eth0 egress 'vyos4' +``` + +Next on the router VyOS2 we will change labels on all incoming traffic only from CS4-\> CS6 + +<img src="/_static/images/qos5.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +``` none +set interfaces ethernet eth0 address '10.1.1.1/24' +set interfaces ethernet eth1 address '10.2.1.1/24' +set interfaces ethernet eth2 address '10.9.9.1/24' +set protocols static route 172.17.1.0/24 next-hop 10.1.1.100 +set qos policy shaper vyos2 class 10 bandwidth '100%' +set qos policy shaper vyos2 class 10 burst '15k' +set qos policy shaper vyos2 class 10 match VYOS2 ip dscp 'CS4' +set qos policy shaper vyos2 class 10 queue-type 'fair-queue' +set qos policy shaper vyos2 class 10 set-dscp 'CS5' +set qos policy shaper vyos2 default bandwidth '100%' +set qos policy shaper vyos2 default burst '15k' +set qos policy shaper vyos2 default ceiling '100%' +set qos policy shaper vyos2 default priority '7' +set qos policy shaper vyos2 default queue-type 'fair-queue' + set qos interface eth2 egress 'vyos2' +``` + +<img src="/_static/images/qos6.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +- 172.17.1.2/24 CS0 + +<img src="/_static/images/qos7.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +- 172.17.1.2/24 CS0 - \> CS4 + +<img src="/_static/images/qos8.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +- 172.17.1.2/24 CS4 - \> CS5 + +<img src="/_static/images/qos9.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +In the end, on the router “VyOS2” we will set outgoing bandwidth limits between the “VyOS3” and “VyOS1” routers. Let's set a limit for IP 10.1.1.100 = 5 Mbps(Tx). We will check the result of the work with the help of the “iPerf” utility. + +Set up bandwidth limits on the eth2 interface of the router “VyOS2”. + +``` none +vyos@vyos2# show qos policy shaper vyos2 class 20 +bandwidth 5mbit +description "for VyOS3 eth0" +match VyOS3 { + ip { + source { + address 10.1.1.100/32 + } + } +} +``` + +Check the result. + +<img src="/_static/images/qos10.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +As we see shaper is working and the traffic will not work over 5 Mbit/s. diff --git a/docs/configexamples/md-segment-routing-isis.md b/docs/configexamples/md-segment-routing-isis.md new file mode 100644 index 00000000..707d4f4b --- /dev/null +++ b/docs/configexamples/md-segment-routing-isis.md @@ -0,0 +1,273 @@ +lastproofread +2023-04-10 + +# Segment-routing IS-IS example + +When utilizing VyOS in an environment with Cisco IOS-XR gear you can use this +blue print as an initial setup to get MPLS ISIS-SR working between those two +devices.The lab was build using `EVE-NG (Emulated Virtual +Environment NG)`. + +<figure> +<img src="/_static/images/vyos-sr-isis.webp" alt="ISIS-SR network" /> +<figcaption>ISIS-SR example network</figcaption> +</figure> + +The below configuration is used as example where we keep focus on +VyOS-P1/VyOS-P2/XRv-P3 which we share the settings. + +## Configuration + +- VyOS-P1: + +``` none +set interfaces dummy dum0 address '192.0.2.1/32' +set interfaces ethernet eth1 address '192.0.2.5/30' +set interfaces ethernet eth1 mtu '8000' +set interfaces ethernet eth3 address '192.0.2.21/30' +set interfaces ethernet eth3 mtu '8000' +set protocols isis interface dum0 passive +set protocols isis interface eth1 network point-to-point +set protocols isis interface eth3 network point-to-point +set protocols isis level 'level-2' +set protocols isis log-adjacency-changes +set protocols isis metric-style 'wide' +set protocols isis net '49.0000.0000.0000.0001.00' +set protocols isis segment-routing maximum-label-depth '8' +set protocols isis segment-routing prefix 192.0.2.1/32 index value '1' +set protocols mpls interface 'eth1' +set protocols mpls interface 'eth3' +set system host-name 'P1-VyOS' +``` + +- XRv-P3: + +``` none +hostname P3-VyOS +interface Loopback0 + ipv4 address 192.0.2.3 255.255.255.255 +! +interface GigabitEthernet0/0/0/1 + mtu 8014 + ipv4 address 192.0.2.6 255.255.255.252 +! +interface GigabitEthernet0/0/0/2 + mtu 8014 + ipv4 address 192.0.2.18 255.255.255.252 +! +router isis VyOS + is-type level-2-only + net 49.0000.0000.0000.0003.00 + log adjacency changes + address-family ipv4 unicast + metric-style wide + segment-routing mpls + ! + interface Loopback0 + passive + address-family ipv4 unicast + prefix-sid index 3 + ! + ! + interface GigabitEthernet0/0/0/1 + point-to-point + address-family ipv4 unicast + ! + ! + interface GigabitEthernet0/0/0/2 + point-to-point + address-family ipv4 unicast + ! + ! +! +``` + +- VyOS-P2: + +``` none +set interfaces dummy dum0 address '192.0.2.2/32' +set interfaces ethernet eth2 address '192.0.2.17/30' +set interfaces ethernet eth2 mtu '8000' +set interfaces ethernet eth3 address '192.0.2.26/30' +set interfaces ethernet eth3 mtu '8000' +set protocols isis interface dum0 passive +set protocols isis interface eth2 network point-to-point +set protocols isis interface eth3 network point-to-point +set protocols isis level 'level-2' +set protocols isis log-adjacency-changes +set protocols isis metric-style 'wide' +set protocols isis net '49.0000.0000.0000.0002.00' +set protocols isis segment-routing maximum-label-depth '8' +set protocols isis segment-routing prefix 192.0.2.2/32 index value '2' +set protocols mpls interface 'eth2' +set protocols mpls interface 'eth3' +set system host-name 'P2-VyOS' +``` + +This gives us MPLS segment routing enabled and labels forwarding : + +``` none +vyos@P1-VyOS:~$ show mpls table +Inbound Label Type Nexthop Outbound Label +----------------------------------------------------------------- +15000 SR (IS-IS) 192.0.2.6 implicit-null +15001 SR (IS-IS) 192.0.2.22 implicit-null +15002 SR (IS-IS) fe80::5200:ff:fe04:3 implicit-null +16002 SR (IS-IS) 192.0.2.6 16002 +16003 SR (IS-IS) 192.0.2.6 implicit-null +16011 SR (IS-IS) 192.0.2.22 implicit-null + +vyos@P2-VyOS:~$ show mpls table +Inbound Label Type Nexthop Outbound Label +------------------------------------------------------- +15000 SR (IS-IS) 192.0.2.18 implicit-null +16001 SR (IS-IS) 192.0.2.18 16001 +16003 SR (IS-IS) 192.0.2.18 implicit-null +16011 SR (IS-IS) 192.0.2.18 16011 + +RP/0/0/CPU0:P3-VyOS#show mpls forwarding +Tue Mar 28 17:47:18.928 UTC +Local Outgoing Prefix Outgoing Next Hop Bytes +Label Label or ID Interface Switched +------ ----------- ------------------ ------------ --------------- ------------ +16001 Pop SR Pfx (idx 1) Gi0/0/0/1 192.0.2.5 0 +16002 Pop SR Pfx (idx 2) Gi0/0/0/2 192.0.2.17 0 +16011 16011 SR Pfx (idx 11) Gi0/0/0/1 192.0.2.5 0 +24000 Pop SR Adj (idx 1) Gi0/0/0/1 192.0.2.5 0 +24001 Pop SR Adj (idx 3) Gi0/0/0/1 192.0.2.5 0 +24002 Pop SR Adj (idx 1) Gi0/0/0/2 192.0.2.17 0 +24003 Pop SR Adj (idx 3) Gi0/0/0/2 192.0.2.17 0 +``` + +VyOS is able to check MSD per devices: + +``` none +vyos@P1-VyOS:~$ show isis segment-routing node +Area VyOS: +IS-IS L1 SR-Nodes: + +IS-IS L2 SR-Nodes: + +System ID SRGB SRLB Algorithm MSD +--------------------------------------------------------------- +0000.0000.0001 16000 - 23999 15000 - 15999 SPF 8 +0000.0000.0002 16000 - 23999 15000 - 15999 SPF 8 +0000.0000.0003 16000 - 23999 0 - 4294967295 SPF 10 +0000.0000.0011 16000 - 23999 15000 - 15999 SPF 8 + +vyos@P2-VyOS:~$ show isis segment-routing node +Area VyOS: + IS-IS L1 SR-Nodes: + + IS-IS L2 SR-Nodes: + + System ID SRGB SRLB Algorithm MSD + --------------------------------------------------------------- + 0000.0000.0001 16000 - 23999 15000 - 15999 SPF 8 + 0000.0000.0002 16000 - 23999 15000 - 15999 SPF 8 + 0000.0000.0003 16000 - 23999 0 - 4294967295 SPF 10 + 0000.0000.0011 16000 - 23999 15000 - 15999 SPF 8 +``` + +Here is the routing tables showing the MPLS segment routing label operations: + +``` none +vyos@P1-VyOS:~$ show ip route isis +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +I>* 192.0.2.2/32 [115/30] via 192.0.2.6, eth1, label 16002, weight 1, 1d03h18m +I>* 192.0.2.3/32 [115/10] via 192.0.2.6, eth1, label implicit-null, weight 1, 1d03h18m +I 192.0.2.4/30 [115/20] via 192.0.2.6, eth1 inactive, weight 1, 1d03h18m +I>* 192.0.2.11/32 [115/20] via 192.0.2.22, eth3, label implicit-null, weight 1, 1d02h47m +I>* 192.0.2.16/30 [115/20] via 192.0.2.6, eth1, weight 1, 1d03h18m +I 192.0.2.20/30 [115/20] via 192.0.2.22, eth3 inactive, weight 1, 1d02h48m +I>* 192.0.2.24/30 [115/30] via 192.0.2.6, eth1, weight 1, 1d03h18m + + +vyos@P2-VyOS:~$ show ip route isis +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +I>* 192.0.2.1/32 [115/30] via 192.0.2.18, eth2, label 16001, weight 1, 1d03h17m +I>* 192.0.2.3/32 [115/10] via 192.0.2.18, eth2, label implicit-null, weight 1, 1d03h17m +I>* 192.0.2.4/30 [115/20] via 192.0.2.18, eth2, weight 1, 1d03h17m +I>* 192.0.2.11/32 [115/40] via 192.0.2.18, eth2, label 16011, weight 1, 1d02h47m +I 192.0.2.16/30 [115/20] via 192.0.2.18, eth2 inactive, weight 1, 1d03h17m +I>* 192.0.2.20/30 [115/30] via 192.0.2.18, eth2, weight 1, 1d03h17m + +RP/0/0/CPU0:P3-VyOS#show route isis +Tue Mar 28 18:19:16.417 UTC + +i L2 192.0.2.1/32 [115/20] via 192.0.2.5, 1d03h, GigabitEthernet0/0/0/1 +i L2 192.0.2.2/32 [115/20] via 192.0.2.17, 1d03h, GigabitEthernet0/0/0/2 +i L2 192.0.2.11/32 [115/30] via 192.0.2.5, 1d02h, GigabitEthernet0/0/0/1 +i L2 192.0.2.20/30 [115/20] via 192.0.2.5, 1d03h, GigabitEthernet0/0/0/1 +i L2 192.0.2.24/30 [115/20] via 192.0.2.17, 1d03h, GigabitEthernet0/0/0/2 +``` + +Information about prefix-sid and label-operation from VyOS + +``` none +vyos@P1-VyOS:~$ show isis route prefix-sid +Area VyOS: +IS-IS L2 IPv4 routing table: + + Prefix Metric Interface Nexthop SID Label Op. + ---------------------------------------------------------------------- + 192.0.2.1/32 0 - - - - + 192.0.2.2/32 30 eth1 192.0.2.6 2 Swap(16002, 16002) + 192.0.2.3/32 10 eth1 192.0.2.6 3 Pop(16003) + 192.0.2.4/30 20 eth1 192.0.2.6 - - + 192.0.2.16/30 20 eth1 192.0.2.6 - - + 192.0.2.20/30 0 - - - - + 192.0.2.24/30 30 eth1 192.0.2.6 - - + + vyos@P2-VyOS:~$ show isis route prefix-sid + Area VyOS: + IS-IS L2 IPv4 routing table: + + Prefix Metric Interface Nexthop SID Label Op. + ----------------------------------------------------------------------- + 192.0.2.1/32 30 eth2 192.0.2.18 1 Swap(16001, 16001) + 192.0.2.2/32 0 - - - - + 192.0.2.3/32 10 eth2 192.0.2.18 3 Pop(16003) + 192.0.2.4/30 20 eth2 192.0.2.18 - - + 192.0.2.16/30 20 eth2 192.0.2.18 - - + 192.0.2.20/30 30 eth2 192.0.2.18 - - + 192.0.2.24/30 0 - - - - +``` + +Ping between VyOS-P1 / VyOS-P2 to confirm reachability: + +``` none +vyos@P1-VyOS:~$ ping 192.0.2.2 source-address 192.0.2.1 +PING 192.0.2.2 (192.0.2.2) from 192.0.2.1 : 56(84) bytes of data. +64 bytes from 192.0.2.2: icmp_seq=1 ttl=63 time=3.47 ms +64 bytes from 192.0.2.2: icmp_seq=2 ttl=63 time=2.06 ms +64 bytes from 192.0.2.2: icmp_seq=3 ttl=63 time=3.90 ms +64 bytes from 192.0.2.2: icmp_seq=4 ttl=63 time=3.87 ms +^C +--- 192.0.2.2 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 3004ms +rtt min/avg/max/mdev = 2.064/3.326/3.903/0.748 ms + +vyos@P2-VyOS:~$ ping 192.0.2.1 source-address 192.0.2.2 +PING 192.0.2.1 (192.0.2.1) from 192.0.2.2 : 56(84) bytes of data. +64 bytes from 192.0.2.1: icmp_seq=1 ttl=63 time=2.91 ms +64 bytes from 192.0.2.1: icmp_seq=2 ttl=63 time=3.23 ms +64 bytes from 192.0.2.1: icmp_seq=3 ttl=63 time=2.91 ms +64 bytes from 192.0.2.1: icmp_seq=4 ttl=63 time=2.85 ms +^C +--- 192.0.2.1 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 3005ms +rtt min/avg/max/mdev = 2.846/2.972/3.231/0.151 ms +``` diff --git a/docs/configexamples/md-wan-load-balancing.md b/docs/configexamples/md-wan-load-balancing.md new file mode 100644 index 00000000..4e146838 --- /dev/null +++ b/docs/configexamples/md-wan-load-balancing.md @@ -0,0 +1,164 @@ +lastproofread +2021-06-29 + +<div id="wan-load-balancing"> + +</div> + +# WAN Load Balancer examples + +% stop_vyoslinter + +## Example 1: Distributing load evenly + +The setup used in this example is shown in the following diagram: + +<img src="/_static/images/Wan_load_balancing1.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +### Overview + +> - All traffic coming in through eth2 is balanced between eth0 and eth1 +> on the router. +> - Pings will be sent to four targets for health testing (33.44.55.66, +> 44.55.66.77, 55.66.77.88 and 66.77.88.99). +> - All outgoing packets are assigned the source address of the assigned +> interface (SNAT). +> - eth0 is set to be removed from the load balancer's interface pool +> after 5 ping failures, eth1 will be removed after 4 ping failures. + +### Create static routes to ping targets + +Create static routes through the two ISPs towards the ping targets and +commit the changes: + +``` none +set protocols static route 33.44.55.66/32 next-hop 11.22.33.1 +set protocols static route 44.55.66.77/32 next-hop 11.22.33.1 +set protocols static route 55.66.77.88/32 next-hop 22.33.44.1 +set protocols static route 66.77.88.99/32 next-hop 22.33.44.1 +``` + +### Configure the load balancer + +Configure the WAN load balancer with the parameters described above: + +``` none +set load-balancing wan interface-health eth0 failure-count 5 +set load-balancing wan interface-health eth0 nexthop 11.22.33.1 +set load-balancing wan interface-health eth0 test 10 type ping +set load-balancing wan interface-health eth0 test 10 target 33.44.55.66 +set load-balancing wan interface-health eth0 test 20 type ping +set load-balancing wan interface-health eth0 test 20 target 44.55.66.77 +set load-balancing wan interface-health eth1 failure-count 4 +set load-balancing wan interface-health eth1 nexthop 22.33.44.1 +set load-balancing wan interface-health eth1 test 10 type ping +set load-balancing wan interface-health eth1 test 10 target 55.66.77.88 +set load-balancing wan interface-health eth1 test 20 type ping +set load-balancing wan interface-health eth1 test 20 target 66.77.88.99 +set load-balancing wan rule 10 inbound-interface eth2 +set load-balancing wan rule 10 interface eth0 +set load-balancing wan rule 10 interface eth1 +``` + +## Example 2: Failover based on interface weights + +This example uses the failover mode. + +### Overview + +In this example, eth0 is the primary interface and eth1 is the secondary +interface. To provide simple failover functionality. If eth0 fails, eth1 +takes over. + +### Create interface weight based configuration + +The configuration steps are the same as in the previous example, except +rule 10. So we keep the configuration, remove rule 10 and add a new rule +for the failover mode: + +``` none +delete load-balancing wan rule 10 +set load-balancing wan rule 10 failover +set load-balancing wan rule 10 inbound-interface eth2 +set load-balancing wan rule 10 interface eth0 weight 10 +set load-balancing wan rule 10 interface eth1 weight 1 +``` + +## Example 3: Failover based on rule order + +The previous example used the failover command to send traffic through +eth1 if eth0 fails. In this example, failover functionality is provided +by rule order. + +### Overview + +Two rules will be created, the first rule directs traffic coming in +from eth2 to eth0 and the second rule directs the traffic to eth1. If +eth0 fails the first rule is bypassed and the second rule matches, +directing traffic to eth1. + +### Create rule order based configuration + +We keep the configuration from the previous example, delete rule 10 +and create the two new rules as described: + +``` none +delete load-balancing wan rule 10 +set load-balancing wan rule 10 inbound-interface eth2 +set load-balancing wan rule 10 interface eth0 +set load-balancing wan rule 20 inbound-interface eth2 +set load-balancing wan rule 20 interface eth1 +``` + +## Example 4: Failover based on rule order - priority traffic + +A rule order for prioritizing traffic is useful in scenarios where the +secondary link has a lower speed and should only carry high priority +traffic. It is assumed for this example that eth1 is connected to a +slower connection than eth0 and should prioritize VoIP traffic. + +### Overview + +A rule order for prioritizing traffic is useful in scenarios where the +secondary link has a lower speed and should only carry high priority +traffic. It is assumed for this example that eth1 is connected to a +slower connection than eth0 and should prioritize VoIP traffic. + +### Create rule order based configuration with low speed secondary link + +We keep the configuration from the previous example, delete rule 20 and +create a new rule as described: + +``` none +delete load-balancing wan rule 20 +set load-balancing wan rule 20 inbound-interface eth2 +set load-balancing wan rule 20 interface eth1 +set load-balancing wan rule 20 destination port sip +set load-balancing wan rule 20 protocol tcp +set protocols static route 0.0.0.0/0 next-hop 11.22.33.1 +``` + +## Example 5: Exclude traffic from load balancing + +In this example two LAN interfaces exist in different subnets instead +of one like in the previous examples: + +<img src="/_static/images/Wan_load_balancing_exclude1.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +### Adding a rule for the second interface + +Based on the previous example, another rule for traffic from the second +interface eth3 can be added to the load balancer. However, traffic meant +to flow between the LAN subnets will be sent to eth0 and eth1 as well. +To prevent this, another rule is required. This rule excludes traffic +between the local subnets from the load balancer. It also excludes +locally-sources packets (required for web caching with load balancing). +eth+ is used as an alias that refers to all ethernet interfaces: + +``` none +set load-balancing wan rule 5 exclude +set load-balancing wan rule 5 inbound-interface eth+ +set load-balancing wan rule 5 destination address 10.0.0.0/8 +``` + +% start_vyoslinter diff --git a/docs/configexamples/md-zone-policy.md b/docs/configexamples/md-zone-policy.md new file mode 100644 index 00000000..afa8c940 --- /dev/null +++ b/docs/configexamples/md-zone-policy.md @@ -0,0 +1,416 @@ +lastproofread +2024-06-14 + +# Zone-Policy example + +<div class="note"> + +<div class="title"> + +Note + +</div> + +In `T2199` the syntax of the zone configuration was changed. +The zone configuration moved from `zone-policy zone <name>` to `firewall zone <name>`. + +</div> + +## Native IPv4 and IPv6 + +We have three networks. + +``` none +WAN - 172.16.10.0/24, 2001:0DB8:0:9999::0/64 +LAN - 192.168.100.0/24, 2001:0DB8:0:AAAA::0/64 +DMZ - 192.168.200.0/24, 2001:0DB8:0:BBBB::0/64 +``` + +**This specific example is for a router on a stick, but is very easily +adapted for however many NICs you have**: + +- Internet - 192.168.200.100 - TCP/80 +- Internet - 192.168.200.100 - TCP/443 +- Internet - 192.168.200.100 - TCP/25 +- Internet - 192.168.200.100 - TCP/53 +- VyOS acts as DHCP, DNS forwarder, NAT, router and firewall. +- 192.168.200.200/2001:0DB8:0:BBBB::200 is an internal/external DNS, web + and mail (SMTP/IMAP) server. +- 192.168.100.10/2001:0DB8:0:AAAA::10 is the administrator's console. It + can SSH to VyOS. +- LAN and DMZ hosts have basic outbound access: Web, FTP, SSH. +- LAN can access DMZ resources. +- DMZ cannot access LAN resources. +- Inbound WAN connect to DMZ host. + +<img src="/_static/images/zone-policy-diagram.webp" class="align-center" style="width:80.0%" alt="Network Topology Diagram" /> + +The VyOS interface is assigned the .1/:1 address of their respective +networks. WAN is on VLAN 10, LAN on VLAN 20, and DMZ on VLAN 30. + +It will look something like this: + +``` none +interfaces { + ethernet eth0 { + duplex auto + hw-id 00:53:ed:6e:2a:92 + smp_affinity auto + speed auto + vif 10 { + address 172.16.10.1/24 + address 2001:db8:0:9999::1/64 + } + vif 20 { + address 192.168.100.1/24 + address 2001:db8:0:AAAA::1/64 + } + vif 30 { + address 192.168.200.1/24 + address 2001:db8:0:BBBB::1/64 + } + } + loopback lo { + } +} +``` + +## Zones Basics + +Each interface is assigned to a zone. The interface can be physical or +virtual such as tunnels (VPN, PPTP, GRE, etc) and are treated exactly +the same. + +Traffic flows from zone A to zone B. That flow is what I refer to as a +zone-pair-direction. eg. A-\>B and B-\>A are two zone-pair-destinations. + +Ruleset are created per zone-pair-direction. + +I name rule sets to indicate which zone-pair-direction they represent. +eg. ZoneA-ZoneB or ZoneB-ZoneA. LAN-DMZ, DMZ-LAN. + +In VyOS, you have to have unique Ruleset names. In the event of overlap, +I add a "-6" to the end of v6 rulesets. eg. LAN-DMZ, LAN-DMZ-6. This +allows for each auto-completion and uniqueness. + +In this example we have 4 zones. LAN, WAN, DMZ, Local. The local zone is +the firewall itself. + +If your computer is on the LAN and you need to SSH into your VyOS box, +you would need a rule to allow it in the LAN-Local ruleset. If you want +to access a webpage from your VyOS box, you need a rule to allow it in +the Local-LAN ruleset. + +In rules, it is good to keep them named consistently. As the number of +rules you have grows, the more consistency you have, the easier your +life will be. + +``` none +Rule 1 - State Established, Related +Rule 2 - State Invalid +Rule 100 - ICMP +Rule 200 - Web +Rule 300 - FTP +Rule 400 - NTP +Rule 500 - SMTP +Rule 600 - DNS +Rule 700 - DHCP +Rule 800 - SSH +Rule 900 - IMAPS +``` + +The first two rules are to deal with the idiosyncrasies of VyOS and +iptables. + +Zones and Rulesets both have a default action statement. When using +Zone-Policies, the default action is set by the zone-policy statement +and is represented by rule 10000. + +It is good practice to log both accepted and denied traffic. It can save +you significant headaches when trying to troubleshoot a connectivity +issue. + +To add logging to the default rule, do: + +``` none +set firewall name <ruleSet> default-log +``` + +By default, iptables does not allow traffic for established sessions to +return, so you must explicitly allow this. I do this by adding two rules +to every ruleset. 1 allows established and related state packets through +and rule 2 drops and logs invalid state packets. We place the +established/related rule at the top because the vast majority of traffic +on a network is established and the invalid rule to prevent invalid +state packets from mistakenly being matched against other rules. Having +the most matched rule listed first reduces CPU load in high volume +environments. Note: I have filed a bug to have this added as a default +action as well. + +''It is important to note, that you do not want to add logging to the +established state rule as you will be logging both the inbound and +outbound packets for each session instead of just the initiation of the +session. Your logs will be massive in a very short period of time.'' + +In VyOS you must have the interfaces created before you can apply it to +the zone and the rulesets must be created prior to applying it to a +zone-policy. + +I create/configure the interfaces first. Build out the rulesets for each +zone-pair-direction which includes at least the three state rules. Then +I setup the zone-policies. + +Zones do not allow for a default action of accept; either drop or +reject. It is important to remember this because if you apply an +interface to a zone and commit, any active connections will be dropped. +Specifically, if you are SSH’d into VyOS and add local or the interface +you are connecting through to a zone and do not have rulesets in place +to allow SSH and established sessions, you will not be able to connect. + +The following are the rules that were created for this example (may not +be complete), both in IPv4 and IPv6. If there is no IP specified, then +the source/destination address is not explicit. + +``` none +WAN - DMZ:192.168.200.200 - tcp/80 +WAN - DMZ:192.168.200.200 - tcp/443 +WAN - DMZ:192.168.200.200 - tcp/25 +WAN - DMZ:192.168.200.200 - tcp/53 +WAN - DMZ:2001:0DB8:0:BBBB::200 - tcp/80 +WAN - DMZ:2001:0DB8:0:BBBB::200 - tcp/443 +WAN - DMZ:2001:0DB8:0:BBBB::200 - tcp/25 +WAN - DMZ:2001:0DB8:0:BBBB::200 - tcp/53 + +DMZ - Local - tcp/53 +DMZ - Local - tcp/123 +DMZ - Local - tcp/67,68 + +LAN - Local - tcp/53 +LAN - Local - tcp/123 +LAN - Local - tcp/67,68 +LAN:192.168.100.10 - Local - tcp/22 +LAN:2001:0DB8:0:AAAA::10 - Local - tcp/22 + +LAN - WAN - tcp/80 +LAN - WAN - tcp/443 +LAN - WAN - tcp/22 +LAN - WAN - tcp/20,21 + +DMZ - WAN - tcp/80 +DMZ - WAN - tcp/443 +DMZ - WAN - tcp/22 +DMZ - WAN - tcp/20,21 +DMZ - WAN - tcp/53 +DMZ - WAN - udp/53 + +Local - WAN - tcp/80 +Local - WAN - tcp/443 +Local - WAN - tcp/20,21 + +Local - DMZ - tcp/25 +Local - DMZ - tcp/67,68 +Local - DMZ - tcp/53 +Local - DMZ - udp/53 + +Local - LAN - tcp/67,68 + +LAN - DMZ - tcp/80 +LAN - DMZ - tcp/443 +LAN - DMZ - tcp/993 +LAN:2001:0DB8:0:AAAA::10 - DMZ:2001:0DB8:0:BBBB::200 - tcp/22 +LAN:192.168.100.10 - DMZ:192.168.200.200 - tcp/22 +``` + +Since we have 4 zones, we need to setup the following rulesets. + +``` none +Lan-wan +Lan-local +Lan-dmz +Wan-lan +Wan-local +Wan-dmz +Local-lan +Local-wan +Local-dmz +Dmz-lan +Dmz-wan +Dmz-local +``` + +Even if the two zones will never communicate, it is a good idea to +create the zone-pair-direction rulesets and set default-log. This +will allow you to log attempts to access the networks. Without it, you +will never see the connection attempts. + +This is an example of the three base rules. + +``` none +name wan-lan { + default-action drop + default-log + rule 1 { + action accept + state { + established enable + related enable + } + } + rule 2 { + action drop + log enable + state { + invalid enable + } + } +} +``` + +Here is an example of an IPv6 DMZ-WAN ruleset. + +``` none +ipv6-name dmz-wan-6 { + default-action drop + default-log + rule 1 { + action accept + state { + established enable + related enable + } + } + rule 2 { + action drop + log enable + state { + invalid enable + } + } + rule 100 { + action accept + log enable + protocol ipv6-icmp + } + rule 200 { + action accept + destination { + port 80,443 + } + log enable + protocol tcp + } + rule 300 { + action accept + destination { + port 20,21 + } + log enable + protocol tcp + } + rule 500 { + action accept + destination { + port 25 + } + log enable + protocol tcp + source { + address 2001:db8:0:BBBB::200 + } + } + rule 600 { + action accept + destination { + port 53 + } + log enable + protocol tcp_udp + source { + address 2001:db8:0:BBBB::200 + } + } + rule 800 { + action accept + destination { + port 22 + } + log enable + protocol tcp + } +} +``` + +Once you have all of your rulesets built, then you need to create your +zone-policy. + +Start by setting the interface and default action for each zone. + +``` none +set firewall zone dmz default-action drop +set firewall zone dmz interface eth0.30 +``` + +In this case, we are setting the v6 ruleset that represents traffic +sourced from the LAN, destined for the DMZ. Because the zone-policy +firewall syntax is a little awkward, I keep it straight by thinking of +it backwards. + +``` none +set firewall zone dmz from lan firewall ipv6-name lan-dmz-6 +``` + +DMZ-LAN policy is LAN-DMZ. You can get a rhythm to it when you build out +a bunch at one time. + +In the end, you will end up with something like this config. I took out +everything but the Firewall, Interfaces, and zone-policy sections. It is +long enough as is. + +## IPv6 Tunnel + +If you are using a IPv6 tunnel from HE.net or someone else, the basis is +the same except you have two WAN interfaces. One for v4 and one for v6. + +You would have 5 zones instead of just 4 and you would configure your v6 +ruleset between your tunnel interface and your LAN/DMZ zones instead of +to the WAN. + +LAN, WAN, DMZ, local and TUN (tunnel) + +v6 pairs would be: + +``` none +lan-tun +lan-local +lan-dmz +tun-lan +tun-local +tun-dmz +local-lan +local-tun +local-dmz +dmz-lan +dmz-tun +dmz-local +``` + +Notice, none go to WAN since WAN wouldn't have a v6 address on it. + +You would have to add a couple of rules on your wan-local ruleset to +allow protocol 41 in. + +Something like: + +``` none +rule 400 { + action accept + destination { + address 172.16.10.1 + } + log enable + protocol 41 + source { + address ip.of.tunnel.broker + } +} +``` diff --git a/docs/configuration/container/md-index.md b/docs/configuration/container/md-index.md new file mode 100644 index 00000000..1cd322f9 --- /dev/null +++ b/docs/configuration/container/md-index.md @@ -0,0 +1,512 @@ +lastproofread +2022-06-10 + +# Container + +The VyOS container implementation is based on <span class="title-ref">Podman\<https://podman.io/\></span> as +a daemonless container engine. + +## Configuration + +<div class="cfgcmd"> + +set container name \<name\> image + +Sets the image name in the hub registry + +``` none +set container name mysql-server image mysql:8.0 +``` + +If a registry is not specified, Docker.io will be used as the container +registry unless an alternative registry is specified using +**set container registry \<name\>** or the registry is included +in the image name + +``` none +set container name mysql-server image quay.io/mysql:8.0 +``` + +</div> + +<div class="cfgcmd"> + +set container name \<name\> entrypoint \<entrypoint\> + +Override the default entrypoint from the image for a container. + +</div> + +<div class="cfgcmd"> + +set container name \<name\> command \<command\> + +Override the default command from the image for a container. + +</div> + +<div class="cfgcmd"> + +set container name \<name\> arguments \<arguments\> + +Set the command arguments for a container. + +</div> + +<div class="cfgcmd"> + +set container name \<name\> host-name \<hostname\> + +Set the host name for a container. + +</div> + +<div class="cfgcmd"> + +set container name \<name\> allow-host-pid + +The container and the host share the same process namespace. +This means that processes running on the host are visible inside the +container, and processes inside the container are visible on the host. + +The command translates to "--pid host" when the container is created. + +</div> + +<div class="cfgcmd"> + +set container name \<name\> allow-host-networks + +Allow host networking in a container. The network stack of the container is +not isolated from the host and will use the host IP. + +The command translates to "--net host" when the container is created. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +**allow-host-networks** cannot be used with **network** + +</div> + +</div> + +<div class="cfgcmd"> + +set container name \<name\> network \<networkname\> + +Attaches user-defined network to a container. +Only one network must be specified and must already exist. + +</div> + +<div class="cfgcmd"> + +set container name \<name\> network \<networkname\> address \<address\> + +Optionally set a specific static IPv4 or IPv6 address for the container. +This address must be within the named network prefix. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The first IP in the container network is reserved by the +engine and cannot be used + +</div> + +</div> + +<div class="cfgcmd"> + +set container name \<name\> description \<text\> + +Set a container description + +</div> + +<div class="cfgcmd"> + +set container name \<name\> environment \<key\> value \<value\> + +Add custom environment variables. +Multiple environment variables are allowed. +The following commands translate to "-e key=value" when the container +is created. + +``` none +set container name mysql-server environment MYSQL_DATABASE value 'zabbix' +set container name mysql-server environment MYSQL_USER value 'zabbix' +set container name mysql-server environment MYSQL_PASSWORD value 'zabbix_pwd' +set container name mysql-server environment MYSQL_ROOT_PASSWORD value 'root_pwd' +``` + +</div> + +<div class="cfgcmd"> + +set container name \<name\> port \<portname\> source \<portnumber\> + +</div> + +<div class="cfgcmd"> + +set container name \<name\> port \<portname\> destination \<portnumber\> + +</div> + +<div class="cfgcmd"> + +set container name \<name\> port \<portname\> protocol \<tcp | udp\> + +Publish a port for the container. + +``` none +set container name zabbix-web-nginx-mysql port http source 80 +set container name zabbix-web-nginx-mysql port http destination 8080 +set container name zabbix-web-nginx-mysql port http protocol tcp +``` + +</div> + +<div class="cfgcmd"> + +set container name \<name\> volume \<volumename\> source \<path\> + +</div> + +<div class="cfgcmd"> + +set container name \<name\> volume \<volumename\> destination \<path\> + +Mount a volume into the container + +``` none +set container name coredns volume 'corefile' source /config/coredns/Corefile +set container name coredns volume 'corefile' destination /etc/Corefile +``` + +</div> + +<div class="cfgcmd"> + +set container name \<name\> volume \<volumename\> mode \<ro | rw\> + +Volume is either mounted as rw (read-write - default) or ro (read-only) + +</div> + +<div class="cfgcmd"> + +set container name \<name\> uid \<number\> + +</div> + +<div class="cfgcmd"> + +set container name \<name\> gid \<number\> + +Set the User ID or Group ID of the container + +</div> + +<div class="cfgcmd"> + +set container name \<name\> restart \[no | on-failure | always\] + +Set the restart behavior of the container. + +- **no**: Do not restart containers on exit +- **on-failure**: Restart containers when they exit with a non-zero + exit code, retrying indefinitely (default) +- **always**: Restart containers when they exit, regardless of status, + retrying indefinitely + +</div> + +<div class="cfgcmd"> + +set container name \<name\> cpu-quota \<num\> + +This specifies the number of CPU resources the container can use. + +Default is 0 for unlimited. +For example, 1.25 limits the container to use up to 1.25 cores +worth of CPU time. +This can be a decimal number with up to three decimal places. + +The command translates to "--cpus=\<num\>" when the container is created. + +</div> + +<div class="cfgcmd"> + +set container name \<name\> memory \<MB\> + +Constrain the memory available to the container. + +Default is 512 MB. Use 0 MB for unlimited memory. + +</div> + +<div class="cfgcmd"> + +set container name \<name\> device \<devicename\> source \<path\> + +</div> + +<div class="cfgcmd"> + +set container name \<name\> device \<devicename\> destination \<path\> + +Add a host device to the container. + +</div> + +<div class="cfgcmd"> + +set container name \<name\> capability \<text\> + +Set container capabilities or permissions. + +- **net-admin**: Network operations (interface, firewall, routing tables) +- **net-bind-service**: Bind a socket to privileged ports + (port numbers less than 1024) +- **net-raw**: Permission to create raw network sockets +- **setpcap**: Capability sets (from bounded or inherited set) +- **sys-admin**: Administration operations (quotactl, mount, sethostname, + setdomainame) +- **sys-time**: Permission to set system clock + +</div> + +<div class="cfgcmd"> + +set container name \<name\> sysctl parameter \<parameter\> value \<value\> + +Set container sysctl values. + +The subset of possible parameters are: + +- Kernel Parameters: kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, + kernel.shmall, kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced +- Parameters beginning with fs.mqueue.\* +- Parameters beginning with net.\* (only if user-defined network is used) + +</div> + +<div class="cfgcmd"> + +set container name \<name\> label \<label\> value \<value\> + +Add metadata label for this container. + +</div> + +<div class="cfgcmd"> + +set container name \<name\> disable + +Disable a container. + +</div> + +### Container Networks + +<div class="cfgcmd"> + +set container network \<name\> + +Creates a named container network + +</div> + +<div class="cfgcmd"> + +set container network \<name\> description + +A brief description what this network is all about. + +</div> + +<div class="cfgcmd"> + +set container network \<name\> prefix \<ipv4|ipv6\> + +Define IPv4 and/or IPv6 prefix for a given network name. +Both IPv4 and IPv6 can be used in parallel. + +</div> + +<div class="cfgcmd"> + +set container network \<name\> vrf \<name\> + +Bind container network to a given VRF instance. + +</div> + +### Container Registry + +<div class="cfgcmd"> + +set container registry \<name\> + +Adds registry to list of unqualified-search-registries. By default, for any +image that does not include the registry in the image name, VyOS will use +docker.io and quay.io as the container registry. + +</div> + +<div class="cfgcmd"> + +set container registry \<name\> disable + +Disable a given container registry + +</div> + +<div class="cfgcmd"> + +set container registry \<name\> authentication username + +</div> + +<div class="cfgcmd"> + +set container registry \<name\> authentication password + +Some container registries require credentials to be used. + +Credentials can be defined here and will only be used when adding a +container image to the system. + +</div> + +## Operation Commands + +<div class="opcmd"> + +add container image \<containername\> + +Pull a new image for container + +</div> + +<div class="opcmd"> + +show container + +Show the list of all active containers. + +</div> + +<div class="opcmd"> + +show container image + +Show the local container images. + +</div> + +<div class="opcmd"> + +show container log \<containername\> + +Show logs from a given container + +</div> + +<div class="opcmd"> + +show container network + +Show a list available container networks + +</div> + +<div class="opcmd"> + +restart container \<containername\> + +Restart a given container + +</div> + +<div class="opcmd"> + +update container image \<containername\> + +Update container image + +</div> + +<div class="opcmd"> + +delete container image \<image id|all\> \[force\] + +Delete a particular container image based on it's image ID. +You can also delete all container images at once. + +You can not delete a container image if it has more then one tag +assigned, this is why there is a <span class="title-ref">force</span> option to pass down to +the container image to also remove those images. + +</div> + +## Example Configuration + +> For the sake of demonstration, [example \#1 in the official documentation](https://www.zabbix.com/documentation/current/manual/installation/containers) +> to the declarative VyOS CLI syntax. +> +> ``` none +> set container network zabbix prefix 172.20.0.0/16 +> set container network zabbix description 'Network for Zabbix component containers' +> +> set container name mysql-server image mysql:8.0 +> set container name mysql-server network zabbix +> +> set container name mysql-server environment 'MYSQL_DATABASE' value 'zabbix' +> set container name mysql-server environment 'MYSQL_USER' value 'zabbix' +> set container name mysql-server environment 'MYSQL_PASSWORD' value 'zabbix_pwd' +> set container name mysql-server environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' +> +> set container name zabbix-java-gateway image zabbix/zabbix-java-gateway:alpine-5.2-latest +> set container name zabbix-java-gateway network zabbix +> +> set container name zabbix-server-mysql image zabbix/zabbix-server-mysql:alpine-5.2-latest +> set container name zabbix-server-mysql network zabbix +> +> set container name zabbix-server-mysql environment 'DB_SERVER_HOST' value 'mysql-server' +> set container name zabbix-server-mysql environment 'MYSQL_DATABASE' value 'zabbix' +> set container name zabbix-server-mysql environment 'MYSQL_USER' value 'zabbix' +> set container name zabbix-server-mysql environment 'MYSQL_PASSWORD' value 'zabbix_pwd' +> set container name zabbix-server-mysql environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' +> set container name zabbix-server-mysql environment 'ZBX_JAVAGATEWAY' value 'zabbix-java-gateway' +> +> set container name zabbix-server-mysql port zabbix source 10051 +> set container name zabbix-server-mysql port zabbix destination 10051 +> +> set container name zabbix-web-nginx-mysql image zabbix/zabbix-web-nginx-mysql:alpine-5.2-latest +> set container name zabbix-web-nginx-mysql network zabbix +> +> set container name zabbix-web-nginx-mysql environment 'MYSQL_DATABASE' value 'zabbix' +> set container name zabbix-web-nginx-mysql environment 'ZBX_SERVER_HOST' value 'zabbix-server-mysql' +> set container name zabbix-web-nginx-mysql environment 'DB_SERVER_HOST' value 'mysql-server' +> set container name zabbix-web-nginx-mysql environment 'MYSQL_USER' value 'zabbix' +> set container name zabbix-web-nginx-mysql environment 'MYSQL_PASSWORD' value 'zabbix_pwd' +> set container name zabbix-web-nginx-mysql environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' +> +> set container name zabbix-web-nginx-mysql port http source 80 +> set container name zabbix-web-nginx-mysql port http destination 8080 +> ``` diff --git a/docs/configuration/firewall/md-bridge.md b/docs/configuration/firewall/md-bridge.md new file mode 100644 index 00000000..fad81412 --- /dev/null +++ b/docs/configuration/firewall/md-bridge.md @@ -0,0 +1,683 @@ +lastproofread +2023-11-08 + +# Bridge Firewall Configuration + +<div class="note"> + +<div class="title"> + +Note + +</div> + +**Documentation under development** + +</div> + +## Overview + +In this section there's useful information of all firewall configuration that +can be done regarding bridge, and appropiate op-mode commands. +Configuration commands covered in this section: + +<div class="cfgcmd"> + +set firewall bridge ... + +</div> + +From main structure defined in `Firewall Overview</configuration/firewall/index>` +in this section you can find detailed information only for the next part +of the general structure: + +``` none +- set firewall + * bridge + - forward + + filter + - name + + custom_name +``` + +Traffic which is received by the router on an interface which is member of a +bridge is processed on the **Bridge Layer**. A simplified packet flow diagram +for this layer is shown next: + +<figure> +<img src="/_static/images/firewall-bridge-packet-flow.webp" /> +</figure> + +For traffic that needs to be forwared internally by the bridge, base chain is +is **forward**, and it's base command for filtering is `set firewall bridge forward filter ...`, which happens in stage 4, highlightened with red color. + +Custom bridge firewall chains can be create with command `set firewall bridge name <name> ...`. In order to use such custom chain, a rule with action jump, +and the appropiate target should be defined in a base chain. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +**Layer 3 bridge**: +When an IP address is assigned to the bridge interface, and if traffic +is sent to the router to this IP (for example using such IP as +default gateway), then rules defined for **bridge firewall** won't +match, and firewall analysis continues at **IP layer**. + +</div> + +## Bridge Rules + +For firewall filtering, firewall rules needs to be created. Each rule is +numbered, has an action to apply if the rule is matched, and the ability +to specify multiple criteria matchers. Data packets go through the rules +from 1 - 999999, so order is crucial. At the first match the action of the +rule will be executed. + +### Actions + +If a rule is defined, then an action must be defined for it. This tells the +firewall what to do if all criteria matchers defined for such rule do match. + +In firewall bridge rules, the action can be: + +> - `accept`: accept the packet. +> - `continue`: continue parsing next rule. +> - `drop`: drop the packet. +> - `jump`: jump to another custom chain. +> - `return`: Return from the current chain and continue at the next rule +> of the last chain. +> - `queue`: Enqueue packet to userspace. + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> action +\[accept | continue | drop | jump | queue | return\] + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> rule \<1-999999\> action +\[accept | continue | drop | jump | queue | return\] + +This required setting defines the action of the current rule. If action is +set to jump, then jump-target is also needed. + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +jump-target \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> rule \<1-999999\> +jump-target \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +queue \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> rule \<1-999999\> +queue \<0-65535\> + +To be used only when action is set to `queue`. Use this command to specify +queue target to use. Queue range is also supported. + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +queue-options bypass + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> rule \<1-999999\> +queue-options bypass + +To be used only when action is set to `queue`. Use this command to let +packet go through firewall when no userspace software is connected to the +queue. + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +queue-options fanout + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> rule \<1-999999\> +queue-options fanout + +To be used only when action is set to `queue`. Use this command to +distribute packets between several queues. + +</div> + +Also, **default-action** is an action that takes place whenever a packet does +not match any rule in it's chain. For base chains, possible options for +**default-action** are **accept** or **drop**. + +<div class="cfgcmd"> + +set firewall bridge forward filter default-action +\[accept | drop\] + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> default-action +\[accept | continue | drop | jump | queue | return\] + +This set the default action of the rule-set if no rule matched a packet +criteria. If default-action is set to `jump`, then +`default-jump-target` is also needed. Note that for base chains, default +action can only be set to `accept` or `drop`, while on custom chain, +more actions are available. + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> default-jump-target \<text\> + +To be used only when `defult-action` is set to `jump`. Use this +command to specify jump target for default rule. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +**Important note about default-actions:** +If default action for any base chain is not defined, then the default +action is set to **accept** for that chain. For custom chains, if default +action is not defined, then the default-action is set to **drop**. + +</div> + +### Firewall Logs + +Logging can be enable for every single firewall rule. If enabled, other +log options can be defined. + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> log + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> rule \<1-999999\> log + +Enable logging for the matched packet. If this configuration command is not +present, then log is not enabled. + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter default-log + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> default-log + +Use this command to enable the logging of the default action on +the specified chain. + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +log-options level \[emerg | alert | crit | err | warn | notice +| info | debug\] + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> rule \<1-999999\> +log-options level \[emerg | alert | crit | err | warn | notice +| info | debug\] + +Define log-level. Only applicable if rule log is enable. + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +log-options group \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> rule \<1-999999\> +log-options group \<0-65535\> + +Define log group to send message to. Only applicable if rule log is enable. + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +log-options snapshot-length \<0-9000\> + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> rule \<1-999999\> +log-options snapshot-length \<0-9000\> + +Define length of packet payload to include in netlink message. Only +applicable if rule log is enable and log group is defined. + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +log-options queue-threshold \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> rule \<1-999999\> +log-options queue-threshold \<0-65535\> + +Define number of packets to queue inside the kernel before sending them to +userspace. Only applicable if rule log is enable and log group is defined. + +</div> + +### Firewall Description + +For reference, a description can be defined for every defined custom chain. + +<div class="cfgcmd"> + +set firewall bridge name \<name\> description \<text\> + +Provide a rule-set description to a custom firewall chain. + +</div> + +### Rule Status + +When defining a rule, it is enable by default. In some cases, it is useful to +just disable the rule, rather than removing it. + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> disable + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> rule \<1-999999\> disable + +Command for disabling a rule but keep it in the configuration. + +</div> + +### Matching criteria + +There are a lot of matching criteria against which the packet can be tested. + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +destination mac-address \<mac-address\> + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> rule \<1-999999\> +destination mac-address \<mac-address\> + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +source mac-address \<mac-address\> + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> rule \<1-999999\> +source mac-address \<mac-address\> + +Match criteria based on source and/or destination mac-address. + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +inbound-interface name \<iface\> + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> rule \<1-999999\> +inbound-interface name \<iface\> + +Match based on inbound interface. Wilcard `*` can be used. +For example: `eth2*`. Prepending character `!` for inverted matching +criteria is also supportd. For example `!eth2` + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +inbound-interface group \<iface_group\> + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> rule \<1-999999\> +inbound-interface group \<iface_group\> + +Match based on inbound interface group. Prepending character `!` for +inverted matching criteria is also supportd. For example `!IFACE_GROUP` + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +outbound-interface name \<iface\> + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> rule \<1-999999\> +outbound-interface name \<iface\> + +Match based on outbound interface. Wilcard `*` can be used. +For example: `eth2*`. Prepending character `!` for inverted matching +criteria is also supportd. For example `!eth2` + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +outbound-interface group \<iface_group\> + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> rule \<1-999999\> +outbound-interface group \<iface_group\> + +Match based on outbound interface group. Prepending character `!` for +inverted matching criteria is also supportd. For example `!IFACE_GROUP` + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +vlan id \<0-4096\> + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> rule \<1-999999\> +vlan id \<0-4096\> + +Match based on vlan ID. Range is also supported. + +</div> + +<div class="cfgcmd"> + +set firewall bridge forward filter rule \<1-999999\> +vlan priority \<0-7\> + +</div> + +<div class="cfgcmd"> + +set firewall bridge name \<name\> rule \<1-999999\> +vlan priority \<0-7\> + +Match based on vlan priority(pcp). Range is also supported. + +</div> + +## Operation-mode Firewall + +### Rule-set overview + +In this section you can find all useful firewall op-mode commands. + +General commands for firewall configuration, counter and statiscits: + +<div class="opcmd"> + +show firewall + +</div> + +<div class="opcmd"> + +show firewall summary + +</div> + +<div class="opcmd"> + +show firewall statistics + +</div> + +And, to print only bridge firewall information: + +<div class="opcmd"> + +show firewall bridge + +</div> + +<div class="opcmd"> + +show firewall bridge forward filter + +</div> + +<div class="opcmd"> + +show firewall bridge forward filter rule \<rule\> + +</div> + +<div class="opcmd"> + +show firewall bridge name \<name\> + +</div> + +<div class="opcmd"> + +show firewall bridge name \<name\> rule \<rule\> + +</div> + +### Show Firewall log + +<div class="opcmd"> + +show log firewall + +</div> + +<div class="opcmd"> + +show log firewall bridge + +</div> + +<div class="opcmd"> + +show log firewall bridge forward + +</div> + +<div class="opcmd"> + +show log firewall bridge forward filter + +</div> + +<div class="opcmd"> + +show log firewall bridge name \<name\> + +</div> + +<div class="opcmd"> + +show log firewall bridge forward filter rule \<rule\> + +</div> + +<div class="opcmd"> + +show log firewall bridge name \<name\> rule \<rule\> + +Show the logs of all firewall; show all bridge firewall logs; show all logs +for forward hook; show all logs for forward hook and priority filter; show +all logs for particular custom chain; show logs for specific Rule-Set. + +</div> + +### Example + +Configuration example: + +``` none +set firewall bridge forward filter default-action 'drop' +set firewall bridge forward filter default-log +set firewall bridge forward filter rule 10 action 'continue' +set firewall bridge forward filter rule 10 inbound-interface name 'eth2' +set firewall bridge forward filter rule 10 vlan id '22' +set firewall bridge forward filter rule 20 action 'drop' +set firewall bridge forward filter rule 20 inbound-interface group 'TRUNK-RIGHT' +set firewall bridge forward filter rule 20 vlan id '60' +set firewall bridge forward filter rule 30 action 'jump' +set firewall bridge forward filter rule 30 jump-target 'TEST' +set firewall bridge forward filter rule 30 outbound-interface name '!eth1' +set firewall bridge forward filter rule 35 action 'accept' +set firewall bridge forward filter rule 35 vlan id '11' +set firewall bridge forward filter rule 40 action 'continue' +set firewall bridge forward filter rule 40 destination mac-address '66:55:44:33:22:11' +set firewall bridge forward filter rule 40 source mac-address '11:22:33:44:55:66' +set firewall bridge name TEST default-action 'accept' +set firewall bridge name TEST default-log +set firewall bridge name TEST rule 10 action 'continue' +set firewall bridge name TEST rule 10 log +set firewall bridge name TEST rule 10 vlan priority '0' +``` + +And op-mode commands: + +``` none +vyos@BRI:~$ show firewall bridge +Rulesets bridge Information + +--------------------------------- +bridge Firewall "forward filter" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- --------------------------------------------------------------------- +10 continue all 0 0 iifname "eth2" vlan id 22 continue +20 drop all 0 0 iifname @I_TRUNK-RIGHT vlan id 60 +30 jump all 2130 170688 oifname != "eth1" jump NAME_TEST +35 accept all 2080 168616 vlan id 11 accept +40 continue all 0 0 ether daddr 66:55:44:33:22:11 ether saddr 11:22:33:44:55:66 continue +default drop all 0 0 + +--------------------------------- +bridge Firewall "name TEST" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- -------------------------------------------------- +10 continue all 2130 170688 vlan pcp 0 prefix "[bri-NAM-TEST-10-C]" continue +default accept all 2130 170688 + +vyos@BRI:~$ +vyos@BRI:~$ show firewall bridge name TEST +Ruleset Information + +--------------------------------- +bridge Firewall "name TEST" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- -------------------------------------------------- +10 continue all 2130 170688 vlan pcp 0 prefix "[bri-NAM-TEST-10-C]" continue +default accept all 2130 170688 + +vyos@BRI:~$ +``` + +Inspect logs: + +``` none +vyos@BRI:~$ show log firewall bridge +Dec 05 14:37:47 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102 +Dec 05 14:37:48 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102 +Dec 05 14:37:49 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102 +... +vyos@BRI:~$ show log firewall bridge forward filter +Dec 05 14:42:22 kernel: [bri-FWD-filter-default-D]IN=eth2 OUT=eth1 MAC=33:33:00:00:00:16:50:00:00:06:00:00:86:dd SRC=0000:0000:0000:0000:0000:0000:0000:0000 DST=ff02:0000:0000:0000:0000:0000:0000:0016 LEN=96 TC=0 HOPLIMIT=1 FLOWLBL=0 PROTO=ICMPv6 TYPE=143 CODE=0 +Dec 05 14:42:22 kernel: [bri-FWD-filter-default-D]IN=eth2 OUT=eth1 MAC=33:33:00:00:00:16:50:00:00:06:00:00:86:dd SRC=0000:0000:0000:0000:0000:0000:0000:0000 DST=ff02:0000:0000:0000:0000:0000:0000:0016 LEN=96 TC=0 HOPLIMIT=1 FLOWLBL=0 PROTO=ICMPv6 TYPE=143 CODE=0 +``` diff --git a/docs/configuration/firewall/md-flowtables.md b/docs/configuration/firewall/md-flowtables.md new file mode 100644 index 00000000..e423eb59 --- /dev/null +++ b/docs/configuration/firewall/md-flowtables.md @@ -0,0 +1,229 @@ +lastproofread +2024-06-20 + +# Flowtables Firewall Configuration + +<div class="note"> + +<div class="title"> + +Note + +</div> + +**Documentation under development** + +</div> + +## Overview + +In this section there's useful information of all firewall configuration that +can be done regarding flowtables. + +<div class="cfgcmd"> + +set firewall flowtables ... + +</div> + +From main structure defined in +`Firewall Overview</configuration/firewall/index>` +in this section you can find detailed information only for the next part +of the general structure: + +``` none +- set firewall + * flowtable + - custom_flow_table + + ... +``` + +Flowtables allows you to define a fastpath through the flowtable datapath. +The flowtable supports for the layer 3 IPv4 and IPv6 and the layer 4 TCP +and UDP protocols. + +<figure> +<img src="/_static/images/firewall-flowtable-packet-flow.webp" /> +</figure> + +Once the first packet of the flow successfully goes through the IP forwarding +path (black circles path), from the second packet on, you might decide to +offload the flow to the flowtable through your ruleset. The flowtable +infrastructure provides a rule action that allows you to specify when to add +a flow to the flowtable (On forward filtering, red circle number 6) + +A packet that finds a matching entry in the flowtable (flowtable hit) is +transmitted to the output netdevice, hence, packets bypass the classic IP +forwarding path and uses the **Fast Path** (orange circles path). The visible +effect is that you do not see these packets from any of the Netfilter +hooks coming after ingress. In case that there is no matching entry in the +flowtable (flowtable miss), the packet follows the classic IP forwarding path. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +**Flowtable Reference:** +<https://docs.kernel.org/networking/nf_flowtable.html> + +</div> + +## Flowtable Configuration + +In order to use flowtables, the minimal configuration needed includes: + +> - Create flowtable: create flowtable, which includes the interfaces +> that are going to be used by the flowtable. +> - Create firewall rule: create a firewall rule, setting action to +> `offload` and using desired flowtable for `offload-target`. + +Creating a flow table: + +<div class="cfgcmd"> + +set firewall flowtable \<flow_table_name\> interface \<iface\> + +Define interfaces to be used in the flowtable. + +</div> + +<div class="cfgcmd"> + +set firewall flowtable \<flow_table_name\> description \<text\> + +</div> + +Provide a description to the flow table. + +<div class="cfgcmd"> + +set firewall flowtable \<flow_table_name\> offload +\<hardware | software\> + +Define type of offload to be used by the flowtable: `hardware` or +`software`. By default, `software` offload is used. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +**Hardware offload:** should be supported by the NICs used. + +</div> + +Creating rules for using flow tables: + +<div class="cfgcmd"> + +set firewall \[ipv4 | ipv6\] forward filter rule \<1-999999\> +action offload + +Create firewall rule in forward chain, and set action to `offload`. + +</div> + +<div class="cfgcmd"> + +set firewall \[ipv4 | ipv6\] forward filter rule \<1-999999\> +offload-target \<flowtable\> + +Create firewall rule in forward chain, and define which flowtbale +should be used. Only applicable if action is `offload`. + +</div> + +## Configuration Example + +Things to be considred in this setup: + +> - Two interfaces are going to be used in the flowtables: eth0 and eth1 +> - Minumum firewall ruleset is provided, which includes some filtering rules, +> and appropiate rules for using flowtable offload capabilities. + +As described, first packet will be evaluated by all the firewall path, so +desired connection should be explicitely accepted. Same thing should be taken +into account for traffic in reverse order. In most cases state policies are +used in order to accept connection in reverse patch. + +We will only accept traffic comming from interface eth0, protocol tcp and +destination port 1122. All other traffic traspassing the router should be +blocked. + +### Commands + +``` none +set firewall flowtable FT01 interface 'eth0' +set firewall flowtable FT01 interface 'eth1' +set firewall ipv4 forward filter default-action 'drop' +set firewall ipv4 forward filter rule 10 action 'offload' +set firewall ipv4 forward filter rule 10 offload-target 'FT01' +set firewall ipv4 forward filter rule 10 state 'established' +set firewall ipv4 forward filter rule 10 state 'related' +set firewall ipv4 forward filter rule 20 action 'accept' +set firewall ipv4 forward filter rule 20 state 'established' +set firewall ipv4 forward filter rule 20 state 'related' +set firewall ipv4 forward filter rule 110 action 'accept' +set firewall ipv4 forward filter rule 110 destination address '192.0.2.100' +set firewall ipv4 forward filter rule 110 destination port '1122' +set firewall ipv4 forward filter rule 110 inbound-interface name 'eth0' +set firewall ipv4 forward filter rule 110 protocol 'tcp' +``` + +### Explanation + +Analysis on what happens for desired connection: + +> 1\. First packet is received on eth0, with destination address 192.0.2.100, +> protocol tcp and destination port 1122. Assume such destination address is +> reachable through interface eth1. +> +> 2\. Since this is the first packet, connection status of this connection, +> so far is **new**. So neither rule 10 nor 20 are valid. +> +> 3. Rule 110 is hit, so connection is accepted. +> +> 4\. Once answer from server 192.0.2.100 is seen in opposite direction, +> connection state will be triggered to **established**, so this reply is +> accepted in rule 20. +> +> 5\. Second packet for this connection is received by the router. Since +> connection state is **established**, then rule 10 is hit, and a new entry +> in the flowtable FT01 is added for this connection. +> +> 6\. All the following packets will skip traditional path, and will be offloaded +> and will use the **Fast Path**. + +### Checks + +It's time to check conntrack table, to see if any connection was accepted, +and if was properly offloaded + +``` none +vyos@FlowTables:~$ show firewall ipv4 forward filter +Ruleset Information + +--------------------------------- +ipv4 Firewall "forward filter" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- ---------------------------------------------------------------- +10 offload all 8 468 ct state { established, related } flow add @VYOS_FLOWTABLE_FT01 +20 accept all 8 468 ct state { established, related } accept +110 accept tcp 2 120 ip daddr 192.0.2.100 tcp dport 1122 iifname "eth0" accept +default drop all 7 420 + +vyos@FlowTables:~$ sudo conntrack -L | grep tcp +conntrack v1.4.6 (conntrack-tools): 5 flow entries have been shown. +tcp 6 src=198.51.100.100 dst=192.0.2.100 sport=41676 dport=1122 src=192.0.2.100 dst=198.51.100.100 sport=1122 dport=41676 [OFFLOAD] mark=0 use=2 +vyos@FlowTables:~$ +``` diff --git a/docs/configuration/firewall/md-global-options.md b/docs/configuration/firewall/md-global-options.md new file mode 100644 index 00000000..dc860894 --- /dev/null +++ b/docs/configuration/firewall/md-global-options.md @@ -0,0 +1,236 @@ +lastproofread +2023-12-26 + +# Global Options Firewall Configuration + +## Overview + +Some firewall settings are global and have an affect on the whole system. +In this section there's useful information about these global-options that can +be configured using vyos cli. + +Configuration commands covered in this section: + +<div class="cfgcmd"> + +set firewall global-options ... + +</div> + +## Configuration + +<div class="cfgcmd"> + +set firewall global-options all-ping \[enable | disable\] + +By default, when VyOS receives an ICMP echo request packet destined for +itself, it will answer with an ICMP echo reply, unless you avoid it +through its firewall. + +With the firewall you can set rules to accept, drop or reject ICMP in, +out or local traffic. You can also use the general **firewall all-ping** +command. This command affects only to LOCAL (packets destined for your +VyOS system), not to IN or OUT traffic. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +**firewall global-options all-ping** affects only to LOCAL +and it always behaves in the most restrictive way + +</div> + +``` none +set firewall global-options all-ping enable +``` + +When the command above is set, VyOS will answer every ICMP echo request +addressed to itself, but that will only happen if no other rule is +applied dropping or rejecting local echo requests. In case of conflict, +VyOS will not answer ICMP echo requests. + +``` none +set firewall global-options all-ping disable +``` + +When the command above is set, VyOS will answer no ICMP echo request +addressed to itself at all, no matter where it comes from or whether +more specific rules are being applied to accept them. + +</div> + +<div class="cfgcmd"> + +set firewall global-options broadcast-ping \[enable | disable\] + +This setting enable or disable the response of icmp broadcast +messages. The following system parameter will be altered: + +- `net.ipv4.icmp_echo_ignore_broadcasts` + +</div> + +<div class="cfgcmd"> + +set firewall global-options ip-src-route \[enable | disable\] + +</div> + +<div class="cfgcmd"> + +set firewall global-options ipv6-src-route \[enable | disable\] + +This setting handle if VyOS accept packets with a source route +option. The following system parameter will be altered: + +- `net.ipv4.conf.all.accept_source_route` +- `net.ipv6.conf.all.accept_source_route` + +</div> + +<div class="cfgcmd"> + +set firewall global-options receive-redirects \[enable | disable\] + +</div> + +<div class="cfgcmd"> + +set firewall global-options ipv6-receive-redirects +\[enable | disable\] + +enable or disable of ICMPv4 or ICMPv6 redirect messages accepted +by VyOS. The following system parameter will be altered: + +- `net.ipv4.conf.all.accept_redirects` +- `net.ipv6.conf.all.accept_redirects` + +</div> + +<div class="cfgcmd"> + +set firewall global-options send-redirects \[enable | disable\] + +enable or disable ICMPv4 redirect messages send by VyOS +The following system parameter will be altered: + +- `net.ipv4.conf.all.send_redirects` + +</div> + +<div class="cfgcmd"> + +set firewall global-options log-martians \[enable | disable\] + +enable or disable the logging of martian IPv4 packets. +The following system parameter will be altered: + +- `net.ipv4.conf.all.log_martians` + +</div> + +<div class="cfgcmd"> + +set firewall global-options source-validation +\[strict | loose | disable\] + +Set the IPv4 source validation mode. +The following system parameter will be altered: + +- `net.ipv4.conf.all.rp_filter` + +</div> + +<div class="cfgcmd"> + +set firewall global-options syn-cookies \[enable | disable\] + +Enable or Disable if VyOS use IPv4 TCP SYN Cookies. +The following system parameter will be altered: + +- `net.ipv4.tcp_syncookies` + +</div> + +<div class="cfgcmd"> + +set firewall global-options twa-hazards-protection +\[enable | disable\] + +Enable or Disable VyOS to be `1337` conform. +The following system parameter will be altered: + +- `net.ipv4.tcp_rfc1337` + +</div> + +<div class="cfgcmd"> + +set firewall global-options state-policy established action +\[accept | drop | reject\] + +</div> + +<div class="cfgcmd"> + +set firewall global-options state-policy established log + +</div> + +<div class="cfgcmd"> + +set firewall global-options state-policy established log-level +\[emerg | alert | crit | err | warn | notice | info | debug\] + +Set the global setting for an established connection. + +</div> + +<div class="cfgcmd"> + +set firewall global-options state-policy invalid action +\[accept | drop | reject\] + +</div> + +<div class="cfgcmd"> + +set firewall global-options state-policy invalid log + +</div> + +<div class="cfgcmd"> + +set firewall global-options state-policy invalid log-level +\[emerg | alert | crit | err | warn | notice | info | debug\] + +Set the global setting for invalid packets. + +</div> + +<div class="cfgcmd"> + +set firewall global-options state-policy related action +\[accept | drop | reject\] + +</div> + +<div class="cfgcmd"> + +set firewall global-options state-policy related log + +</div> + +<div class="cfgcmd"> + +set firewall global-options state-policy related log-level +\[emerg | alert | crit | err | warn | notice | info | debug\] + +Set the global setting for related connections. + +</div> diff --git a/docs/configuration/firewall/md-groups.md b/docs/configuration/firewall/md-groups.md new file mode 100644 index 00000000..926b503d --- /dev/null +++ b/docs/configuration/firewall/md-groups.md @@ -0,0 +1,561 @@ +lastproofread +2023-11-08 + +# Firewall groups + +## Configuration + +Firewall groups represent collections of IP addresses, networks, ports, +mac addresses, domains or interfaces. Once created, a group can be referenced +by firewall, nat and policy route rules as either a source or destination +matcher, and/or as inbound/outbound in the case of interface group. + +### Address Groups + +In an **address group** a single IP address or IP address ranges are +defined. + +<div class="cfgcmd"> + +set firewall group address-group \<name\> address \[address | +address range\] + +</div> + +<div class="cfgcmd"> + +set firewall group ipv6-address-group \<name\> address \<address\> + +Define a IPv4 or a IPv6 address group + +``` none +set firewall group address-group ADR-INSIDE-v4 address 192.168.0.1 +set firewall group address-group ADR-INSIDE-v4 address 10.0.0.1-10.0.0.8 +set firewall group ipv6-address-group ADR-INSIDE-v6 address 2001:db8::1 +``` + +</div> + +<div class="cfgcmd"> + +set firewall group address-group \<name\> description \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall group ipv6-address-group \<name\> description \<text\> + +Provide a IPv4 or IPv6 address group description + +</div> + +### Network Groups + +While **network groups** accept IP networks in CIDR notation, specific +IP addresses can be added as a 32-bit prefix. If you foresee the need +to add a mix of addresses and networks, the network group is +recommended. + +<div class="cfgcmd"> + +set firewall group network-group \<name\> network \<CIDR\> + +</div> + +<div class="cfgcmd"> + +set firewall group ipv6-network-group \<name\> network \<CIDR\> + +Define a IPv4 or IPv6 Network group. + +``` none +set firewall group network-group NET-INSIDE-v4 network 192.168.0.0/24 +set firewall group network-group NET-INSIDE-v4 network 192.168.1.0/24 +set firewall group ipv6-network-group NET-INSIDE-v6 network 2001:db8::/64 +``` + +</div> + +<div class="cfgcmd"> + +set firewall group network-group \<name\> description \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall group ipv6-network-group \<name\> description \<text\> + +Provide an IPv4 or IPv6 network group description. + +</div> + +### Interface Groups + +An **interface group** represents a collection of interfaces. + +<div class="cfgcmd"> + +set firewall group interface-group \<name\> interface \<text\> + +Define an interface group. Wildcard are accepted too. + +</div> + +``` none +set firewall group interface-group LAN interface bond1001 +set firewall group interface-group LAN interface eth3* +``` + +<div class="cfgcmd"> + +set firewall group interface-group \<name\> description \<text\> + +Provide an interface group description + +</div> + +### Port Groups + +A **port group** represents only port numbers, not the protocol. Port +groups can be referenced for either TCP or UDP. It is recommended that +TCP and UDP groups are created separately to avoid accidentally +filtering unnecessary ports. Ranges of ports can be specified by using +<span class="title-ref">-</span>. + +<div class="cfgcmd"> + +set firewall group port-group \<name\> port +\[portname | portnumber | startport-endport\] + +Define a port group. A port name can be any name defined in +/etc/services. e.g.: http + +``` none +set firewall group port-group PORT-TCP-SERVER1 port http +set firewall group port-group PORT-TCP-SERVER1 port 443 +set firewall group port-group PORT-TCP-SERVER1 port 5000-5010 +``` + +</div> + +<div class="cfgcmd"> + +set firewall group port-group \<name\> description \<text\> + +Provide a port group description. + +</div> + +### MAC Groups + +A **mac group** represents a collection of mac addresses. + +<div class="cfgcmd"> + +set firewall group mac-group \<name\> mac-address \<mac-address\> + +Define a mac group. + +</div> + +``` none +set firewall group mac-group MAC-G01 mac-address 88:a4:c2:15:b6:4f +set firewall group mac-group MAC-G01 mac-address 4c:d5:77:c0:19:81 +``` + +<div class="cfgcmd"> + +set firewall group mac-group \<name\> description \<text\> + +Provide a mac group description. + +</div> + +### Domain Groups + +A **domain group** represents a collection of domains. + +<div class="cfgcmd"> + +set firewall group domain-group \<name\> address \<domain\> + +Define a domain group. + +</div> + +``` none +set firewall group domain-group DOM address example.com +``` + +<div class="cfgcmd"> + +set firewall group domain-group \<name\> description \<text\> + +Provide a domain group description. + +</div> + +### Dynamic Groups + +Firewall dynamic groups are different from all the groups defined previously +because, not only they can be used as source/destination in firewall rules, +but members of these groups are not defined statically using vyos +configuration. + +Instead, members of these groups are added dynamically using firewall +rules. + +#### Defining Dynamic Address Groups + +Dynamic address group is supported by both IPv4 and IPv6 families. +Commands used to define dynamic IPv4|IPv6 address groups are: + +<div class="cfgcmd"> + +set firewall group dynamic-group address-group \<name\> + +</div> + +<div class="cfgcmd"> + +set firewall group dynamic-group ipv6-address-group \<name\> + +</div> + +Add description to firewall groups: + +<div class="cfgcmd"> + +set firewall group dynamic-group address-group \<name\> +description \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall group dynamic-group ipv6-address-group \<name\> +description \<text\> + +</div> + +#### Adding elements to Dynamic Firewall Groups + +Once dynamic firewall groups are defined, they should be used in firewall +rules in order to dynamically add elements to it. + +Commands used for this task are: + +- Add destination IP address of the connection to a dynamic address group: + +<div class="cfgcmd"> + +set firewall ipv4 \[forward | input | output\] filter rule +\<1-999999\> add-address-to-group destination-address address-group \<name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> add-address-to-group +destination-address address-group \<name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 \[forward | input | output\] filter rule +\<1-999999\> add-address-to-group destination-address address-group \<name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> add-address-to-group +destination-address address-group \<name\> + +</div> + +- Add source IP address of the connection to a dynamic address group: + +<div class="cfgcmd"> + +set firewall ipv4 \[forward | input | output\] filter rule +\<1-999999\> add-address-to-group source-address address-group \<name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> add-address-to-group +source-address address-group \<name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 \[forward | input | output\] filter rule +\<1-999999\> add-address-to-group source-address address-group \<name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> add-address-to-group +source-address address-group \<name\> + +</div> + +Also, specific timeout can be defined per rule. In case rule gets a hit, +source or destinatination address will be added to the group, and this +element will remain in the group until timeout expires. If no timeout +is defined, then the element will remain in the group until next reboot, +or until a new commit that changes firewall configuration is done. + +<div class="cfgcmd"> + +set firewall ipv4 \[forward | input | output\] filter rule +\<1-999999\> add-address-to-group \[destination-address | source-address\] +timeout \<timeout\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> add-address-to-group +\[destination-address | source-address\] timeout \<timeout\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 \[forward | input | output\] filter rule +\<1-999999\> add-address-to-group \[destination-address | source-address\] +timeout \<timeout\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> add-address-to-group +\[destination-address | source-address\] timeout \<timeout\> + +</div> + +Timeout can be defined using seconds, minutes, hours or days: + +``` none +set firewall ipv6 name FOO rule 10 add-address-to-group source-address timeout +Possible completions: +<number>s Timeout value in seconds +<number>m Timeout value in minutes +<number>h Timeout value in hours +<number>d Timeout value in days +``` + +#### Using Dynamic Firewall Groups + +As any other firewall group, dynamic firewall groups can be used in firewall +rules as matching options. For example: + +``` none +set firewall ipv4 input filter rule 10 source group dynamic-address-group FOO +set firewall ipv4 input filter rule 10 destination group dynamic-address-group BAR +``` + +## Examples + +### General example + +As said before, once firewall groups are created, they can be referenced +either in firewall, nat, nat66 and/or policy-route rules. + +Here is an example were multiple groups are created: + +> ``` none +> set firewall group address-group SERVERS address 198.51.100.101 +> set firewall group address-group SERVERS address 198.51.100.102 +> set firewall group network-group TRUSTEDv4 network 192.0.2.0/30 +> set firewall group network-group TRUSTEDv4 network 203.0.113.128/25 +> set firewall group ipv6-network-group TRUSTEDv6 network 2001:db8::/64 +> set firewall group interface-group LAN interface eth2.2001 +> set firewall group interface-group LAN interface bon0 +> set firewall group port-group PORT-SERVERS port http +> set firewall group port-group PORT-SERVERS port 443 +> set firewall group port-group PORT-SERVERS port 5000-5010 +> ``` + +And next, some configuration example where groups are used: + +> ``` none +> set firewall ipv4 output filter rule 10 action accept +> set firewall ipv4 output filter rule 10 outbound-interface group !LAN +> set firewall ipv4 forward filter rule 20 action accept +> set firewall ipv4 forward filter rule 20 source group network-group TRUSTEDv4 +> set firewall ipv6 input filter rule 10 action accept +> set firewall ipv6 input filter rule 10 source group network-group TRUSTEDv6 +> set nat destination rule 101 inbound-interface group LAN +> set nat destination rule 101 destination group address-group SERVERS +> set nat destination rule 101 protocol tcp +> set nat destination rule 101 destination group port-group PORT-SERVERS +> set nat destination rule 101 translation address 203.0.113.250 +> set policy route PBR rule 201 destination group port-group PORT-SERVERS +> set policy route PBR rule 201 protocol tcp +> set policy route PBR rule 201 set table 15 +> ``` + +### Port knocking example + +Using dynamic firewall groups, we can secure access to the router, or any other +device if needed, by using the technique of port knocking. + +A 4 step port knocking example is shown next: + +> ``` none +> set firewall global-options state-policy established action 'accept' +> set firewall global-options state-policy invalid action 'drop' +> set firewall global-options state-policy related action 'accept' +> set firewall group dynamic-group address-group ALLOWED +> set firewall group dynamic-group address-group PN_01 +> set firewall group dynamic-group address-group PN_02 +> set firewall ipv4 input filter default-action 'drop' +> set firewall ipv4 input filter rule 5 action 'accept' +> set firewall ipv4 input filter rule 5 protocol 'icmp' +> set firewall ipv4 input filter rule 10 action 'drop' +> set firewall ipv4 input filter rule 10 add-address-to-group source-address address-group 'PN_01' +> set firewall ipv4 input filter rule 10 add-address-to-group source-address timeout '2m' +> set firewall ipv4 input filter rule 10 description 'Port_nock 01' +> set firewall ipv4 input filter rule 10 destination port '9990' +> set firewall ipv4 input filter rule 10 protocol 'tcp' +> set firewall ipv4 input filter rule 20 action 'drop' +> set firewall ipv4 input filter rule 20 add-address-to-group source-address address-group 'PN_02' +> set firewall ipv4 input filter rule 20 add-address-to-group source-address timeout '3m' +> set firewall ipv4 input filter rule 20 description 'Port_nock 02' +> set firewall ipv4 input filter rule 20 destination port '9991' +> set firewall ipv4 input filter rule 20 protocol 'tcp' +> set firewall ipv4 input filter rule 20 source group dynamic-address-group 'PN_01' +> set firewall ipv4 input filter rule 30 action 'drop' +> set firewall ipv4 input filter rule 30 add-address-to-group source-address address-group 'ALLOWED' +> set firewall ipv4 input filter rule 30 add-address-to-group source-address timeout '2h' +> set firewall ipv4 input filter rule 30 description 'Port_nock 03' +> set firewall ipv4 input filter rule 30 destination port '9992' +> set firewall ipv4 input filter rule 30 protocol 'tcp' +> set firewall ipv4 input filter rule 30 source group dynamic-address-group 'PN_02' +> set firewall ipv4 input filter rule 99 action 'accept' +> set firewall ipv4 input filter rule 99 description 'Port_nock 04 - Allow ssh' +> set firewall ipv4 input filter rule 99 destination port '22' +> set firewall ipv4 input filter rule 99 protocol 'tcp' +> set firewall ipv4 input filter rule 99 source group dynamic-address-group 'ALLOWED' +> ``` + +Before testing, we can check members of firewall groups: + +> ``` none +> vyos@vyos# run show firewall group +> Firewall Groups +> +> Name Type References Members Timeout Expires +> ------- ---------------------- -------------------- ------------- --------- --------- +> ALLOWED address_group(dynamic) ipv4-input-filter-30 N/D N/D N/D +> PN_01 address_group(dynamic) ipv4-input-filter-10 N/D N/D N/D +> PN_02 address_group(dynamic) ipv4-input-filter-20 N/D N/D N/D +> [edit] +> vyos@vyos# +> ``` + +With this configuration, in order to get ssh access to the router, user +needs to: + +1\. Generate a new TCP connection with destination port 9990. As shown next, +a new entry was added to dynamic firewall group **PN_01** + +> ``` none +> vyos@vyos# run show firewall group +> Firewall Groups +> +> Name Type References Members Timeout Expires +> ------- ---------------------- -------------------- ------------- --------- --------- +> ALLOWED address_group(dynamic) ipv4-input-filter-30 N/D N/D N/D +> PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.89.31 120 119 +> PN_02 address_group(dynamic) ipv4-input-filter-20 N/D N/D N/D +> [edit] +> vyos@vyos# +> ``` + +2\. Generate a new TCP connection with destination port 9991. As shown next, +a new entry was added to dynamic firewall group **PN_02** + +> ``` none +> vyos@vyos# run show firewall group +> Firewall Groups +> +> Name Type References Members Timeout Expires +> ------- ---------------------- -------------------- ------------- --------- --------- +> ALLOWED address_group(dynamic) ipv4-input-filter-30 N/D N/D N/D +> PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.89.31 120 106 +> PN_02 address_group(dynamic) ipv4-input-filter-20 192.168.89.31 180 179 +> [edit] +> vyos@vyos# +> ``` + +3\. Generate a new TCP connection with destination port 9992. As shown next, +a new entry was added to dynamic firewall group **ALLOWED** + +> ``` none +> vyos@vyos# run show firewall group +> Firewall Groups +> +> Name Type References Members Timeout Expires +> ------- ---------------------- -------------------- ------------- --------- --------- +> ALLOWED address_group(dynamic) ipv4-input-filter-30 192.168.89.31 7200 7199 +> PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.89.31 120 89 +> PN_02 address_group(dynamic) ipv4-input-filter-20 192.168.89.31 180 170 +> [edit] +> vyos@vyos# +> ``` + +4. Now user can connect through ssh to the router (assuming ssh is configured). + +## Operation-mode + +<div class="opcmd"> + +show firewall group + +</div> + +<div class="opcmd"> + +show firewall group \<name\> + +Overview of defined groups. You see the firewall group name, type, +references (where the group is used), members, timeout and expiration (last +two only present in dynamic firewall groups). + +</div> + +Here is an example of such command: + +> ``` none +> vyos@vyos:~$ show firewall group +> Firewall Groups +> +> Name Type References Members Timeout Expires +> ------------ ---------------------- ---------------------- ---------------- --------- --------- +> SERVERS address_group nat-destination-101 198.51.100.101 +> 198.51.100.102 +> ALLOWED address_group(dynamic) ipv4-input-filter-30 192.168.77.39 7200 7174 +> PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.0.245 120 112 +> 192.168.77.39 120 85 +> PN_02 address_group(dynamic) ipv4-input-filter-20 192.168.77.39 180 151 +> LAN interface_group ipv4-output-filter-10 bon0 +> nat-destination-101 eth2.2001 +> TRUSTEDv6 ipv6_network_group ipv6-input-filter-10 2001:db8::/64 +> TRUSTEDv4 network_group ipv4-forward-filter-20 192.0.2.0/30 +> 203.0.113.128/25 +> PORT-SERVERS port_group route-PBR-201 443 +> route-PBR-201 5000-5010 +> nat-destination-101 http +> vyos@vyos:~$ +> ``` diff --git a/docs/configuration/firewall/md-index.md b/docs/configuration/firewall/md-index.md new file mode 100644 index 00000000..a7511536 --- /dev/null +++ b/docs/configuration/firewall/md-index.md @@ -0,0 +1,181 @@ +lastproofread +2023-11-23 + +# Firewall + +As VyOS is based on Linux it leverages its firewall. The Netfilter project +created iptables and its successor nftables for the Linux kernel to +work directly on packet data flows. This now extends the concept of +zone-based security to allow for manipulating the data at multiple stages once +accepted by the network interface and the driver before being handed off to +the destination (e.g., a web server OR another device). + +A simplified traffic flow diagram, based on Netfilter packet flow, is shown +next, in order to have a full view and understanding of how packets are +processed, and what possible paths traffic can take. + +<figure> +<img src="/_static/images/firewall-gral-packet-flow.webp" /> +</figure> + +The main points regarding this packet flow and terminology used in VyOS +firewall are covered below: + +> - **Bridge Port?**: choose appropriate path based on whether interface +> where the packet was received is part of a bridge, or not. + +If the interface where the packet was received isn't part of a bridge, then +packetis processed at the **IP Layer**: + +> - **Prerouting**: several actions can be done in this stage, and currently +> these actions are defined in different parts in VyOS configuration. Order +> is important, and all these actions are performed before any actions +> defined under `firewall` section. Relevant configuration that acts in +> this stage are: +> +> > - **Conntrack Ignore**: rules defined under `set system conntrack ignore [ipv4 | ipv6] ...`. +> > - **Policy Route**: rules defined under `set policy [route | route6] ...`. +> > - **Destination NAT**: rules defined under `set [nat | nat66] destination...`. +> +> - **Destination is the router?**: choose appropriate path based on +> destination IP address. Transit forward continues to **forward**, +> while traffic that destination IP address is configured on the router +> continues to **input**. +> +> - **Input**: stage where traffic destined for the router itself can be +> filtered and controlled. This is where all rules for securing the router +> should take place. This includes ipv4 and ipv6 filtering rules, defined +> in: +> +> - `set firewall ipv4 input filter ...`. +> - `set firewall ipv6 input filter ...`. +> +> - **Forward**: stage where transit traffic can be filtered and controlled. +> This includes ipv4 and ipv6 filtering rules, defined in: +> +> - `set firewall ipv4 forward filter ...`. +> - `set firewall ipv6 forward filter ...`. +> +> - **Output**: stage where traffic that originates from the router itself +> can be filtered and controlled. Bear in mind that this traffic can be a +> new connection originated by a internal process running on VyOS router, +> such as NTP, or a response to traffic received externaly through +> **input** (for example response to an ssh login attempt to the router). +> This includes ipv4 and ipv6 filtering rules, defined in: +> +> - `set firewall ipv4 output filter ...`. +> - `set firewall ipv6 output filter ...`. +> +> - **Postrouting**: as in **Prerouting**, several actions defined in +> different parts of VyOS configuration are performed in this +> stage. This includes: +> +> - **Source NAT**: rules defined under `set [nat | nat66] source...`. + +If the interface where the packet was received is part of a bridge, then +the packet is processed at the **Bridge Layer**, which contains a basic setup for +bridge filtering: + +> - **Forward (Bridge)**: stage where traffic that is trespasing through the +> bridge is filtered and controlled: +> - `set firewall bridge forward filter ...`. + +The main structure of the VyOS firewall CLI is shown next: + +``` none +- set firewall + * bridge + - forward + + filter + * flowtable + - custom_flow_table + + ... + * global-options + + all-ping + + broadcast-ping + + ... + * group + - address-group + - ipv6-address-group + - network-group + - ipv6-network-group + - interface-group + - mac-group + - port-group + - domain-group + * ipv4 + - forward + + filter + - input + + filter + - output + + filter + - name + + custom_name + * ipv6 + - forward + + filter + - input + + filter + - output + + filter + - ipv6-name + + custom_name + * zone + - custom_zone_name + + ... +``` + +Please, refer to appropriate section for more information about firewall +configuration: + +<div class="toctree" maxdepth="1" includehidden=""> + +global-options +groups +bridge +ipv4 +ipv6 +flowtables + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +**For more information** +of Netfilter hooks and Linux networking packet flows can be +found in [Netfilter-Hooks](https://wiki.nftables.org/wiki-nftables/index.php/Netfilter_hooks) + +</div> + +## Zone-based firewall + +<div class="toctree" maxdepth="1" includehidden=""> + +zone + +</div> + +With zone-based firewalls a new concept was implemented, in addition to the +standard in and out traffic flows, a local flow was added. This local was for +traffic originating and destined to the router itself. Which means additional +rules were required to secure the firewall itself from the network, in +addition to the existing inbound and outbound rules from the traditional +concept above. + +To configure VyOS with the +`zone-based firewall configuration </configuration/firewall/zone>` + +As the example image below shows, the device now needs rules to allow/block +traffic to or from the services running on the device that have open +connections on that interface. + +<figure> +<img src="/_static/images/firewall-zonebased.webp" /> +</figure> diff --git a/docs/configuration/firewall/md-ipv4.md b/docs/configuration/firewall/md-ipv4.md new file mode 100644 index 00000000..7ac0ff49 --- /dev/null +++ b/docs/configuration/firewall/md-ipv4.md @@ -0,0 +1,2657 @@ +lastproofread +2023-11-08 + +# IPv4 Firewall Configuration + +## Overview + +In this section there's useful information of all firewall configuration that +can be done regarding IPv4, and appropiate op-mode commands. +Configuration commands covered in this section: + +<div class="cfgcmd"> + +set firewall ipv4 ... + +</div> + +From main structure defined in +`Firewall Overview</configuration/firewall/index>` +in this section you can find detailed information only for the next part +of the general structure: + +``` none +- set firewall + * ipv4 + - forward + + filter + - input + + filter + - output + + filter + - name + + custom_name +``` + +For transit traffic, which is received by the router and forwarded, base chain +is **forward**. A simplified packet flow diagram for transit traffic is shown +next: + +<figure> +<img src="/_static/images/firewall-fwd-packet-flow.webp" /> +</figure> + +Where firewall base chain to configure firewall filtering rules for transit +traffic is `set firewall ipv4 forward filter ...`, which happens in stage 5, +highlightened with red color. + +For traffic towards the router itself, base chain is **input**, while traffic +originated by the router, base chain is **output**. +A new simplified packet flow diagram is shown next, which shows the path +for traffic destinated to the router itself, and traffic generated by the +router (starting from circle number 6): + +<figure> +<img src="/_static/images/firewall-input-packet-flow.webp" /> +</figure> + +Base chain is for traffic toward the router is `set firewall ipv4 input filter ...` + +And base chain for traffic generated by the router is `set firewall ipv4 output filter ...` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +**Important note about default-actions:** +If default action for any base chain is not defined, then the default +action is set to **accept** for that chain. For custom chains, if default +action is not defined, then the default-action is set to **drop** + +</div> + +Custom firewall chains can be created, with commands +`set firewall ipv4 name <name> ...`. In order to use +such custom chain, a rule with **action jump**, and the appropiate **target** +should be defined in a base chain. + +## Firewall - IPv4 Rules + +For firewall filtering, firewall rules needs to be created. Each rule is +numbered, has an action to apply if the rule is matched, and the ability +to specify multiple criteria matchers. Data packets go through the rules +from 1 - 999999, so order is crucial. At the first match the action of the +rule will be executed. + +### Actions + +If a rule is defined, then an action must be defined for it. This tells the +firewall what to do if all criteria matchers defined for such rule do match. + +The action can be : + +> - `accept`: accept the packet. +> - `continue`: continue parsing next rule. +> - `drop`: drop the packet. +> - `reject`: reject the packet. +> - `jump`: jump to another custom chain. +> - `return`: Return from the current chain and continue at the next rule +> of the last chain. +> - `queue`: Enqueue packet to userspace. +> - `synproxy`: synproxy the packet. + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> action +\[accept | continue | drop | jump | queue | reject | return | synproxy\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> action +\[accept | continue | drop | jump | queue | reject | return | synproxy\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> action +\[accept | continue | drop | jump | queue | reject | return\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> action +\[accept | continue | drop | jump | queue | reject | return\] + +This required setting defines the action of the current rule. If action is +set to jump, then jump-target is also needed. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +jump-target \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +jump-target \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +jump-target \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +jump-target \<text\> + +To be used only when action is set to `jump`. Use this command to specify +jump target. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +queue \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +queue \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +queue \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +queue \<0-65535\> + +To be used only when action is set to `queue`. Use this command to specify +queue target to use. Queue range is also supported. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +queue-options bypass + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +queue-options bypass + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +queue-options bypass + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +queue-options bypass + +To be used only when action is set to `queue`. Use this command to let +packet go through firewall when no userspace software is connected to the +queue. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +queue-options fanout + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +queue-options fanout + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +queue-options fanout + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +queue-options fanout + +To be used only when action is set to `queue`. Use this command to +distribute packets between several queues. + +</div> + +Also, **default-action** is an action that takes place whenever a packet does +not match any rule in it's chain. For base chains, possible options for +**default-action** are **accept** or **drop**. + +<div class="cfgcmd"> + +set firewall ipv4 forward filter default-action +\[accept | drop\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter default-action +\[accept | drop\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter default-action +\[accept | drop\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> default-action +\[accept | drop | jump | queue | reject | return\] + +This set the default action of the rule-set if no rule matched a packet +criteria. If default-action is set to `jump`, then +`default-jump-target` is also needed. Note that for base chains, default +action can only be set to `accept` or `drop`, while on custom chain, +more actions are available. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> default-jump-target \<text\> + +To be used only when `defult-action` is set to `jump`. Use this +command to specify jump target for default rule. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +**Important note about default-actions:** +If default action for any base chain is not defined, then the default +action is set to **accept** for that chain. For custom chains, if default +action is not defined, then the default-action is set to **drop**. + +</div> + +### Firewall Logs + +Logging can be enable for every single firewall rule. If enabled, other +log options can be defined. + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> log + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> log + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> log + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> log + +Enable logging for the matched packet. If this configuration command is not +present, then log is not enabled. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter default-log + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter default-log + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter default-log + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> default-log + +Use this command to enable the logging of the default action on +the specified chain. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +log-options level \[emerg | alert | crit | err | warn | notice +| info | debug\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +log-options level \[emerg | alert | crit | err | warn | notice +| info | debug\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +log-options level \[emerg | alert | crit | err | warn | notice +| info | debug\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +log-options level \[emerg | alert | crit | err | warn | notice +| info | debug\] + +Define log-level. Only applicable if rule log is enable. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +log-options group \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +log-options group \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +log-options group \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +log-options group \<0-65535\> + +Define log group to send message to. Only applicable if rule log is enable. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +log-options snapshot-length \<0-9000\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +log-options snapshot-length \<0-9000\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +log-options snapshot-length \<0-9000\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +log-options snapshot-length \<0-9000\> + +Define length of packet payload to include in netlink message. Only +applicable if rule log is enable and log group is defined. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +log-options queue-threshold \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +log-options queue-threshold \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +log-options queue-threshold \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +log-options queue-threshold \<0-65535\> + +Define number of packets to queue inside the kernel before sending them to +userspace. Only applicable if rule log is enable and log group is defined. + +</div> + +### Firewall Description + +For reference, a description can be defined for every single rule, and for +every defined custom chain. + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> description \<text\> + +Provide a rule-set description to a custom firewall chain. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +description \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +description \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +description \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> description \<text\> + +Provide a description for each rule. + +</div> + +### Rule Status + +When defining a rule, it is enable by default. In some cases, it is useful to +just disable the rule, rather than removing it. + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> disable + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> disable + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> disable + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> disable + +Command for disabling a rule but keep it in the configuration. + +</div> + +### Matching criteria + +There are a lot of matching criteria against which the packet can be tested. + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +connection-status nat \[destination | source\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +connection-status nat \[destination | source\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +connection-status nat \[destination | source\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +connection-status nat \[destination | source\] + +Match criteria based on nat connection status. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +connection-mark \<1-2147483647\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +connection-mark \<1-2147483647\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +connection-mark \<1-2147483647\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +connection-mark \<1-2147483647\> + +Match criteria based on connection mark. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +source address \[address | addressrange | CIDR\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +source address \[address | addressrange | CIDR\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +source address \[address | addressrange | CIDR\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +source address \[address | addressrange | CIDR\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +destination address \[address | addressrange | CIDR\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +destination address \[address | addressrange | CIDR\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +destination address \[address | addressrange | CIDR\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +destination address \[address | addressrange | CIDR\] + +Match criteria based on source and/or destination address. This is similar +to the network groups part, but here you are able to negate the matching +addresses. + +``` none +set firewall ipv4 name FOO rule 50 source address 192.0.2.10-192.0.2.11 +# with a '!' the rule match everything except the specified subnet +set firewall ipv4 name FOO rule 51 source address !203.0.113.0/24 +``` + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +source address-mask \[address\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +source address-mask \[address\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +source address-mask \[address\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +source address-mask \[address\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +destination address-mask \[address\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +destination address-mask \[address\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +destination address-mask \[address\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +destination address-mask \[address\] + +An arbitrary netmask can be applied to mask addresses to only match against +a specific portion. + +This functions for both individual addresses and address groups. + +``` none +# Match any IPv4 address with `11` as the 2nd octet and `13` as the forth octet +set firewall ipv4 name FOO rule 100 destination address 0.11.0.13 +set firewall ipv4 name FOO rule 100 destination address-mask 0.255.0.255 +``` + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +source fqdn \<fqdn\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +source fqdn \<fqdn\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +source fqdn \<fqdn\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +source fqdn \<fqdn\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +destination fqdn \<fqdn\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +destination fqdn \<fqdn\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +destination fqdn \<fqdn\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +destination fqdn \<fqdn\> + +Specify a Fully Qualified Domain Name as source/destination matcher. Ensure +router is able to resolve such dns query. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +source geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +source geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +source geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +source geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +destination geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +destination geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +destination geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +destination geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +source geoip inverse-match + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +source geoip inverse-match + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +source geoip inverse-match + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +source geoip inverse-match + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +destination geoip inverse-match + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +destination geoip inverse-match + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +destination geoip inverse-match + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +destination geoip inverse-match + +Match IP addresses based on its geolocation. More info: [geoip matching](https://wiki.nftables.org/wiki-nftables/index.php/GeoIP_matching). +Use inverse-match to match anything except the given country-codes. + +</div> + +Data is provided by DB-IP.com under CC-BY-4.0 license. Attribution required, +permits redistribution so we can include a database in images(~3MB +compressed). Includes cron script (manually callable by op-mode update +geoip) to keep database and rules updated. + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +source mac-address \<mac-address\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +source mac-address \<mac-address\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +source mac-address \<mac-address\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +source mac-address \<mac-address\> + +Only in the source criteria, you can specify a mac-address. + +``` none +set firewall ipv4 input filter rule 100 source mac-address 00:53:00:11:22:33 +set firewall ipv4 input filter rule 101 source mac-address !00:53:00:aa:12:34 +``` + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +source port \[1-65535 | portname | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +source port \[1-65535 | portname | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +source port \[1-65535 | portname | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +source port \[1-65535 | portname | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +destination port \[1-65535 | portname | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +destination port \[1-65535 | portname | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +destination port \[1-65535 | portname | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +destination port \[1-65535 | portname | start-end\] + +A port can be set with a port number or a name which is here +defined: `/etc/services`. + +``` none +set firewall ipv4 forward filter rule 10 source port '22' +set firewall ipv4 forward filter rule 11 source port '!http' +set firewall ipv4 forward filter rule 12 source port 'https' +``` + +Multiple source ports can be specified as a comma-separated list. +The whole list can also be "negated" using `!`. For example: + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +source group address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +source group address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +source group address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +source group address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +destination group address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +destination group address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +destination group address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +destination group address-group \<name | !name\> + +Use a specific address-group. Prepend character `!` for inverted matching +criteria. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +source group dynamic-address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +source group dynamic-address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +source group dynamic-address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +source group dynamic-address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +destination group dynamic-address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +destination group dynamic-address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +destination group dynamic-address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +destination group dynamic-address-group \<name | !name\> + +Use a specific dynamic-address-group. Prepend character `!` for inverted +matching criteria. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +source group network-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +source group network-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +source group network-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +source group network-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +destination group network-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +destination group network-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +destination group network-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +destination group network-group \<name | !name\> + +Use a specific network-group. Prepend character `!` for inverted matching +criteria. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +source group port-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +source group port-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +source group port-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +source group port-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +destination group port-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +destination group port-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +destination group port-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +destination group port-group \<name | !name\> + +Use a specific port-group. Prepend character `!` for inverted matching +criteria. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +source group domain-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +source group domain-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +source group domain-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +source group domain-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +destination group domain-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +destination group domain-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +destination group domain-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +destination group domain-group \<name | !name\> + +Use a specific domain-group. Prepend character `!` for inverted matching +criteria. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +source group mac-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +source group mac-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +source group mac-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +source group mac-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +destination group mac-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +destination group mac-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +destination group mac-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +destination group mac-group \<name | !name\> + +Use a specific mac-group. Prepend character `!` for inverted matching +criteria. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +dscp \[0-63 | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +dscp \[0-63 | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +dscp \[0-63 | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +dscp \[0-63 | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +dscp-exclude \[0-63 | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +dscp-exclude \[0-63 | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +dscp-exclude \[0-63 | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +dscp-exclude \[0-63 | start-end\] + +Match based on dscp value. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +fragment \[match-frag | match-non-frag\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +fragment \[match-frag | match-non-frag\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +fragment \[match-frag | match-non-frag\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +fragment \[match-frag | match-non-frag\] + +Match based on fragment criteria. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +icmp \[code | type\] \<0-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +icmp \[code | type\] \<0-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +icmp \[code | type\] \<0-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +icmp \[code | type\] \<0-255\> + +Match based on icmp code and type. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +icmp type-name \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +icmp type-name \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +icmp type-name \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +icmp type-name \<text\> + +Match based on icmp type-name criteria. Use tab for information +about what **type-name** criteria are supported. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +inbound-interface name \<iface\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +inbound-interface name \<iface\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +inbound-interface name \<iface\> + +Match based on inbound interface. Wilcard `*` can be used. +For example: `eth2*`. Prepending character `!` for inverted matching +criteria is also supportd. For example `!eth2` + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If an interface is attached to a non-default vrf, when using +**inbound-interface**, vrf name must be used. For example `set firewall ipv4 forward filter rule 10 inbound-interface name MGMT` + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +inbound-interface group \<iface_group\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +inbound-interface group \<iface_group\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +inbound-interface group \<iface_group\> + +Match based on inbound interface group. Prepending character `!` for +inverted matching criteria is also supportd. For example `!IFACE_GROUP` + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +outbound-interface name \<iface\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +outbound-interface name \<iface\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +outbound-interface name \<iface\> + +Match based on outbound interface. Wilcard `*` can be used. +For example: `eth2*`. Prepending character `!` for inverted matching +criteria is also supportd. For example `!eth2` + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If an interface is attached to a non-default vrf, when using +**outbound-interface**, real interface name must be used. For example +`set firewall ipv4 forward filter rule 10 outbound-interface name eth0` + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +outbound-interface group \<iface_group\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +outbound-interface group \<iface_group\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +outbound-interface group \<iface_group\> + +Match based on outbound interface group. Prepending character `!` for +inverted matching criteria is also supportd. For example `!IFACE_GROUP` + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +ipsec \[match-ipsec | match-none\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +ipsec \[match-ipsec | match-none\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +ipsec \[match-ipsec | match-none\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +ipsec \[match-ipsec | match-none\] + +Match based on ipsec criteria. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +limit burst \<0-4294967295\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +limit burst \<0-4294967295\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +limit burst \<0-4294967295\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +limit burst \<0-4294967295\> + +Match based on the maximum number of packets to allow in excess of rate. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +limit rate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +limit rate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +limit rate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +limit rate \<text\> + +Match based on the maximum average rate, specified as **integer/unit**. +For example **5/minutes** + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +packet-length \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +packet-length \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +packet-length \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +packet-length \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +packet-length-exclude \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +packet-length-exclude \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +packet-length-exclude \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +packet-length-exclude \<text\> + +Match based on packet length criteria. Multiple values from 1 to 65535 +and ranges are supported. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +packet-type \[broadcast | host | multicast | other\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +packet-type \[broadcast | host | multicast | other\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +packet-type \[broadcast | host | multicast | other\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +packet-type \[broadcast | host | multicast | other\] + +Match based on packet type criteria. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +protocol \[\<text\> | \<0-255\> | all | tcp_udp\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +protocol \[\<text\> | \<0-255\> | all | tcp_udp\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +protocol \[\<text\> | \<0-255\> | all | tcp_udp\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +protocol \[\<text\> | \<0-255\> | all | tcp_udp\] + +Match a protocol criteria. A protocol number or a name which is here +defined: `/etc/protocols`. +Special names are `all` for all protocols and `tcp_udp` for tcp and udp +based packets. The `!` negate the selected protocol. + +``` none +set firewall ipv4 forward fitler rule 10 protocol tcp_udp +set firewall ipv4 forward fitler rule 11 protocol !tcp_udp +``` + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +recent time \[second | minute | hour\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +recent time \[second | minute | hour\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +recent time \[second | minute | hour\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +recent time \[second | minute | hour\] + +Match bases on recently seen sources. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +tcp flags \[not\] \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +tcp flags \[not\] \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +tcp flags \[not\] \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +tcp flags \[not\] \<text\> + +Allowed values fpr TCP flags: `ack`, `cwr`, `ecn`, `fin`, `psh`, +`rst`, `syn` and `urg`. Multiple values are supported, and for +inverted selection use `not`, as shown in the example. + +``` none +set firewall ipv4 input filter rule 10 tcp flags 'ack' +set firewall ipv4 input filter rule 12 tcp flags 'syn' +set firewall ipv4 input filter rule 13 tcp flags not 'fin' +``` + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +state \[established | invalid | new | related\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +state \[established | invalid | new | related\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +state \[established | invalid | new | related\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +state \[established | invalid | new | related\] + +Match against the state of a packet. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +time startdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +time startdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +time startdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +time startdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +time starttime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +time starttime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +time starttime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +time starttime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +time stopdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +time stopdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +time stopdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +time stopdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +time stoptime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +time stoptime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +time stoptime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +time stoptime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +time weekdays \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +time weekdays \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +time weekdays \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +time weekdays \<text\> + +Time to match the defined rule. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +ttl \<eq | gt | lt\> \<0-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +ttl \<eq | gt | lt\> \<0-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +ttl \<eq | gt | lt\> \<0-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +ttl \<eq | gt | lt\> \<0-255\> + +Match time to live parameter, where 'eq' stands for 'equal'; 'gt' stands for +'greater than', and 'lt' stands for 'less than'. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +recent time \<second | minute | hour\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +recent time \<second | minute | hour\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +recent time \<second | minute | hour\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +recent time \<second | minute | hour\> + +Match when 'count' amount of connections are seen within 'time'. These +matching criteria can be used to block brute-force attempts. + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 forward filter rule \<1-999999\> +conntrack-helper \<module\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 input filter rule \<1-999999\> +conntrack-helper \<module\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 output filter rule \<1-999999\> +conntrack-helper \<module\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 name \<name\> rule \<1-999999\> +conntrack-helper \<module\> + +Match based on connection tracking protocol helper module to secure use of +that helper module. See below for possible completions <span class="title-ref">\<module\></span>. + +``` none +Possible completions: + ftp Related traffic from FTP helper + h323 Related traffic from H.323 helper + pptp Related traffic from PPTP helper + nfs Related traffic from NFS helper + sip Related traffic from SIP helper + tftp Related traffic from TFTP helper + sqlnet Related traffic from SQLNet helper +``` + +</div> + +## Synproxy + +Synproxy connections + +<div class="cfgcmd"> + +set firewall ipv4 \[input | forward\] filter rule \<1-999999\> +action synproxy + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 \[input | forward\] filter rule \<1-999999\> +protocol tcp + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 \[input | forward\] filter rule \<1-999999\> +synproxy tcp mss \<501-65535\> + +Set TCP-MSS (maximum segment size) for the connection + +</div> + +<div class="cfgcmd"> + +set firewall ipv4 \[input | forward\] filter rule \<1-999999\> +synproxy tcp window-scale \<1-14\> + +Set the window scale factor for TCP window scaling + +</div> + +### Example synproxy + +Requirements to enable synproxy: + +> - Traffic must be symmetric +> - Synproxy relies on syncookies and TCP timestamps, ensure these are enabled +> - Disable conntrack loose track option + +``` none +set system sysctl parameter net.ipv4.tcp_timestamps value '1' + +set system conntrack tcp loose disable +set system conntrack ignore ipv4 rule 10 destination port '8080' +set system conntrack ignore ipv4 rule 10 protocol 'tcp' +set system conntrack ignore ipv4 rule 10 tcp flags syn + +set firewall global-options syn-cookies 'enable' +set firewall ipv4 input filter rule 10 action 'synproxy' +set firewall ipv4 input filter rule 10 destination port '8080' +set firewall ipv4 input filter rule 10 inbound-interface name 'eth1' +set firewall ipv4 input filter rule 10 protocol 'tcp' +set firewall ipv4 input filter rule 10 synproxy tcp mss '1460' +set firewall ipv4 input filter rule 10 synproxy tcp window-scale '7' +set firewall ipv4 input filter rule 1000 action 'drop' +set firewall ipv4 input filter rule 1000 state invalid +``` + +## Operation-mode Firewall + +### Rule-set overview + +<div class="opcmd"> + +show firewall + +This will show you a basic firewall overview, for all ruleset, and not +only for ipv4 + +``` none +vyos@vyos:~$ show firewall +Rulesets Information + +--------------------------------- +ipv4 Firewall "forward filter" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- ----------------------------- +20 accept all 0 0 ip saddr @N_TRUSTEDv4 accept +21 jump all 0 0 jump NAME_AUX +default accept all 0 0 + +--------------------------------- +ipv4 Firewall "input filter" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- ------------------------- +10 accept all 156 14377 iifname != @I_LAN accept +default accept all 0 0 + +--------------------------------- +ipv4 Firewall "name AUX" + + Rule Action Protocol Packets Bytes Conditions +------ -------- ---------- --------- ------- -------------------------------------------- + 10 accept icmp 0 0 meta l4proto icmp accept + 20 accept udp 0 0 meta l4proto udp ip saddr @A_SERVERS accept + 30 drop all 0 0 ip saddr != @A_SERVERS iifname "eth2" + +--------------------------------- +ipv4 Firewall "output filter" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- ---------------------------------------- +10 reject all 0 0 oifname @I_LAN +20 accept icmp 2 168 meta l4proto icmp oifname "eth0" accept +default accept all 72 9258 + +--------------------------------- +ipv6 Firewall "input filter" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- ------------------------------- +10 accept all 0 0 ip6 saddr @N6_TRUSTEDv6 accept +default accept all 2 112 + +vyos@vyos:~$ +``` + +</div> + +<div class="opcmd"> + +show firewall summary + +This will show you a summary of rule-sets and groups + +``` none +vyos@vyos:~$ show firewall summary +Ruleset Summary + +IPv6 Ruleset: + +Ruleset Hook Ruleset Priority Description +-------------- -------------------- ------------------------- +forward filter +input filter +ipv6_name IPV6-VyOS_MANAGEMENT +ipv6_name IPV6-WAN_IN PUBLIC_INTERNET + +IPv4 Ruleset: + +Ruleset Hook Ruleset Priority Description +-------------- ------------------ ------------------------- +forward filter +input filter +name VyOS_MANAGEMENT +name WAN_IN PUBLIC_INTERNET + +Firewall Groups + +Name Type References Members +----------------------- ------------------ ----------------------- ---------------- +PBX address_group WAN_IN-100 198.51.100.77 +SERVERS address_group WAN_IN-110 192.0.2.10 + WAN_IN-111 192.0.2.11 + WAN_IN-112 192.0.2.12 + WAN_IN-120 + WAN_IN-121 + WAN_IN-122 +SUPPORT address_group VyOS_MANAGEMENT-20 192.168.1.2 + WAN_IN-20 +PHONE_VPN_SERVERS address_group WAN_IN-160 10.6.32.2 +PINGABLE_ADRESSES address_group WAN_IN-170 192.168.5.2 + WAN_IN-171 +PBX ipv6_address_group IPV6-WAN_IN-100 2001:db8::1 +SERVERS ipv6_address_group IPV6-WAN_IN-110 2001:db8::2 + IPV6-WAN_IN-111 2001:db8::3 + IPV6-WAN_IN-112 2001:db8::4 + IPV6-WAN_IN-120 + IPV6-WAN_IN-121 + IPV6-WAN_IN-122 +SUPPORT ipv6_address_group IPV6-VyOS_MANAGEMENT-20 2001:db8::5 + IPV6-WAN_IN-20 +``` + +</div> + +<div class="opcmd"> + +show firewall ipv4 \[forward | input | output\] filter + +</div> + +<div class="opcmd"> + +show firewall ipv4 name \<name\> + +This command will give an overview of a single rule-set. + +``` none +vyos@vyos:~$ show firewall ipv4 input filter +Ruleset Information + +--------------------------------- +IPv4 Firewall "input filter" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- ----------------------------------------- +5 jump all 0 0 iifname "eth2" jump NAME_VyOS_MANAGEMENT +default accept all +``` + +</div> + +<div class="opcmd"> + +show firewall ipv4 \[forward | input | output\] +filter rule \<1-999999\> + +</div> + +<div class="opcmd"> + +show firewall ipv4 name \<name\> rule \<1-999999\> + +This command will give an overview of a rule in a single rule-set, plus +information for default action. + +</div> + +``` none +vyos@vyos:~$show firewall ipv4 output filter rule 20 +Rule Information + +--------------------------------- +ipv4 Firewall "output filter" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- ---------------------------------------- +20 accept icmp 2 168 meta l4proto icmp oifname "eth0" accept +default accept all 286 47614 + +vyos@vyos:~$ +``` + +<div class="opcmd"> + +show firewall statistics + +This will show you a statistic of all rule-sets since the last boot. + +</div> + +### Show Firewall log + +<div class="opcmd"> + +show log firewall + +</div> + +<div class="opcmd"> + +show log firewall ipv4 + +</div> + +<div class="opcmd"> + +show log firewall ipv4 \[forward | input | output | name\] + +</div> + +<div class="opcmd"> + +show log firewall ipv4 \[forward | input | output\] filter + +</div> + +<div class="opcmd"> + +show log firewall ipv4 name \<name\> + +</div> + +<div class="opcmd"> + +show log firewall ipv4 \[forward | input | output\] filter rule \<rule\> + +</div> + +<div class="opcmd"> + +show log firewall ipv4 name \<name\> rule \<rule\> + +Show the logs of all firewall; show all ipv4 firewall logs; show all logs +for particular hook; show all logs for particular hook and priority; +show all logs for particular custom chain; show logs for specific Rule-Set. + +</div> + +### Example Partial Config + +``` none +firewall { + group { + network-group BAD-NETWORKS { + network 198.51.100.0/24 + network 203.0.113.0/24 + } + network-group GOOD-NETWORKS { + network 192.0.2.0/24 + } + port-group BAD-PORTS { + port 65535 + } + } + ipv4 { + forward { + filter { + default-action accept + rule 5 { + action accept + source { + group { + network-group GOOD-NETWORKS + } + } + } + rule 10 { + action drop + description "Bad Networks" + protocol all + source { + group { + network-group BAD-NETWORKS + } + } + } + } + } + } +} +``` + +### Update geoip database + +<div class="opcmd"> + +update geoip + +Command used to update GeoIP database and firewall sets. + +</div> diff --git a/docs/configuration/firewall/md-ipv6.md b/docs/configuration/firewall/md-ipv6.md new file mode 100644 index 00000000..a6c2aabf --- /dev/null +++ b/docs/configuration/firewall/md-ipv6.md @@ -0,0 +1,2638 @@ +lastproofread +2023-11-08 + +# IPv6 Firewall Configuration + +## Overview + +In this section there's useful information of all firewall configuration that +can be done regarding IPv6, and appropiate op-mode commands. +Configuration commands covered in this section: + +<div class="cfgcmd"> + +set firewall ipv6 ... + +</div> + +From main structure defined in +`Firewall Overview</configuration/firewall/index>` +in this section you can find detailed information only for the next part +of the general structure: + +``` none +- set firewall + * ipv6 + - forward + + filter + - input + + filter + - output + + filter + - name + + custom_name +``` + +For transit traffic, which is received by the router and forwarded, base chain +is **forward**. A simplified packet flow diagram for transit traffic is shown +next: + +<figure> +<img src="/_static/images/firewall-fwd-packet-flow.webp" /> +</figure> + +Where firewall base chain to configure firewall filtering rules for transit +traffic is `set firewall ipv6 forward filter ...`, which happens in stage 5, +highlightened with red color. + +For traffic towards the router itself, base chain is **input**, while traffic +originated by the router, base chain is **output**. +A new simplified packet flow diagram is shown next, which shows the path +for traffic destinated to the router itself, and traffic generated by the +router (starting from circle number 6): + +<figure> +<img src="/_static/images/firewall-input-packet-flow.webp" /> +</figure> + +Base chain is for traffic toward the router is `set firewall ipv6 input filter ...` + +And base chain for traffic generated by the router is `set firewall ipv6 output filter ...` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +**Important note about default-actions:** +If default action for any base chain is not defined, then the default +action is set to **accept** for that chain. For custom chains, if default +action is not defined, then the default-action is set to **drop** + +</div> + +Custom firewall chains can be created, with commands +`set firewall ipv6 name <name> ...`. In order to use +such custom chain, a rule with **action jump**, and the appropiate **target** +should be defined in a base chain. + +## Firewall - IPv6 Rules + +For firewall filtering, firewall rules needs to be created. Each rule is +numbered, has an action to apply if the rule is matched, and the ability +to specify multiple criteria matchers. Data packets go through the rules +from 1 - 999999, so order is crucial. At the first match the action of the +rule will be executed. + +### Actions + +If a rule is defined, then an action must be defined for it. This tells the +firewall what to do if all criteria matchers defined for such rule do match. + +The action can be : + +> - `accept`: accept the packet. +> - `continue`: continue parsing next rule. +> - `drop`: drop the packet. +> - `reject`: reject the packet. +> - `jump`: jump to another custom chain. +> - `return`: Return from the current chain and continue at the next rule +> of the last chain. +> - `queue`: Enqueue packet to userspace. +> - `synproxy`: synproxy the packet. + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> action +\[accept | continue | drop | jump | queue | reject | return | synproxy\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> action +\[accept | continue | drop | jump | queue | reject | return | synproxy\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> action +\[accept | continue | drop | jump | queue | reject | return\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> action +\[accept | continue | drop | jump | queue | reject | return\] + +This required setting defines the action of the current rule. If action is +set to jump, then jump-target is also needed. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +jump-target \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +jump-target \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +jump-target \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +jump-target \<text\> + +To be used only when action is set to `jump`. Use this command to specify +jump target. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +queue \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +queue \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +queue \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +queue \<0-65535\> + +To be used only when action is set to `queue`. Use this command to specify +queue target to use. Queue range is also supported. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +queue-options bypass + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +queue-options bypass + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +queue-options bypass + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +queue-options bypass + +To be used only when action is set to `queue`. Use this command to let +packet go through firewall when no userspace software is connected to the +queue. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +queue-options fanout + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +queue-options fanout + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +queue-options fanout + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +queue-options fanout + +To be used only when action is set to `queue`. Use this command to +distribute packets between several queues. + +</div> + +Also, **default-action** is an action that takes place whenever a packet does +not match any rule in it's chain. For base chains, possible options for +**default-action** are **accept** or **drop**. + +<div class="cfgcmd"> + +set firewall ipv6 forward filter default-action +\[accept | drop\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter default-action +\[accept | drop\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter default-action +\[accept | drop\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> default-action +\[accept | drop | jump | queue | reject | return\] + +This set the default action of the rule-set if no rule matched a packet +criteria. If default-action is set to `jump`, then +`default-jump-target` is also needed. Note that for base chains, default +action can only be set to `accept` or `drop`, while on custom chain, +more actions are available. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> default-jump-target \<text\> + +To be used only when `defult-action` is set to `jump`. Use this +command to specify jump target for default rule. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +**Important note about default-actions:** +If default action for any base chain is not defined, then the default +action is set to **accept** for that chain. For custom chains, if default +action is not defined, then the default-action is set to **drop**. + +</div> + +### Firewall Logs + +Logging can be enable for every single firewall rule. If enabled, other +log options can be defined. + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> log + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> log + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> log + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> log + +Enable logging for the matched packet. If this configuration command is not +present, then log is not enabled. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter default-log + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter default-log + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter default-log + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> default-log + +Use this command to enable the logging of the default action on +the specified chain. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +log-options level \[emerg | alert | crit | err | warn | notice +| info | debug\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +log-options level \[emerg | alert | crit | err | warn | notice +| info | debug\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +log-options level \[emerg | alert | crit | err | warn | notice +| info | debug\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +log-options level \[emerg | alert | crit | err | warn | notice +| info | debug\] + +Define log-level. Only applicable if rule log is enable. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +log-options group \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +log-options group \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +log-options group \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +log-options group \<0-65535\> + +Define log group to send message to. Only applicable if rule log is enable. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +log-options snapshot-length \<0-9000\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +log-options snapshot-length \<0-9000\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +log-options snapshot-length \<0-9000\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +log-options snapshot-length \<0-9000\> + +Define length of packet payload to include in netlink message. Only +applicable if rule log is enable and log group is defined. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +log-options queue-threshold \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +log-options queue-threshold \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +log-options queue-threshold \<0-65535\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +log-options queue-threshold \<0-65535\> + +Define number of packets to queue inside the kernel before sending them to +userspace. Only applicable if rule log is enable and log group is defined. + +</div> + +### Firewall Description + +For reference, a description can be defined for every single rule, and for +every defined custom chain. + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> description \<text\> + +Provide a rule-set description to a custom firewall chain. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +description \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +description \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +description \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> description \<text\> + +Provide a description for each rule. + +</div> + +### Rule Status + +When defining a rule, it is enable by default. In some cases, it is useful to +just disable the rule, rather than removing it. + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> disable + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> disable + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> disable + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> disable + +Command for disabling a rule but keep it in the configuration. + +</div> + +### Matching criteria + +There are a lot of matching criteria against which the packet can be tested. + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +connection-status nat \[destination | source\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +connection-status nat \[destination | source\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +connection-status nat \[destination | source\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +connection-status nat \[destination | source\] + +Match criteria based on nat connection status. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +connection-mark \<1-2147483647\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +connection-mark \<1-2147483647\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +connection-mark \<1-2147483647\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +connection-mark \<1-2147483647\> + +Match criteria based on connection mark. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +source address \[address | addressrange | CIDR\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +source address \[address | addressrange | CIDR\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +source address \[address | addressrange | CIDR\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +source address \[address | addressrange | CIDR\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +destination address \[address | addressrange | CIDR\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +destination address \[address | addressrange | CIDR\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +destination address \[address | addressrange | CIDR\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +destination address \[address | addressrange | CIDR\] + +Match criteria based on source and/or destination address. This is similar +to the network groups part, but here you are able to negate the matching +addresses. + +``` none +set firewall ipv6 name FOO rule 100 source address 2001:db8::202 +``` + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +source address-mask \[address\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +source address-mask \[address\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +source address-mask \[address\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +source address-mask \[address\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +destination address-mask \[address\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +destination address-mask \[address\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +destination address-mask \[address\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +destination address-mask \[address\] + +An arbitrary netmask can be applied to mask addresses to only match against +a specific portion. This is particularly useful with IPv6 as rules will +remain valid if the IPv6 prefix changes and the host +portion of systems IPv6 address is static (for example, with SLAAC or +[tokenised IPv6 addresses](https://datatracker.ietf.org/doc/id/draft-chown-6man-tokenised-ipv6-identifiers-02.txt)) + +This functions for both individual addresses and address groups. + +``` none +# Match any IPv6 address with the suffix ::0000:0000:0000:beef +set firewall ipv6 forward filter rule 100 destination address ::beef +set firewall ipv6 forward filter rule 100 destination address-mask ::ffff:ffff:ffff:ffff +# Address groups +set firewall group ipv6-address-group WEBSERVERS address ::1000 +set firewall group ipv6-address-group WEBSERVERS address ::2000 +set firewall ipv6 forward filter rule 200 source group address-group WEBSERVERS +set firewall ipv6 forward filter rule 200 source address-mask ::ffff:ffff:ffff:ffff +``` + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +source fqdn \<fqdn\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +source fqdn \<fqdn\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +source fqdn \<fqdn\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +source fqdn \<fqdn\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +destination fqdn \<fqdn\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +destination fqdn \<fqdn\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +destination fqdn \<fqdn\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +destination fqdn \<fqdn\> + +Specify a Fully Qualified Domain Name as source/destination matcher. Ensure +router is able to resolve such dns query. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +source geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +source geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +source geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +source geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +destination geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +destination geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +destination geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +destination geoip country-code \<country\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +source geoip inverse-match + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +source geoip inverse-match + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +source geoip inverse-match + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +source geoip inverse-match + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +destination geoip inverse-match + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +destination geoip inverse-match + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +destination geoip inverse-match + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +destination geoip inverse-match + +Match IP addresses based on its geolocation. More info: [geoip matching](https://wiki.nftables.org/wiki-nftables/index.php/GeoIP_matching). +Use inverse-match to match anything except the given country-codes. + +</div> + +Data is provided by DB-IP.com under CC-BY-4.0 license. Attribution required, +permits redistribution so we can include a database in images(~3MB +compressed). Includes cron script (manually callable by op-mode update +geoip) to keep database and rules updated. + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +source mac-address \<mac-address\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +source mac-address \<mac-address\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +source mac-address \<mac-address\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +source mac-address \<mac-address\> + +Only in the source criteria, you can specify a mac-address. + +``` none +set firewall ipv6 input filter rule 100 source mac-address 00:53:00:11:22:33 +set firewall ipv6 input filter rule 101 source mac-address !00:53:00:aa:12:34 +``` + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +source port \[1-65535 | portname | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +source port \[1-65535 | portname | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +source port \[1-65535 | portname | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +source port \[1-65535 | portname | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +destination port \[1-65535 | portname | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +destination port \[1-65535 | portname | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +destination port \[1-65535 | portname | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +destination port \[1-65535 | portname | start-end\] + +A port can be set with a port number or a name which is here +defined: `/etc/services`. + +``` none +set firewall ipv6 forward filter rule 10 source port '22' +set firewall ipv6 forward filter rule 11 source port '!http' +set firewall ipv6 forward filter rule 12 source port 'https' +``` + +Multiple source ports can be specified as a comma-separated list. +The whole list can also be "negated" using `!`. For example: + +``` none +set firewall ipv6 forward filter rule 10 source port '!22,https,3333-3338' +``` + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +source group address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +source group address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +source group address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +source group address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +destination group address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +destination group address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +destination group address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +destination group address-group \<name | !name\> + +Use a specific address-group. Prepend character `!` for inverted matching +criteria. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +source group dynamic-address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +source group dynamic-address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +source group dynamic-address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +source group dynamic-address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +destination group dynamic-address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +destination group dynamic-address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +destination group dynamic-address-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +destination group dynamic-address-group \<name | !name\> + +Use a specific dynamic-address-group. Prepend character `!` for inverted +matching criteria. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +source group network-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +source group network-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +source group network-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +source group network-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +destination group network-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +destination group network-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +destination group network-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +destination group network-group \<name | !name\> + +Use a specific network-group. Prepend character `!` for inverted matching +criteria. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +source group port-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +source group port-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +source group port-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +source group port-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +destination group port-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +destination group port-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +destination group port-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +destination group port-group \<name | !name\> + +Use a specific port-group. Prepend character `!` for inverted matching +criteria. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +source group domain-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +source group domain-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +source group domain-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +source group domain-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +destination group domain-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +destination group domain-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +destination group domain-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +destination group domain-group \<name | !name\> + +Use a specific domain-group. Prepend character `!` for inverted matching +criteria. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +source group mac-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +source group mac-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +source group mac-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +source group mac-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +destination group mac-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +destination group mac-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +destination group mac-group \<name | !name\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +destination group mac-group \<name | !name\> + +Use a specific mac-group. Prepend character `!` for inverted matching +criteria. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +dscp \[0-63 | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +dscp \[0-63 | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +dscp \[0-63 | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +dscp \[0-63 | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +dscp-exclude \[0-63 | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +dscp-exclude \[0-63 | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +dscp-exclude \[0-63 | start-end\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +dscp-exclude \[0-63 | start-end\] + +Match based on dscp value. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +fragment \[match-frag | match-non-frag\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +fragment \[match-frag | match-non-frag\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +fragment \[match-frag | match-non-frag\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +fragment \[match-frag | match-non-frag\] + +Match based on fragment criteria. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +icmpv6 \[code | type\] \<0-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +icmpv6 \[code | type\] \<0-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +icmpv6 \[code | type\] \<0-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +icmpv6 \[code | type\] \<0-255\> + +Match based on icmp|icmpv6 code and type. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +icmpv6 type-name \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +icmpv6 type-name \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +icmpv6 type-name \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +icmpv6 type-name \<text\> + +Match based on icmpv6 type-name criteria. Use tab for information +about what **type-name** criteria are supported. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +inbound-interface name \<iface\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +inbound-interface name \<iface\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +inbound-interface name \<iface\> + +Match based on inbound interface. Wilcard `*` can be used. +For example: `eth2*`. Prepending character `!` for inverted matching +criteria is also supportd. For example `!eth2` + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If an interface is attached to a non-default vrf, when using +**inbound-interface**, vrf name must be used. For example `set firewall ipv6 forward filter rule 10 inbound-interface name MGMT` + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +inbound-interface group \<iface_group\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +inbound-interface group \<iface_group\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +inbound-interface group \<iface_group\> + +Match based on inbound interface group. Prepending character `!` for +inverted matching criteria is also supportd. For example `!IFACE_GROUP` + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +outbound-interface name \<iface\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +outbound-interface name \<iface\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +outbound-interface name \<iface\> + +Match based on outbound interface. Wilcard `*` can be used. +For example: `eth2*`. Prepending character `!` for inverted matching +criteria is also supportd. For example `!eth2` + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If an interface is attached to a non-default vrf, when using +**outbound-interface**, real interface name must be used. For example +`set firewall ipv6 forward filter rule 10 outbound-interface name eth0` + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +outbound-interface group \<iface_group\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +outbound-interface group \<iface_group\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +outbound-interface group \<iface_group\> + +Match based on outbound interface group. Prepending character `!` for +inverted matching criteria is also supportd. For example `!IFACE_GROUP` + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +ipsec \[match-ipsec | match-none\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +ipsec \[match-ipsec | match-none\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +ipsec \[match-ipsec | match-none\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +ipsec \[match-ipsec | match-none\] + +Match based on ipsec criteria. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +limit burst \<0-4294967295\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +limit burst \<0-4294967295\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +limit burst \<0-4294967295\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +limit burst \<0-4294967295\> + +Match based on the maximum number of packets to allow in excess of rate. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +limit rate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +limit rate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +limit rate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +limit rate \<text\> + +Match based on the maximum average rate, specified as **integer/unit**. +For example **5/minutes** + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +packet-length \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +packet-length \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +packet-length \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +packet-length \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +packet-length-exclude \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +packet-length-exclude \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +packet-length-exclude \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +packet-length-exclude \<text\> + +Match based on packet length criteria. Multiple values from 1 to 65535 +and ranges are supported. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +packet-type \[broadcast | host | multicast | other\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +packet-type \[broadcast | host | multicast | other\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +packet-type \[broadcast | host | multicast | other\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +packet-type \[broadcast | host | multicast | other\] + +Match based on packet type criteria. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +protocol \[\<text\> | \<0-255\> | all | tcp_udp\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +protocol \[\<text\> | \<0-255\> | all | tcp_udp\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +protocol \[\<text\> | \<0-255\> | all | tcp_udp\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +protocol \[\<text\> | \<0-255\> | all | tcp_udp\] + +Match a protocol criteria. A protocol number or a name which is here +defined: `/etc/protocols`. +Special names are `all` for all protocols and `tcp_udp` for tcp and udp +based packets. The `!` negate the selected protocol. + +``` none +set firewall ipv6 input filter rule 10 protocol tcp +``` + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +recent time \[second | minute | hour\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +recent time \[second | minute | hour\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +recent time \[second | minute | hour\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +recent time \[second | minute | hour\] + +Match bases on recently seen sources. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +tcp flags \[not\] \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +tcp flags \[not\] \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +tcp flags \[not\] \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +tcp flags \[not\] \<text\> + +Allowed values fpr TCP flags: `ack`, `cwr`, `ecn`, `fin`, `psh`, +`rst`, `syn` and `urg`. Multiple values are supported, and for +inverted selection use `not`, as shown in the example. + +``` none +set firewall ipv6 input filter rule 10 tcp flags 'ack' +set firewall ipv6 input filter rule 12 tcp flags 'syn' +set firewall ipv6 input filter rule 13 tcp flags not 'fin' +``` + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +state \[established | invalid | new | related\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +state \[established | invalid | new | related\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +state \[established | invalid | new | related\] + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +state \[established | invalid | new | related\] + +Match against the state of a packet. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +time startdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +time startdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +time startdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +time startdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +time starttime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +time starttime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +time starttime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +time starttime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +time stopdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +time stopdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +time stopdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +time stopdate \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +time stoptime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +time stoptime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +time stoptime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +time stoptime \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +time weekdays \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +time weekdays \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +time weekdays \<text\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +time weekdays \<text\> + +Time to match the defined rule. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +hop-limit \<eq | gt | lt\> \<0-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +hop-limit \<eq | gt | lt\> \<0-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +hop-limit \<eq | gt | lt\> \<0-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +hop-limit \<eq | gt | lt\> \<0-255\> + +Match hop-limit parameter, where 'eq' stands for 'equal'; 'gt' stands for +'greater than', and 'lt' stands for 'less than'. + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 forward filter rule \<1-999999\> +recent time \<second | minute | hour\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 input filter rule \<1-999999\> +recent time \<second | minute | hour\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 output filter rule \<1-999999\> +recent time \<second | minute | hour\> + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 name \<name\> rule \<1-999999\> +recent time \<second | minute | hour\> + +Match when 'count' amount of connections are seen within 'time'. These +matching criteria can be used to block brute-force attempts. + +</div> + +## Synproxy + +Synproxy connections + +<div class="cfgcmd"> + +set firewall ipv6 \[input | forward\] filter rule \<1-999999\> +action synproxy + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 \[input | forward\] filter rule \<1-999999\> +protocol tcp + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 \[input | forward\] filter rule \<1-999999\> +synproxy tcp mss \<501-65535\> + +Set TCP-MSS (maximum segment size) for the connection + +</div> + +<div class="cfgcmd"> + +set firewall ipv6 \[input | forward\] filter rule \<1-999999\> +synproxy tcp window-scale \<1-14\> + +Set the window scale factor for TCP window scaling + +</div> + +### Example synproxy + +Requirements to enable synproxy: + +> - Traffic must be symmetric +> - Synproxy relies on syncookies and TCP timestamps, ensure these are enabled +> - Disable conntrack loose track option + +``` none +set system sysctl parameter net.ipv4.tcp_timestamps value '1' + +set system conntrack tcp loose disable +set system conntrack ignore ipv6 rule 10 destination port '8080' +set system conntrack ignore ipv6 rule 10 protocol 'tcp' +set system conntrack ignore ipv6 rule 10 tcp flags syn + +set firewall global-options syn-cookies 'enable' +set firewall ipv6 input filter rule 10 action 'synproxy' +set firewall ipv6 input filter rule 10 destination port '8080' +set firewall ipv6 input filter rule 10 inbound-interface name 'eth1' +set firewall ipv6 input filter rule 10 protocol 'tcp' +set firewall ipv6 input filter rule 10 synproxy tcp mss '1460' +set firewall ipv6 input filter rule 10 synproxy tcp window-scale '7' +set firewall ipv6 input filter rule 1000 action 'drop' +set firewall ipv6 input filter rule 1000 state invalid +``` + +## Operation-mode Firewall + +### Rule-set overview + +<div class="opcmd"> + +show firewall + +This will show you a basic firewall overview + +``` none +vyos@vyos:~$ show firewall +Rulesets Information + +--------------------------------- +IPv4 Firewall "forward filter" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- ----------------------------------------- +5 jump all 0 0 iifname "eth1" jump NAME_VyOS_MANAGEMENT +10 jump all 0 0 oifname "eth1" jump NAME_WAN_IN +15 jump all 0 0 iifname "eth3" jump NAME_WAN_IN +default accept all + +--------------------------------- +IPv4 Firewall "name VyOS_MANAGEMENT" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- -------------------------------- +5 accept all 0 0 ct state established accept +10 drop all 0 0 ct state invalid +20 accept all 0 0 ip saddr @A_GOOD_GUYS accept +30 accept all 0 0 ip saddr @N_ENTIRE_RANGE accept +40 accept all 0 0 ip saddr @A_VyOS_SERVERS accept +50 accept icmp 0 0 meta l4proto icmp accept +default drop all 0 0 + +--------------------------------- +IPv6 Firewall "forward filter" + +Rule Action Protocol +------- -------- ---------- +5 jump all +10 jump all +15 jump all +default accept all + +--------------------------------- +IPv6 Firewall "input filter" + +Rule Action Protocol +------- -------- ---------- +5 jump all +default accept all + +--------------------------------- +IPv6 Firewall "ipv6_name IPV6-VyOS_MANAGEMENT" + +Rule Action Protocol +------- -------- ---------- +5 accept all +10 drop all +20 accept all +30 accept all +40 accept all +50 accept ipv6-icmp +default drop all +``` + +</div> + +<div class="opcmd"> + +show firewall summary + +This will show you a summary of rule-sets and groups + +``` none +vyos@vyos:~$ show firewall summary +Ruleset Summary + +IPv6 Ruleset: + +Ruleset Hook Ruleset Priority Description +-------------- -------------------- ------------------------- +forward filter +input filter +ipv6_name IPV6-VyOS_MANAGEMENT +ipv6_name IPV6-WAN_IN PUBLIC_INTERNET + +IPv4 Ruleset: + +Ruleset Hook Ruleset Priority Description +-------------- ------------------ ------------------------- +forward filter +input filter +name VyOS_MANAGEMENT +name WAN_IN PUBLIC_INTERNET + +Firewall Groups + +Name Type References Members +----------------------- ------------------ ----------------------- ---------------- +PBX address_group WAN_IN-100 198.51.100.77 +SERVERS address_group WAN_IN-110 192.0.2.10 + WAN_IN-111 192.0.2.11 + WAN_IN-112 192.0.2.12 + WAN_IN-120 + WAN_IN-121 + WAN_IN-122 +SUPPORT address_group VyOS_MANAGEMENT-20 192.168.1.2 + WAN_IN-20 +PHONE_VPN_SERVERS address_group WAN_IN-160 10.6.32.2 +PINGABLE_ADRESSES address_group WAN_IN-170 192.168.5.2 + WAN_IN-171 +PBX ipv6_address_group IPV6-WAN_IN-100 2001:db8::1 +SERVERS ipv6_address_group IPV6-WAN_IN-110 2001:db8::2 + IPV6-WAN_IN-111 2001:db8::3 + IPV6-WAN_IN-112 2001:db8::4 + IPV6-WAN_IN-120 + IPV6-WAN_IN-121 + IPV6-WAN_IN-122 +SUPPORT ipv6_address_group IPV6-VyOS_MANAGEMENT-20 2001:db8::5 + IPV6-WAN_IN-20 +``` + +</div> + +<div class="opcmd"> + +show firewall ipv6 \[forward | input | output\] filter + +</div> + +<div class="opcmd"> + +show firewall ipv6 ipv6-name \<name\> + +This command will give an overview of a single rule-set. + +``` none +vyos@vyos:~$ show firewall ipv6 input filter +Ruleset Information + +--------------------------------- +ipv6 Firewall "input filter" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- ------------------------------------------------------------------------------ +10 jump all 13 1456 iifname "eth1" jump NAME6_INP-ETH1 +20 accept ipv6-icmp 10 1112 meta l4proto ipv6-icmp iifname "eth0" prefix "[ipv6-INP-filter-20-A]" accept +default accept all 14 1584 + +vyos@vyos:~$ +``` + +</div> + +<div class="opcmd"> + +show firewall ipv6 \[forward | input | output\] +filter rule \<1-999999\> + +</div> + +<div class="opcmd"> + +show firewall ipv6 name \<name\> rule \<1-999999\> + +</div> + +<div class="opcmd"> + +show firewall ipv6 ipv6-name \<name\> rule \<1-999999\> + +This command will give an overview of a rule in a single rule-set + +</div> + +<div class="opcmd"> + +show firewall group \<name\> + +Overview of defined groups. You see the type, the members, and where the +group is used. + +``` none +vyos@vyos:~$ show firewall group LAN +Firewall Groups + +Name Type References Members +------------ ------------------ ----------------------- ---------------- +LAN ipv6_network_group IPV6-VyOS_MANAGEMENT-30 2001:db8::0/64 + IPV6-WAN_IN-30 +LAN network_group VyOS_MANAGEMENT-30 192.168.200.0/24 + WAN_IN-30 +``` + +</div> + +<div class="opcmd"> + +show firewall statistics + +This will show you a statistic of all rule-sets since the last boot. + +</div> + +### Show Firewall log + +<div class="opcmd"> + +show log firewall + +</div> + +<div class="opcmd"> + +show log firewall ipv6 + +</div> + +<div class="opcmd"> + +show log firewall ipv6 \[forward | input | output | name\] + +</div> + +<div class="opcmd"> + +show log firewall ipv6 \[forward | input | output\] filter + +</div> + +<div class="opcmd"> + +show log firewall ipv6 name \<name\> + +</div> + +<div class="opcmd"> + +show log firewall ipv6 \[forward | input | output\] filter rule \<rule\> + +</div> + +<div class="opcmd"> + +show log firewall ipv6 name \<name\> rule \<rule\> + +Show the logs of all firewall; show all ipv6 firewall logs; show all logs +for particular hook; show all logs for particular hook and priority; +show all logs for particular custom chain; show logs for specific Rule-Set. + +</div> + +### Example Partial Config + +``` none +firewall { + ipv6 { + input { + filter { + rule 10 { + action jump + inbound-interface { + name eth1 + } + jump-target INP-ETH1 + } + rule 20 { + action accept + inbound-interface { + name eth0 + } + log + protocol ipv6-icmp + } + } + } + name INP-ETH1 { + default-action drop + default-log + rule 10 { + action accept + protocol tcp_udp + } + } + } +} +``` + +### Update geoip database + +<div class="opcmd"> + +update geoip + +Command used to update GeoIP database and firewall sets. + +</div> diff --git a/docs/configuration/firewall/md-zone.md b/docs/configuration/firewall/md-zone.md new file mode 100644 index 00000000..6eb27b6c --- /dev/null +++ b/docs/configuration/firewall/md-zone.md @@ -0,0 +1,209 @@ +lastproofread +2023-11-01 + +# Zone Based Firewall + +## Overview + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Starting from VyOS 1.4-rolling-202308040557, a new firewall +structure can be found on all vyos instalations. Zone based firewall was +removed in that version, but re introduced in VyOS 1.4 and 1.5. All +versions built after 2023-10-22 has this feature. +Documentation for most of the new firewall CLI can be +found in the [firewall](https://docs.vyos.io/en/latest/configuration/firewall/general.html) +chapter. The legacy firewall is still available for versions before +1.4-rolling-202308040557 and can be found in the +`legacy firewall configuration </configuration/firewall/general-legacy>` +chapter. + +</div> + +In this section there's useful information of all firewall configuration that +is needed for zone-based firewall. +Configuration commands covered in this section: + +<div class="cfgcmd"> + +set firewall zone ... + +</div> + +From main structure defined in +`Firewall Overview</configuration/firewall/index>` +in this section you can find detailed information only for the next part +of the general structure: + +``` none +- set firewall + * zone + - custom_zone_name + + ... +``` + +In zone-based policy, interfaces are assigned to zones, and inspection policy +is applied to traffic moving between the zones and acted on according to +firewall rules. A zone is a group of interfaces that have similar functions or +features. It establishes the security borders of a network. A zone defines a +boundary where traffic is subjected to policy restrictions as it crosses to +another region of a network. + +Key Points: + +- A zone must be configured before an interface is assigned to it and an + interface can be assigned to only a single zone. +- All traffic to and from an interface within a zone is permitted. +- All traffic between zones is affected by existing policies +- Traffic cannot flow between zone member interface and any interface that is + not a zone member. +- You need 2 separate firewalls to define traffic: one for each direction. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +In `T2199` the syntax of the zone configuration was changed. +The zone configuration moved from `zone-policy zone <name>` to `firewall zone <name>`. + +</div> + +## Configuration + +As an alternative to applying policy to an interface directly, a zone-based +firewall can be created to simplify configuration when multiple interfaces +belong to the same security zone. Instead of applying rule-sets to interfaces, +they are applied to source zone-destination zone pairs. + +A basic introduction to zone-based firewalls can be found [here](https://support.vyos.io/en/kb/articles/a-primer-to-zone-based-firewall), +and an example at `examples-zone-policy`. + +### Define a Zone + +To define a zone setup either one with interfaces or a local zone. + +<div class="cfgcmd"> + +set firewall zone \<name\> interface \<interface\> + +Set interfaces to a zone. A zone can have multiple interfaces. +But an interface can only be a member in one zone. + +</div> + +<div class="cfgcmd"> + +set firewall zone \<name\> local-zone + +Define the zone as a local zone. A local zone has no interfaces and +will be applied to the router itself. + +</div> + +<div class="cfgcmd"> + +set firewall zone \<name\> default-action \[drop | reject\] + +Change the default-action with this setting. + +</div> + +<div class="cfgcmd"> + +set firewall zone \<name\> description + +Set a meaningful description. + +</div> + +### Applying a Rule-Set to a Zone + +Before you are able to apply a rule-set to a zone you have to create the zones +first. + +It helps to think of the syntax as: (see below). The 'rule-set' should be +written from the perspective of: *Source Zone*-to-\>\*Destination Zone\* + +<div class="cfgcmd"> + +set firewall zone \<Destination Zone\> from \<Source Zone\> +firewall name \<rule-set\> + +</div> + +<div class="cfgcmd"> + +set firewall zone \<name\> from \<name\> firewall name +\<rule-set\> + +</div> + +<div class="cfgcmd"> + +set firewall zone \<name\> from \<name\> firewall ipv6-name +\<rule-set\> + +You apply a rule-set always to a zone from an other zone, it is recommended +to create one rule-set for each zone pair. + +``` none +set firewall zone DMZ from LAN firewall name LANv4-to-DMZv4 +set firewall zone LAN from DMZ firewall name DMZv4-to-LANv4 +``` + +</div> + +## Operation-mode + +<div class="opcmd"> + +show firewall zone-policy + +This will show you a basic summary of zones configuration. + +``` none +vyos@vyos:~$ show firewall zone-policy +Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 +------ ------------ ----------- --------------- --------------- +LAN eth1 WAN WAN_to_LAN + eth2 +LOCAL LOCAL LAN LAN_to_LOCAL + WAN WAN_to_LOCAL WAN_to_LOCAL_v6 +WAN eth3 LAN LAN_to_WAN + eth0 LOCAL LOCAL_to_WAN +vyos@vyos:~$ +``` + +</div> + +<div class="opcmd"> + +show firewall zone-policy zone \<zone\> + +This will show you a basic summary of a particular zone. + +``` none +vyos@vyos:~$ show firewall zone-policy zone WAN +Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 +------ ------------ ----------- --------------- --------------- +WAN eth3 LAN LAN_to_WAN + eth0 LOCAL LOCAL_to_WAN +vyos@vyos:~$ show firewall zone-policy zone LOCAL +Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 +------ ------------ ----------- --------------- --------------- +LOCAL LOCAL LAN LAN_to_LOCAL + WAN WAN_to_LOCAL WAN_to_LOCAL_v6 +vyos@vyos:~$ +``` + +</div> diff --git a/docs/configuration/highavailability/md-index.md b/docs/configuration/highavailability/md-index.md new file mode 100644 index 00000000..6d66603e --- /dev/null +++ b/docs/configuration/highavailability/md-index.md @@ -0,0 +1,525 @@ +lastproofread +2021-06-30 + +# High availability + +VRRP (Virtual Router Redundancy Protocol) provides active/backup redundancy for +routers. Every VRRP router has a physical IP/IPv6 address, and a virtual +address. On startup, routers elect the master, and the router with the highest +priority becomes the master and assigns the virtual address to its interface. +All routers with lower priorities become backup routers. The master then starts +sending keepalive packets to notify other routers that it's available. If the +master fails and stops sending keepalive packets, the router with the next +highest priority becomes the new master and takes over the virtual address. + +VRRP keepalive packets use multicast, and VRRP setups are limited to a single +datalink layer segment. You can setup multiple VRRP groups +(also called virtual routers). Virtual routers are identified by a +VRID (Virtual Router IDentifier). If you setup multiple groups on the same +interface, their VRIDs must be unique if they use the same address family, +but it's possible (even if not recommended for readability reasons) to use +duplicate VRIDs on different interfaces. + +## Basic setup + +VRRP groups are created with the +`set high-availability vrrp group $GROUP_NAME` commands. The required +parameters are interface, vrid, and address. + +minimal config + +``` none +set high-availability vrrp group Foo vrid 10 +set high-availability vrrp group Foo interface eth0 +set high-availability vrrp group Foo address 192.0.2.1/24 +``` + +You can verify your VRRP group status with the operational mode +`run show vrrp` command: + +``` none +vyos@vyos# run show vrrp +Name Interface VRID State Last Transition +---------- ----------- ------ ------- ----------------- +Foo eth1 10 MASTER 2s +``` + +## IPv6 support + +The `address` parameter can be either an IPv4 or IPv6 address, but you can +not mix IPv4 and IPv6 in the same group, and will need to create groups with +different VRIDs specially for IPv4 and IPv6. +If you want to use IPv4 + IPv6 address you can use option `excluded-address` + +## Address + +The `address` can be configured either on the VRRP interface or on not VRRP +interface. + +``` none +set high-availability vrrp group Foo address 192.0.2.1/24 +set high-availability vrrp group Foo address 203.0.113.22/24 interface eth2 +set high-availability vrrp group Foo address 198.51.100.33/24 interface eth3 +``` + +## Disabling a VRRP group + +You can disable a VRRP group with `disable` option: + +``` none +set high-availability vrrp group Foo disable +``` + +A disabled group will be removed from the VRRP process and your router will not +participate in VRRP for that VRID. It will disappear from operational mode +commands output, rather than enter the backup state. + +## Exclude address + +Exclude IP addresses from `VRRP packets`. This option `excluded-address` is +used when you want to set IPv4 + IPv6 addresses on the same virtual interface +or when used more than 20 IP addresses. + +``` none +set high-availability vrrp group Foo excluded-address '203.0.113.254/24' +set high-availability vrrp group Foo excluded-address '2001:db8:aa::1/64' +set high-availability vrrp group Foo excluded-address '2001:db8:22::1/64' +``` + +## Setting VRRP group priority + +VRRP priority can be set with `priority` option: + +``` none +set high-availability vrrp group Foo priority 200 +``` + +The priority must be an integer number from 1 to 255. Higher priority value +increases router's precedence in the master elections. + +## Sync groups + +A sync group allows VRRP groups to transition together. + +``` none +edit high-availability vrrp +set sync-group MAIN member VLAN9 +set sync-group MAIN member VLAN20 +``` + +In the following example, when VLAN9 transitions, VLAN20 will also transition: + +``` none +vrrp { + group VLAN9 { + interface eth0.9 + address 10.9.1.1/24 + priority 200 + vrid 9 + } + group VLAN20 { + interface eth0.20 + priority 200 + address 10.20.20.1/24 + vrid 20 + } + sync-group MAIN { + member VLAN20 + member VLAN9 + } +} +``` + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +All items in a sync group should be similarly configured. +If one VRRP group is set to a different preemption delay or priority, +it would result in an endless transition loop. + +</div> + +## Preemption + +VRRP can use two modes: preemptive and non-preemptive. In the preemptive mode, +if a router with a higher priority fails and then comes back, routers with lower +priority will give up their master status. In non-preemptive mode, the newly +elected master will keep the master status and the virtual address indefinitely. + +By default VRRP uses preemption. You can disable it with the "no-preempt" +option: + +``` none +set high-availability vrrp group Foo no-preempt +``` + +You can also configure the time interval for preemption with the "preempt-delay" +option. For example, to set the higher priority router to take over in 180 +seconds, use: + +``` none +set high-availability vrrp group Foo preempt-delay 180 +``` + +## Track + +Track option to track non VRRP interface states. VRRP changes status to +`FAULT` if one of the track interfaces in state `down`. + +``` none +set high-availability vrrp group Foo track interface eth0 +set high-availability vrrp group Foo track interface eth1 +``` + +Ignore VRRP main interface faults + +``` none +set high-availability vrrp group Foo track exclude-vrrp-interface +``` + +## Unicast VRRP + +By default VRRP uses multicast packets. If your network does not support +multicast for whatever reason, you can make VRRP use unicast communication +instead. + +``` none +set high-availability vrrp group Foo peer-address 192.0.2.10 +set high-availability vrrp group Foo hello-source-address 192.0.2.15 +``` + +## rfc3768-compatibility + +RFC 3768 defines a virtual MAC address to each VRRP virtual router. +This virtual router MAC address will be used as the source in all periodic VRRP +messages sent by the active node. When the rfc3768-compatibility option is set, +a new VRRP interface is created, to which the MAC address and the virtual IP +address is automatically assigned. + +``` none +set high-availability vrrp group Foo rfc3768-compatibility +``` + +Verification + +``` none +$show interfaces ethernet eth0v10 +eth0v10@eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue +state UP group default qlen 1000 +link/ether 00:00:5e:00:01:0a brd ff:ff:ff:ff:ff:ff +inet 172.25.0.247/16 scope global eth0v10 +valid_lft forever preferred_lft forever +``` + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +RFC 3768 creates a virtual interface. If you want to apply +the destination NAT rule to the traffic sent to the virtual MAC, set +the created virtual interface as <span class="title-ref">inbound-interface</span>. + +</div> + +## Global options + +On most scenarios, there's no need to change specific parameters, and using +default configuration is enough. But there are cases were extra configuration +is needed. + +<div class="cfgcmd"> + +set high-availability vrrp global-parameters startup_delay \<1-600\> + +This option specifies a delay in seconds before vrrp instances start up +after keepalived starts. + +</div> + +## Gratuitous ARP + +These configuration is not mandatory and in most cases there's no +need to configure it. But if necessary, Gratuitous ARP can be configured in +`global-parameters` and/or in `group` section. + +<div class="cfgcmd"> + +set high-availability vrrp global-parameters garp interval +\<0.000-1000\> + +</div> + +<div class="cfgcmd"> + +set high-availability vrrp group \<name\> garp interval \<0.000-1000\> + +Set delay between gratuitous ARP messages sent on an interface. + +0 if not defined. + +</div> + +<div class="cfgcmd"> + +set high-availability vrrp global-parameters garp master-delay \<1-255\> + +</div> + +<div class="cfgcmd"> + +set high-availability vrrp group \<name\> garp master-delay \<1-255\> + +Set delay for second set of gratuitous ARPs after transition to MASTER. + +5 if not defined. + +</div> + +<div class="cfgcmd"> + +set high-availability vrrp global-parameters garp master-refresh +\<1-600\> + +</div> + +<div class="cfgcmd"> + +set high-availability vrrp group \<name\> garp master-refresh +\<1-600\> + +Set minimum time interval for refreshing gratuitous ARPs while MASTER. + +0 if not defined, which means no refreshing. + +</div> + +<div class="cfgcmd"> + +set high-availability vrrp global-parameters garp +master-refresh-repeat \<1-600\> + +</div> + +<div class="cfgcmd"> + +set high-availability vrrp group \<name\> garp +master-refresh-repeat \<1-600\> + +Set number of gratuitous ARP messages to send at a time while MASTER. + +1 if not defined. + +</div> + +<div class="cfgcmd"> + +set high-availability vrrp global-parameters garp master-repeat +\<1-600\> + +</div> + +<div class="cfgcmd"> + +set high-availability vrrp group \<name\> garp master-repeat +\<1-600\> + +Set number of gratuitous ARP messages to send at a time after transition to +MASTER. + +5 if not defined. + +</div> + +## Version + +<div class="cfgcmd"> + +set high-availability vrrp global-parameters version 2|3 + +Set the default VRRP version to use. This defaults to 2, but IPv6 instances +will always use version 3. + +</div> + +## Scripting + +VRRP functionality can be extended with scripts. VyOS supports two kinds of +scripts: health check scripts and transition scripts. Health check scripts +execute custom checks in addition to the master router reachability. Transition +scripts are executed when VRRP state changes from master to backup or fault and +vice versa and can be used to enable or disable certain services, for example. + +### Health check scripts + +This setup will make the VRRP process execute the +`/config/scripts/vrrp-check.sh script` every 60 seconds, and transition the +group to the fault state if it fails (i.e. exits with non-zero status) three +times: + +``` none +set high-availability vrrp group Foo health-check script /config/scripts/vrrp-check.sh +set high-availability vrrp group Foo health-check interval 60 +set high-availability vrrp group Foo health-check failure-count 3 +``` + +When the vrrp group is a member of the sync group will use only +the sync group health check script. +This example shows how to configure it for the sync group: + +``` none +set high-availability vrrp sync-group Bar health-check script /config/scripts/vrrp-check.sh +set high-availability vrrp sync-group Bar health-check interval 60 +set high-availability vrrp sync-group Bar health-check failure-count 3 +``` + +### Transition scripts + +Transition scripts can help you implement various fixups, such as starting and +stopping services, or even modifying the VyOS config on VRRP transition. +This setup will make the VRRP process execute the +`/config/scripts/vrrp-fail.sh` with argument `Foo` when VRRP fails, +and the `/config/scripts/vrrp-master.sh` when the router becomes the master: + +``` none +set high-availability vrrp group Foo transition-script backup "/config/scripts/vrrp-fail.sh Foo" +set high-availability vrrp group Foo transition-script fault "/config/scripts/vrrp-fail.sh Foo" +set high-availability vrrp group Foo transition-script master "/config/scripts/vrrp-master.sh Foo" +``` + +To know more about scripting, check the `command-scripting` section. + +## Virtual-server + +Virtual Server allows to Load-balance traffic destination virtual-address:port +between several real servers. + +### Algorithm + +Load-balancing schedule algorithm: + +- round-robin +- weighted-round-robin +- least-connection +- weighted-least-connection +- source-hashing +- destination-hashing +- locality-based-least-connection + +``` none +set high-availability virtual-server 203.0.113.1 algorithm 'least-connection' +``` + +### Forward method + +- NAT +- direct +- tunnel + +``` none +set high-availability virtual-server 203.0.113.1 forward-method 'nat' +``` + +### Health-check + +Custom health-check script allows checking real-server availability + +``` none +set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 health-check script <path-to-script> +``` + +### Fwmark + +Firewall mark. It possible to loadbalancing traffic based on `fwmark` value + +``` none +set high-availability virtual-server 203.0.113.1 fwmark '111' +``` + +### Real server + +Real server IP address and port + +``` none +set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 port '80' +``` + +### Example + +Virtual-server can be configured with VRRP virtual address or without VRRP. + +In the next example all traffic destined to `203.0.113.1` and port `8280` +protocol TCP is balanced between 2 real servers `192.0.2.11` and +`192.0.2.12` to port `80` + +Real server is auto-excluded if port check with this server fail. + +``` none +set interfaces ethernet eth0 address '203.0.113.11/24' +set interfaces ethernet eth1 address '192.0.2.1/24' +set high-availability vrrp group FOO interface 'eth0' +set high-availability vrrp group FOO no-preempt +set high-availability vrrp group FOO priority '150' +set high-availability vrrp group FOO address '203.0.113.1/24' +set high-availability vrrp group FOO vrid '10' + +set high-availability virtual-server 203.0.113.1 algorithm 'source-hashing' +set high-availability virtual-server 203.0.113.1 delay-loop '10' +set high-availability virtual-server 203.0.113.1 forward-method 'nat' +set high-availability virtual-server 203.0.113.1 persistence-timeout '180' +set high-availability virtual-server 203.0.113.1 port '8280' +set high-availability virtual-server 203.0.113.1 protocol 'tcp' +set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 port '80' +set high-availability virtual-server 203.0.113.1 real-server 192.0.2.12 port '80' +``` + +A firewall mark `fwmark` allows using multiple ports for high-availability +virtual-server. +It uses fwmark value. + +In this example all traffic destined to ports "80, 2222, 8888" protocol TCP +marks to fwmark "111" and balanced between 2 real servers. +Port "0" is required if multiple ports are used. + +``` none +set interfaces ethernet eth0 address 'dhcp' +set interfaces ethernet eth0 description 'WAN' +set interfaces ethernet eth1 address '192.0.2.1/24' +set interfaces ethernet eth1 description 'LAN' + +set policy route PR interface 'eth0' +set policy route PR rule 10 destination port '80,2222,8888' +set policy route PR rule 10 protocol 'tcp' +set policy route PR rule 10 set mark '111' + +set high-availability virtual-server vyos fwmark '111' +set high-availability virtual-server vyos protocol 'tcp' +set high-availability virtual-server vyos real-server 192.0.2.11 health-check script '/config/scripts/check-real-server-first.sh' +set high-availability virtual-server vyos real-server 192.0.2.11 port '0' +set high-availability virtual-server vyos real-server 192.0.2.12 health-check script '/config/scripts/check-real-server-second.sh' +set high-availability virtual-server vyos real-server 192.0.2.12 port '0' + +set nat source rule 100 outbound-interface 'eth0' +set nat source rule 100 source address '192.0.2.0/24' +set nat source rule 100 translation address 'masquerade' +``` + +Op-mode check virtual-server status + +``` none +vyos@r14:~$ run show virtual-server +IP Virtual Server version 1.2.1 (size=4096) +Prot LocalAddress:Port Scheduler Flags + -> RemoteAddress:Port Forward Weight ActiveConn InActConn +FWM 111 lc persistent 300 + -> 192.0.2.11:0 Masq 1 0 0 + -> 192.0.2.12:0 Masq 1 1 0 +``` diff --git a/docs/configuration/interfaces/md-bonding.md b/docs/configuration/interfaces/md-bonding.md new file mode 100644 index 00000000..837b61c5 --- /dev/null +++ b/docs/configuration/interfaces/md-bonding.md @@ -0,0 +1,731 @@ +lastproofread +2021-06-30 + +# Bond / Link Aggregation + +The bonding interface provides a method for aggregating multiple network +interfaces into a single logical "bonded" interface, or LAG, or ether-channel, +or port-channel. The behavior of the bonded interfaces depends upon the mode; +generally speaking, modes provide either hot standby or load balancing services. +Additionally, link integrity monitoring may be performed. + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="bonding" var1="bond0"> + +/\_include/interface-common-with-dhcp.txt + +</div> + +### Member Interfaces + +<div class="cfgcmd"> + +set interfaces bonding \<interface\> member interface \<member\> + +Enslave <span class="title-ref">\<member\></span> interface to bond <span class="title-ref">\<interface\></span>. + +</div> + +### Bond options + +<div class="cfgcmd"> + +set interfaces bonding \<interface\> mode \<802.3ad | active-backup | +broadcast | round-robin | transmit-load-balance | adaptive-load-balance | +xor-hash\> + +Specifies one of the bonding policies. The default is 802.3ad. Possible +values are: + +- `802.3ad` - IEEE 802.3ad Dynamic link aggregation. Creates aggregation + groups that share the same speed and duplex settings. Utilizes all slaves + in the active aggregator according to the 802.3ad specification. + + Slave selection for outgoing traffic is done according to the transmit + hash policy, which may be changed from the default simple XOR policy via + the `hash-policy` option, documented below. + + <div class="note"> + + <div class="title"> + + Note + + </div> + + Not all transmit policies may be 802.3ad compliant, particularly + in regards to the packet misordering requirements of section 43.2.4 + of the 802.3ad standard. + + </div> + +- `active-backup` - Active-backup policy: Only one slave in the bond is + active. A different slave becomes active if, and only if, the active slave + fails. The bond's MAC address is externally visible on only one port + (network adapter) to avoid confusing the switch. + + When a failover occurs in active-backup mode, bonding will issue one or + more gratuitous ARPs on the newly active slave. One gratuitous ARP is + issued for the bonding master interface and each VLAN interfaces + configured above it, provided that the interface has at least one IP + address configured. Gratuitous ARPs issued for VLAN interfaces are tagged + with the appropriate VLAN id. + + This mode provides fault tolerance. The `primary` option, + documented below, affects the behavior of this mode. + +- `broadcast` - Broadcast policy: transmits everything on all slave + interfaces. + + This mode provides fault tolerance. + +- `round-robin` - Round-robin policy: Transmit packets in sequential + order from the first available slave through the last. + + This mode provides load balancing and fault tolerance. + +- `transmit-load-balance` - Adaptive transmit load balancing: channel + bonding that does not require any special switch support. + + Incoming traffic is received by the current slave. If the receiving slave + fails, another slave takes over the MAC address of the failed receiving + slave. + +- `adaptive-load-balance` - Adaptive load balancing: includes + transmit-load-balance plus receive load balancing for IPV4 traffic, and + does not require any special switch support. The receive load balancing + is achieved by ARP negotiation. The bonding driver intercepts the ARP + Replies sent by the local system on their way out and overwrites the + source hardware address with the unique hardware address of one of the + slaves in the bond such that different peers use different hardware + addresses for the server. + + Receive traffic from connections created by the server is also balanced. + When the local system sends an ARP Request the bonding driver copies and + saves the peer's IP information from the ARP packet. When the ARP Reply + arrives from the peer, its hardware address is retrieved and the bonding + driver initiates an ARP reply to this peer assigning it to one of the + slaves in the bond. A problematic outcome of using ARP negotiation for + balancing is that each time that an ARP request is broadcast it uses the + hardware address of the bond. Hence, peers learn the hardware address + of the bond and the balancing of receive traffic collapses to the current + slave. This is handled by sending updates (ARP Replies) to all the peers + with their individually assigned hardware address such that the traffic + is redistributed. Receive traffic is also redistributed when a new slave + is added to the bond and when an inactive slave is re-activated. The + receive load is distributed sequentially (round robin) among the group + of highest speed slaves in the bond. + + When a link is reconnected or a new slave joins the bond the receive + traffic is redistributed among all active slaves in the bond by initiating + ARP Replies with the selected MAC address to each of the clients. The + updelay parameter (detailed below) must be set to a value equal or greater + than the switch's forwarding delay so that the ARP Replies sent to the + peers will not be blocked by the switch. + +- `xor-hash` - XOR policy: Transmit based on the selected transmit + hash policy. The default policy is a simple \[(source MAC address XOR'd + with destination MAC address XOR packet type ID) modulo slave count\]. + Alternate transmit policies may be selected via the `hash-policy` + option, described below. + + This mode provides load balancing and fault tolerance. + +</div> + +<div class="cfgcmd"> + +set interfaces bonding \<interface\> min-links \<0-16\> + +Specifies the minimum number of links that must be active before asserting +carrier. It is similar to the Cisco EtherChannel min-links feature. This +allows setting the minimum number of member ports that must be up (link-up +state) before marking the bond device as up (carrier on). This is useful for +situations where higher level services such as clustering want to ensure a +minimum number of low bandwidth links are active before switchover. + +This option only affects 802.3ad mode. + +The default value is 0. This will cause the carrier to be asserted +(for 802.3ad mode) whenever there is an active aggregator, +regardless of the number of available links in that aggregator. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Because an aggregator cannot be active without at least one +available link, setting this option to 0 or to 1 has the exact same +effect. + +</div> + +</div> + +<div class="cfgcmd"> + +set interfaces bonding \<interface\> lacp-rate \<slow|fast\> + +Option specifying the rate in which we'll ask our link partner to transmit +LACPDU packets in 802.3ad mode. + +This option only affects 802.3ad mode. + +- slow: Request partner to transmit LACPDUs every 30 seconds +- fast: Request partner to transmit LACPDUs every 1 second + +The default value is slow. + +</div> + +<div class="cfgcmd"> + +set interfaces bonding \<interface\> system-mac \<mac address\> + +This option allow to specifies the 802.3ad system MAC address.You can set a +random mac-address that can be used for these LACPDU exchanges. + +</div> + +<div class="cfgcmd"> + +set interfaces bonding \<interface\> hash-policy \<policy\> + +- **layer2** - Uses XOR of hardware MAC addresses and packet type ID field + to generate the hash. The formula is + + ``` none + hash = source MAC XOR destination MAC XOR packet type ID + slave number = hash modulo slave count + ``` + + This algorithm will place all traffic to a particular network peer on + the same slave. + + This algorithm is 802.3ad compliant. + +- **layer2+3** - This policy uses a combination of layer2 and layer3 + protocol information to generate the hash. Uses XOR of hardware MAC + addresses and IP addresses to generate the hash. The formula is: + + ``` none + hash = source MAC XOR destination MAC XOR packet type ID + hash = hash XOR source IP XOR destination IP + hash = hash XOR (hash RSHIFT 16) + hash = hash XOR (hash RSHIFT 8) + ``` + + And then hash is reduced modulo slave count. + + If the protocol is IPv6 then the source and destination addresses are + first hashed using ipv6_addr_hash. + + This algorithm will place all traffic to a particular network peer on the + same slave. For non-IP traffic, the formula is the same as for the layer2 + transmit hash policy. + + This policy is intended to provide a more balanced distribution of traffic + than layer2 alone, especially in environments where a layer3 gateway + device is required to reach most destinations. + + This algorithm is 802.3ad compliant. + +- **layer3+4** - This policy uses upper layer protocol information, when + available, to generate the hash. This allows for traffic to a particular + network peer to span multiple slaves, although a single connection will + not span multiple slaves. + + The formula for unfragmented TCP and UDP packets is + + ``` none + hash = source port, destination port (as in the header) + hash = hash XOR source IP XOR destination IP + hash = hash XOR (hash RSHIFT 16) + hash = hash XOR (hash RSHIFT 8) + ``` + + And then hash is reduced modulo slave count. + + If the protocol is IPv6 then the source and destination addresses are + first hashed using ipv6_addr_hash. + + For fragmented TCP or UDP packets and all other IPv4 and IPv6 protocol + traffic, the source and destination port information is omitted. For + non-IP traffic, the formula is the same as for the layer2 transmit hash + policy. + + This algorithm is not fully 802.3ad compliant. A single TCP or UDP + conversation containing both fragmented and unfragmented packets will see + packets striped across two interfaces. This may result in out of order + delivery. Most traffic types will not meet these criteria, as TCP rarely + fragments traffic, and most UDP traffic is not involved in extended + conversations. Other implementations of 802.3ad may or may not tolerate + this noncompliance. + +</div> + +<div class="cfgcmd"> + +set interfaces bonding \<interface\> primary \<interface\> + +An <span class="title-ref">\<interface\></span> specifying which slave is the primary device. The specified +device will always be the active slave while it is available. Only when the +primary is off-line will alternate devices be used. This is useful when one +slave is preferred over another, e.g., when one slave has higher throughput +than another. + +The primary option is only valid for active-backup, transmit-load-balance, +and adaptive-load-balance mode. + +</div> + +<div class="cfgcmd"> + +set interfaces bonding \<interface\> arp-monitor interval \<time\> + +Specifies the ARP link monitoring <span class="title-ref">\<time\></span> in seconds. + +The ARP monitor works by periodically checking the slave devices to determine +whether they have sent or received traffic recently (the precise criteria +depends upon the bonding mode, and the state of the slave). Regular traffic +is generated via ARP probes issued for the addresses specified by the +`arp-monitor target` option. + +If ARP monitoring is used in an etherchannel compatible mode (modes +round-robin and xor-hash), the switch should be configured in a mode that +evenly distributes packets across all links. If the switch is configured to +distribute the packets in an XOR fashion, all replies from the ARP targets +will be received on the same link which could cause the other team members +to fail. + +A value of 0 disables ARP monitoring. The default value is 0. + +</div> + +<div class="cfgcmd"> + +set interfaces bonding \<interface\> arp-monitor target \<address\> + +Specifies the IP addresses to use as ARP monitoring peers when +`arp-monitor interval` option is \> 0. These are the targets of the +ARP request sent to determine the health of the link to the targets. + +Multiple target IP addresses can be specified. At least one IP address must +be given for ARP monitoring to function. + +The maximum number of targets that can be specified is 16. The default value +is no IP address. + +</div> + +### VLAN + +<div class="cmdinclude" var0="bonding" var1="bond0"> + +/\_include/interface-vlan-8021q.txt + +</div> + +### Port Mirror (SPAN) + +<div class="cmdinclude" var0="bondinging" var1="bond1" var2="eth3"> + +../../\_include/interface-mirror.txt + +</div> + +#### EVPN Multihoming + +All-Active Multihoming is used for redundancy and load sharing. Servers are +attached to two or more PEs and the links are bonded (link-aggregation). +This group of server links is referred to as an `ES (Ethernet Segment)`. + +An Ethernet Segment can be configured by specifying a system-MAC and a local +discriminator or a complete ESINAME against the bond interface on the PE. + +<div class="cfgcmd"> + +set interfaces bonding \<interface\> evpn es-id \<\<1-16777215|10-byte ID\> + +</div> + +<div class="cfgcmd"> + +set interfaces bonding \<interface\> evpn es-sys-mac \<xx:xx:xx:xx:xx:xx\> + +The sys-mac and local discriminator are used for generating a 10-byte, Type-3 +Ethernet Segment ID. ESINAME is a 10-byte, Type-0 Ethernet Segment ID - +"00:AA:BB:CC:DD:EE:FF:GG:HH:II". + +Type-1 (EAD-per-ES and EAD-per-EVI) routes are used to advertise the locally +attached ESs and to learn off remote ESs in the network. Local Type-2/MAC-IP +routes are also advertised with a destination ESI allowing for MAC-IP syncing +between Ethernet Segment peers. Reference: RFC 7432, RFC 8365 + +EVPN-MH is intended as a replacement for MLAG or Anycast VTEPs. In multihoming +each PE has an unique VTEP address which requires the introduction of a new +dataplane construct, MAC-ECMP. Here a MAC/FDB entry can point to a list of +remote PEs/VTEPs. + +</div> + +<div class="cfgcmd"> + +set interfaces bonding \<interface\> evpn es-df-pref \<1-65535\> + +Type-4 (ESR) routes are used for Designated Forwarder (DF) election. +DFs forward BUM traffic received via the overlay network. This +implementation uses a preference based DF election specified by +draft-ietf-bess-evpn-pref-df. + +The DF preference is configurable per-ES. + +BUM traffic is rxed via the overlay by all PEs attached to a server but +only the DF can forward the de-capsulated traffic to the access port. +To accommodate that non-DF filters are installed in the dataplane to drop +the traffic. + +Similarly traffic received from ES peers via the overlay cannot be forwarded +to the server. This is split-horizon-filtering with local bias. + +</div> + +<div class="cmdinclude" var0="bonding" var1="bond0"> + +/\_include/interface-evpn-uplink.txt + +</div> + +## Example + +The following configuration on VyOS applies to all following 3rd party vendors. +It creates a bond with two links and VLAN 10, 100 on the bonded interfaces with +a per VIF IPv4 address. + +``` none +# Create bonding interface bond0 with 802.3ad LACP +set interfaces bonding bond0 hash-policy 'layer2' +set interfaces bonding bond0 mode '802.3ad' + +# Add the required vlans and IPv4 addresses on them +set interfaces bonding bond0 vif 10 address 192.168.0.1/24 +set interfaces bonding bond0 vif 100 address 10.10.10.1/24 + +# Add the member interfaces to the bonding interface +set interfaces bonding bond0 member interface eth1 +set interfaces bonding bond0 member interface eth2 +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you happen to run this in a virtual environment like by EVE-NG +you need to ensure your VyOS NIC is set to use the e1000 driver. Using the +default `virtio-net-pci` or the `vmxnet3` driver will not work. ICMP +messages will not be properly processed. They are visible on the virtual wire +but will not make it fully up the networking stack. + +You can check your NIC driver by issuing `show interfaces ethernet +eth0 physical | grep -i driver` + +</div> + +### Cisco Catalyst + +Assign member interfaces to PortChannel + +``` none +interface GigabitEthernet1/0/23 + description VyOS eth1 + channel-group 1 mode active +! +interface GigabitEthernet1/0/24 + description VyOS eth2 + channel-group 1 mode active +! +``` + +A new interface becomes present `Port-channel1`, all configuration like +allowed VLAN interfaces, STP will happen here. + +``` none +interface Port-channel1 + description LACP Channel for VyOS + switchport trunk encapsulation dot1q + switchport trunk allowed vlan 10,100 + switchport mode trunk + spanning-tree portfast trunk +! +``` + +### Juniper EX Switch + +For a headstart you can use the below example on how to build a bond with two +interfaces from VyOS to a Juniper EX Switch system. + +``` none +# Create aggregated ethernet device with 802.3ad LACP and port speeds of 10gbit/s +set interfaces ae0 aggregated-ether-options link-speed 10g +set interfaces ae0 aggregated-ether-options lacp active + +# Create layer 2 on the aggregated ethernet device with trunking for our vlans +set interfaces ae0 unit 0 family ethernet-switching port-mode trunk + +# Add the required vlans to the device +set interfaces ae0 unit 0 family ethernet-switching vlan members 10 +set interfaces ae0 unit 0 family ethernet-switching vlan members 100 + +# Add the two interfaces to the aggregated ethernet device, in this setup both +# ports are on the same switch (switch 0, module 1, port 0 and 1) +set interfaces xe-0/1/0 ether-options 802.3ad ae0 +set interfaces xe-0/1/1 ether-options 802.3ad ae0 + +# But this can also be done with multiple switches in a stack, a virtual +# chassis on Juniper (switch 0 and switch 1, module 1, port 0 on both switches) +set interfaces xe-0/1/0 ether-options 802.3ad ae0 +set interfaces xe-1/1/0 ether-options 802.3ad ae0 +``` + +### Aruba/HP + +For a headstart you can use the below example on how to build a +bond,port-channel with two interfaces from VyOS to a Aruba/HP 2510G switch. + +``` none +# Create trunk with 2 member interfaces (interface 1 and 2) and LACP +trunk 1-2 Trk1 LACP + +# Add the required vlans to the trunk +vlan 10 tagged Trk1 +vlan 100 tagged Trk1 +``` + +### Arista EOS + +When utilizing VyOS in an environment with Arista gear you can use this blue +print as an initial setup to get an LACP bond / port-channel operational between +those two devices. + +Lets assume the following topology: + +<figure> +<img src="/_static/images/vyos_arista_bond_lacp.webp" alt="VyOS Arista EOS setup" /> +</figure> + +**R1** + +> ``` none +> interfaces { +> bonding bond10 { +> hash-policy layer3+4 +> member { +> interface eth1 +> interface eth2 +> } +> mode 802.3ad +> vif 100 { +> address 192.0.2.1/30 +> address 2001:db8::1/64 +> } +> } +> ``` + +**R2** + +> ``` none +> interfaces { +> bonding bond10 { +> hash-policy layer3+4 +> member { +> interface eth1 +> interface eth2 +> } +> mode 802.3ad +> vif 100 { +> address 192.0.2.2/30 +> address 2001:db8::2/64 +> } +> } +> ``` + +**SW1** + +> ``` none +> ! +> vlan 100 +> name FOO +> ! +> interface Port-Channel10 +> switchport trunk allowed vlan 100 +> switchport mode trunk +> spanning-tree portfast +> ! +> interface Port-Channel20 +> switchport mode trunk +> no spanning-tree portfast auto +> spanning-tree portfast network +> ! +> interface Ethernet1 +> channel-group 10 mode active +> ! +> interface Ethernet2 +> channel-group 10 mode active +> ! +> interface Ethernet3 +> channel-group 20 mode active +> ! +> interface Ethernet4 +> channel-group 20 mode active +> ! +> ``` + +**SW2** + +> ``` none +> ! +> vlan 100 +> name FOO +> ! +> interface Port-Channel10 +> switchport trunk allowed vlan 100 +> switchport mode trunk +> spanning-tree portfast +> ! +> interface Port-Channel20 +> switchport mode trunk +> no spanning-tree portfast auto +> spanning-tree portfast network +> ! +> interface Ethernet1 +> channel-group 10 mode active +> ! +> interface Ethernet2 +> channel-group 10 mode active +> ! +> interface Ethernet3 +> channel-group 20 mode active +> ! +> interface Ethernet4 +> channel-group 20 mode active +> ! +> ``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +When using EVE-NG to lab this environment ensure you are using e1000 +as the desired driver for your VyOS network interfaces. When using the +regular virtio network driver no LACP PDUs will be sent by VyOS thus the +port-channel will never become active! + +</div> + +## Operation + +<div class="opcmd"> + +show interfaces bonding + +Show brief interface information. + +``` none +vyos@vyos:~$ show interfaces bonding +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +bond0 - u/u my-sw1 int 23 and 24 +bond0.10 192.168.0.1/24 u/u office-net +bond0.100 10.10.10.1/24 u/u management-net +``` + +</div> + +<div class="opcmd"> + +show interfaces bonding \<interface\> + +Show detailed information on given <span class="title-ref">\<interface\></span> + +``` none +vyos@vyos:~$ show interfaces bonding bond5 +bond5: <NO-CARRIER,BROADCAST,MULTICAST,MASTER,UP> mtu 1500 qdisc noqueue state DOWN group default qlen 1000 + link/ether 00:50:56:bf:ef:aa brd ff:ff:ff:ff:ff:ff + inet6 fe80::e862:26ff:fe72:2dac/64 scope link tentative + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 0 0 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 0 0 0 0 0 0 +``` + +</div> + +<div class="opcmd"> + +show interfaces bonding \<interface\> detail + +Show detailed information about the underlaying physical links on given +bond <span class="title-ref">\<interface\></span>. + +``` none +vyos@vyos:~$ show interfaces bonding bond5 detail +Ethernet Channel Bonding Driver: v3.7.1 (April 27, 2011) + +Bonding Mode: IEEE 802.3ad Dynamic link aggregation +Transmit Hash Policy: layer2 (0) +MII Status: down +MII Polling Interval (ms): 100 +Up Delay (ms): 0 +Down Delay (ms): 0 + +802.3ad info +LACP rate: slow +Min links: 0 +Aggregator selection policy (ad_select): stable + +Slave Interface: eth1 +MII Status: down +Speed: Unknown +Duplex: Unknown +Link Failure Count: 0 +Permanent HW addr: 00:50:56:bf:ef:aa +Slave queue ID: 0 +Aggregator ID: 1 +Actor Churn State: churned +Partner Churn State: churned +Actor Churned Count: 1 +Partner Churned Count: 1 + +Slave Interface: eth2 +MII Status: down +Speed: Unknown +Duplex: Unknown +Link Failure Count: 0 +Permanent HW addr: 00:50:56:bf:19:26 +Slave queue ID: 0 +Aggregator ID: 2 +Actor Churn State: churned +Partner Churn State: churned +Actor Churned Count: 1 +Partner Churned Count: 1 +``` + +</div> diff --git a/docs/configuration/interfaces/md-bridge.md b/docs/configuration/interfaces/md-bridge.md new file mode 100644 index 00000000..732ea8e9 --- /dev/null +++ b/docs/configuration/interfaces/md-bridge.md @@ -0,0 +1,405 @@ +lastproofread +2021-06-30 + +# Bridge + +A Bridge is a way to connect two Ethernet segments together in a +protocol independent way. Packets are forwarded based on Ethernet +address, rather than IP address (like a router). Since forwarding is +done at Layer 2, all protocols can go transparently through a bridge. +The Linux bridge code implements a subset of the ANSI/IEEE 802.1d +standard. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Spanning Tree Protocol is not enabled by default in VyOS. +`stp` can be easily enabled if needed. + +</div> + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="bridge" var1="br0"> + +/\_include/interface-common-with-dhcp.txt + +</div> + +### Member Interfaces + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> member interface \<member\> + +Assign <span class="title-ref">\<member\></span> interface to bridge <span class="title-ref">\<interface\></span>. A completion +helper will help you with all allowed interfaces which can be +bridged. This includes `ethernet-interface`, +`bond-interface`, `l2tpv3-interface`, `openvpn`, +`vxlan-interface`, `wireless-interface`, +`tunnel-interface` and `geneve-interface`. + +</div> + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> member interface \<member\> +priority \<priority\> + +Configure individual bridge port <span class="title-ref">\<priority\></span>. + +Each bridge has a relative priority and cost. Each interface is +associated with a port (number) in the STP code. Each has a priority +and a cost, that is used to decide which is the shortest path to +forward a packet. The lowest cost path is always used unless the +other path is down. If you have multiple bridges and interfaces then +you may need to adjust the priorities to achieve optimum +performance. + +</div> + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> member interface \<member\> +cost \<cost\> + +Path <span class="title-ref">\<cost\></span> value for Spanning Tree Protocol. Each interface in a +bridge could have a different speed and this value is used when +deciding which link to use. Faster interfaces should have lower +costs. + +</div> + +### Bridge Options + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> aging \<time\> + +MAC address aging <span class="title-ref">\<time</span>\> in seconds (default: 300). + +</div> + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> max-age \<time\> + +Bridge maximum aging <span class="title-ref">\<time\></span> in seconds (default: 20). + +If an another bridge in the spanning tree does not send out a hello +packet for a long period of time, it is assumed to be dead. + +</div> + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> igmp querier + +Enable IGMP and MLD querier. + +</div> + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> igmp snooping + +Enable IGMP and MLD snooping. + +</div> + +#### STP Parameter + +`STP (Spanning Tree Protocol)` is a network protocol that builds a +loop-free logical topology for Ethernet networks. The basic function of +STP is to prevent bridge loops and the broadcast radiation that results +from them. Spanning tree also allows a network design to include backup +links providing fault tolerance if an active link fails. + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> stp + +Enable spanning tree protocol. STP is disabled by default. + +</div> + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> forwarding-delay \<delay\> + +Spanning Tree Protocol forwarding <span class="title-ref">\<delay\></span> in seconds (default: 15). + +The forwarding delay time is the time spent in each of the listening and +learning states before the Forwarding state is entered. This delay is +so that when a new bridge comes onto a busy network it looks at some +traffic before participating. + +</div> + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> hello-time \<interval\> + +Spanning Tree Protocol hello advertisement <span class="title-ref">\<interval\></span> in seconds +(default: 2). + +Periodically, a hello packet is sent out by the Root Bridge and the +Designated Bridges. Hello packets are used to communicate information +about the topology throughout the entire Bridged Local Area Network. + +</div> + +### VLAN + +#### Enable VLAN-Aware Bridge + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> enable-vlan + +To activate the VLAN aware bridge, you must activate this setting to use VLAN +settings for the bridge + +</div> + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> protocol \<802.1ad|802.1q\> + +Define used ethertype of bridge interface. + +Ethertype `0x8100` is used for `802.1q` and ethertype `0x88a8` is used +for `802.1ad`. + +The default is `802.1q`. + +</div> + +#### VLAN Options + +<div class="note"> + +<div class="title"> + +Note + +</div> + +It is not valid to use the <span class="title-ref">vif 1</span> option for VLAN aware bridges +because VLAN aware bridges assume that all unlabeled packets belong to +the default VLAN 1 member and that the VLAN ID of the bridge's parent +interface is always 1 + +</div> + +<div class="cmdinclude" var0="bridge" var1="br0"> + +/\_include/interface-vlan-8021q.txt + +</div> + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> member interface \<member\> +native-vlan \<vlan-id\> + +Set the native VLAN ID flag of the interface. When a data packet without a +VLAN tag enters the port, the data packet will be forced to add a tag of a +specific vlan id. When the vlan id flag flows out, the tag of the vlan id +will be stripped + +Example: Set <span class="title-ref">eth0</span> member port to be native VLAN 2 + +``` none +set interfaces bridge br1 member interface eth0 native-vlan 2 +``` + +</div> + +<div class="cfgcmd"> + +set interfaces bridge \<interface\> member interface \<member\> +allowed-vlan \<vlan-id\> + +Allows specific VLAN IDs to pass through the bridge member interface. This +can either be an individual VLAN id or a range of VLAN ids delimited by a +hyphen. + +Example: Set <span class="title-ref">eth0</span> member port to be allowed VLAN 4 + +``` none +set interfaces bridge br1 member interface eth0 allowed-vlan 4 +``` + +Example: Set <span class="title-ref">eth0</span> member port to be allowed VLAN 6-8 + +``` none +set interfaces bridge br1 member interface eth0 allowed-vlan 6-8 +``` + +</div> + +### Port Mirror (SPAN) + +<div class="cmdinclude" var0="bridge" var1="br1" var2="eth3"> + +../../\_include/interface-mirror.txt + +</div> + +## Examples + +### Create a basic bridge + +Creating a bridge interface is very simple. In this example, we will +have: + +- A bridge named <span class="title-ref">br100</span> +- Member interfaces <span class="title-ref">eth1</span> and VLAN 10 on interface <span class="title-ref">eth2</span> +- Enable STP +- Bridge answers on IP address 192.0.2.1/24 and 2001:db8::ffff/64 + +``` none +set interfaces bridge br100 address 192.0.2.1/24 +set interfaces bridge br100 address 2001:db8::ffff/64 +set interfaces bridge br100 member interface eth1 +set interfaces bridge br100 member interface eth2.10 +set interfaces bridge br100 stp +``` + +This results in the active configuration: + +``` none +vyos@vyos# show interfaces bridge br100 + address 192.0.2.1/24 + address 2001:db8::ffff/64 + member { + interface eth1 { + } + interface eth2.10 { + } + } + stp +``` + +### Using VLAN aware Bridge + +An example of creating a VLAN-aware bridge is as follows: + +- A bridge named <span class="title-ref">br100</span> +- The member interface <span class="title-ref">eth1</span> is a trunk that allows VLAN 10 to pass +- VLAN 10 on member interface <span class="title-ref">eth2</span> (ACCESS mode) +- Enable STP +- Bridge answers on IP address 192.0.2.1/24 and 2001:db8::ffff/64 + +``` none +set interfaces bridge br100 enable-vlan +set interfaces bridge br100 member interface eth1 allowed-vlan 10 +set interfaces bridge br100 member interface eth2 native-vlan 10 +set interfaces bridge br100 vif 10 address 192.0.2.1/24 +set interfaces bridge br100 vif 10 address 2001:db8::ffff/64 +set interfaces bridge br100 stp +``` + +This results in the active configuration: + +``` none +vyos@vyos# show interfaces bridge br100 + enable-vlan + member { + interface eth1 { + allowed-vlan 10 + } + interface eth2 { + native-vlan 10 + } + } + stp + vif 10 { + address 192.0.2.1/24 + address 2001:db8::ffff/64 + } +``` + +### Using the operation mode command to view Bridge Information + +<div class="opcmd"> + +show bridge + +The <span class="title-ref">show bridge</span> operational command can be used to display +configured bridges: + +``` none +vyos@vyos:~$ show bridge +3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br0 state forwarding +priority 32 cost 100 +4: eth2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br0 state forwarding +priority 32 cost 100 +``` + +</div> + +<div class="opcmd"> + +show bridge \<name\> fdb + +Show bridge <span class="title-ref">\<name\></span> fdb displays the current forwarding table: + +``` none +vyos@vyos:~$ show bridge br0 fdb +50:00:00:08:00:01 dev eth1 vlan 20 master br0 permanent +50:00:00:08:00:01 dev eth1 vlan 10 master br0 permanent +50:00:00:08:00:01 dev eth1 master br0 permanent +33:33:00:00:00:01 dev eth1 self permanent +33:33:00:00:00:02 dev eth1 self permanent +01:00:5e:00:00:01 dev eth1 self permanent +50:00:00:08:00:02 dev eth2 vlan 20 master br0 permanent +50:00:00:08:00:02 dev eth2 vlan 10 master br0 permanent +50:00:00:08:00:02 dev eth2 master br0 permanent +33:33:00:00:00:01 dev eth2 self permanent +33:33:00:00:00:02 dev eth2 self permanent +01:00:5e:00:00:01 dev eth2 self permanent +33:33:00:00:00:01 dev br0 self permanent +33:33:00:00:00:02 dev br0 self permanent +33:33:ff:08:00:01 dev br0 self permanent +01:00:5e:00:00:6a dev br0 self permanent +33:33:00:00:00:6a dev br0 self permanent +01:00:5e:00:00:01 dev br0 self permanent +33:33:ff:00:00:00 dev br0 self permanent +``` + +</div> + +<div class="opcmd"> + +show bridge \<name\> mdb + +Show bridge <span class="title-ref">\<name\></span> mdb displays the current multicast group membership +table.The table is populated by IGMP and MLD snooping in the bridge driver +automatically. + +``` none +vyos@vyos:~$ show bridge br0 mdb +dev br0 port br0 grp ff02::1:ff00:0 temp vid 1 +dev br0 port br0 grp ff02::2 temp vid 1 +dev br0 port br0 grp ff02::1:ff08:1 temp vid 1 +dev br0 port br0 grp ff02::6a temp vid 1 +``` + +</div> + +> Show bridge Media Access Control (MAC) address table +> +> ``` none +> vyos@vyos:~$ show bridge br100 macs +> port no mac addr is local? ageing timer +> 1 00:53:29:44:3b:19 yes 0.00 +> ``` diff --git a/docs/configuration/interfaces/md-dummy.md b/docs/configuration/interfaces/md-dummy.md new file mode 100644 index 00000000..ec79579e --- /dev/null +++ b/docs/configuration/interfaces/md-dummy.md @@ -0,0 +1,110 @@ +lastproofread +2023-01-20 + +# Dummy + +The dummy interface is really a little exotic, but rather useful nevertheless. +Dummy interfaces are much like the `loopback-interface` interface, except +you can have as many as you want. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Dummy interfaces can be used as interfaces that always stay up (in +the same fashion to loopbacks in Cisco IOS), or for testing purposes. + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +On systems with multiple redundant uplinks and routes, +it's a good idea to use a dedicated address for management and dynamic routing protocols. +However, assigning that address to a physical link is risky: +if that link goes down, that address will become inaccessible. +A common solution is to assign the management address to a loopback or a dummy interface +and advertise that address via all physical links, so that it's reachable +through any of them. Since in Linux-based systems, there can be only one loopback interface, +it's better to use a dummy interface for that purpose, since they can be added, removed, +and taken up and down independently. + +</div> + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="dummy" var1="dum0"> + +/\_include/interface-address.txt + +</div> + +<div class="cmdinclude" var0="dummy" var1="dum0"> + +/\_include/interface-description.txt + +</div> + +<div class="cmdinclude" var0="dummy" var1="dum0"> + +/\_include/interface-disable.txt + +</div> + +<div class="cmdinclude" var0="dummy" var1="dum0"> + +/\_include/interface-vrf.txt + +</div> + +## Operation + +<div class="opcmd"> + +show interfaces dummy + +Show brief interface information. + +``` none +vyos@vyos:~$ show interfaces dummy +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +dum0 172.18.254.201/32 u/u +``` + +</div> + +<div class="opcmd"> + +show interfaces dummy \<interface\> + +Show detailed information on given <span class="title-ref">\<interface\></span> + +``` none +vyos@vyos:~$ show interfaces dummy dum0 +dum0: <BROADCAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc noqueue state UNKNOWN group default qlen 1000 + link/ether 26:7c:8e:bc:fc:f5 brd ff:ff:ff:ff:ff:ff + inet 172.18.254.201/32 scope global dum0 + valid_lft forever preferred_lft forever + inet6 fe80::247c:8eff:febc:fcf5/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 0 0 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 1369707 4267 0 0 0 0 +``` + +</div> diff --git a/docs/configuration/interfaces/md-ethernet.md b/docs/configuration/interfaces/md-ethernet.md new file mode 100644 index 00000000..4b0ee7f5 --- /dev/null +++ b/docs/configuration/interfaces/md-ethernet.md @@ -0,0 +1,357 @@ +lastproofread +2023-01-20 + +# Ethernet + +This will be the most widely used interface on a router carrying traffic to the +real world. + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="ethernet" var1="eth0"> + +/\_include/interface-common-with-dhcp.txt + +</div> + +### Ethernet options + +<div class="cfgcmd"> + +set interfaces ethernet \<interface\> duplex \<auto | full | half\> + +Configure physical interface duplex setting. + +- auto - interface duplex setting is auto-negotiated +- full - always use full-duplex +- half - always use half-duplex + +VyOS default will be <span class="title-ref">auto</span>. + +</div> + +<div class="cfgcmd"> + +set interfaces ethernet \<interface\> speed \<auto | 10 | 100 | 1000 | +2500 | 5000 | 10000 | 25000 | 40000 | 50000 | 100000\> + +Configure physical interface speed setting. + +- auto - interface speed is auto-negotiated +- 10 - 10 MBit/s +- 100 - 100 MBit/s +- 1000 - 1 GBit/s +- 2500 - 2.5 GBit/s +- 5000 - 5 GBit/s +- 10000 - 10 GBit/s +- 25000 - 25 GBit/s +- 40000 - 40 GBit/s +- 50000 - 50 GBit/s +- 100000 - 100 GBit/s + +VyOS default will be <span class="title-ref">auto</span>. + +</div> + +<div class="cfgcmd"> + +set interface ethernet \<interface\> ring-buffer rx \<value\> + +</div> + +<div class="cfgcmd"> + +set interface ethernet \<interface\> ring-buffer tx \<value\> + +Configures the ring buffer size of the interface. + +The supported values for a specific interface can be obtained +with: <span class="title-ref">ethtool -g \<interface\></span> + +</div> + +#### Offloading + +<div class="cfgcmd"> + +set interfaces ethernet \<interface\> offload \<gro | gso | lro | rps | +sg | tso\> + +Enable different types of hardware offloading on the given NIC. + +`LRO (Large Receive Offload)` is a technique designed to boost the +efficiency of how your computer's network interface card (NIC) processes +incoming network traffic. Typically, network data arrives in smaller chunks +called packets. Processing each packet individually consumes CPU (central +processing unit) resources. Lots of small packets can lead to a performance +bottleneck. Instead of handing the CPU each packet as it comes in, LRO +instructs the NIC to combine multiple incoming packets into a single, larger +packet. This larger packet is then passed to the CPU for processing. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Under some circumstances, LRO is known to modify the packet headers +of forwarded traffic, which breaks the end-to-end principle of computer +networking. LRO is also only able to offload TCP segments encapsulated in +IPv4 packets. Due to these limitations, it is recommended to use GRO +(Generic Receive Offload) where possible. More information on the +limitations of LRO can be found here: <https://lwn.net/Articles/358910/> + +</div> + +`GSO (Generic Segmentation Offload)` is a pure software offload that is +meant to deal with cases where device drivers cannot perform the offloads +described above. What occurs in GSO is that a given skbuff will have its data +broken out over multiple skbuffs that have been resized to match the MSS +provided via skb_shinfo()-\>gso_size. + +Before enabling any hardware segmentation offload a corresponding software +offload is required in GSO. Otherwise it becomes possible for a frame to be +re-routed between devices and end up being unable to be transmitted. + +`GRO (Generic receive offload)` is the complement to GSO. Ideally any +frame assembled by GRO should be segmented to create an identical sequence of +frames using GSO, and any sequence of frames segmented by GSO should be able +to be reassembled back to the original by GRO. The only exception to this is +IPv4 ID in the case that the DF bit is set for a given IP header. If the +value of the IPv4 ID is not sequentially incrementing it will be altered so +that it is when a frame assembled via GRO is segmented via GSO. + +`RPS (Receive Packet Steering)` is logically a software implementation +of `RSS (Receive Side Scaling)`. Being in software, it is necessarily +called later in the datapath. Whereas RSS selects the queue and hence CPU that +will run the hardware interrupt handler, RPS selects the CPU to perform +protocol processing above the interrupt handler. This is accomplished by +placing the packet on the desired CPU's backlog queue and waking up the CPU +for processing. RPS has some advantages over RSS: + +- it can be used with any NIC +- software filters can easily be added to hash over new protocols +- it does not increase hardware device interrupt rate, although it does + introduce inter-processor interrupts (IPIs) + +<div class="note"> + +<div class="title"> + +Note + +</div> + +In order to use TSO/LRO with VMXNET3 adapters, the SG offloading +option must also be enabled. + +</div> + +</div> + +#### Authentication (EAPoL) + +<div class="cmdinclude" var0="ethernet" var1="eth0"> + +/\_include/interface-eapol.txt + +</div> + +#### EVPN Multihoming + +Uplink/Core tracking. + +<div class="cmdinclude" var0="ethernet" var1="eth0"> + +/\_include/interface-evpn-uplink.txt + +</div> + +### VLAN + +#### Regular VLANs (802.1q) + +<div class="cmdinclude" var0="ethernet" var1="eth0"> + +/\_include/interface-vlan-8021q.txt + +</div> + +#### QinQ (802.1ad) + +<div class="cmdinclude" var0="ethernet" var1="eth0"> + +/\_include/interface-vlan-8021ad.txt + +</div> + +### Port Mirror (SPAN) + +<div class="cmdinclude" var0="ethernet" var1="eth1" var2="eth3"> + +../../\_include/interface-mirror.txt + +</div> + +## Operation + +<div class="opcmd"> + +show interfaces ethernet + +Show brief interface information. + +``` none +vyos@vyos:~$ show interfaces ethernet +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +eth0 172.18.201.10/24 u/u LAN +eth1 172.18.202.11/24 u/u WAN +eth2 - u/D +``` + +</div> + +<div class="opcmd"> + +show interfaces ethernet \<interface\> + +Show detailed information on given <span class="title-ref">\<interface\></span> + +``` none +vyos@vyos:~$ show interfaces ethernet eth0 +eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 + link/ether 00:50:44:00:f5:c9 brd ff:ff:ff:ff:ff:ff + inet6 fe80::250:44ff:fe00:f5c9/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 56735451 179841 0 0 0 142380 + TX: bytes packets errors dropped carrier collisions + 5601460 62595 0 0 0 0 +``` + +</div> + +<div class="opcmd"> + +show interfaces ethernet \<interface\> physical + +Show information about physical <span class="title-ref">\<interface\></span> + +``` none +vyos@vyos:~$ show interfaces ethernet eth0 physical +Settings for eth0: + Supported ports: [ TP ] + Supported link modes: 1000baseT/Full + 10000baseT/Full + Supported pause frame use: No + Supports auto-negotiation: No + Supported FEC modes: Not reported + Advertised link modes: Not reported + Advertised pause frame use: No + Advertised auto-negotiation: No + Advertised FEC modes: Not reported + Speed: 10000Mb/s + Duplex: Full + Port: Twisted Pair + PHYAD: 0 + Transceiver: internal + Auto-negotiation: off + MDI-X: Unknown + Supports Wake-on: uag + Wake-on: d + Link detected: yes +driver: vmxnet3 +version: 1.4.16.0-k-NAPI +firmware-version: +expansion-rom-version: +bus-info: 0000:0b:00.0 +supports-statistics: yes +supports-test: no +supports-eeprom-access: no +supports-register-dump: yes +supports-priv-flags: no +``` + +</div> + +<div class="opcmd"> + +show interfaces ethernet \<interface\> physical offload + +Show available offloading functions on given <span class="title-ref">\<interface\></span> + +``` none +vyos@vyos:~$ show interfaces ethernet eth0 physical offload +rx-checksumming on +tx-checksumming on +tx-checksum-ip-generic on +scatter-gather off +tx-scatter-gather off +tcp-segmentation-offload off +tx-tcp-segmentation off +tx-tcp-mangleid-segmentation off +tx-tcp6-segmentation off +udp-fragmentation-offload off +generic-segmentation-offload off +generic-receive-offload off +large-receive-offload off +rx-vlan-offload on +tx-vlan-offload on +ntuple-filters off +receive-hashing on +tx-gre-segmentation on +tx-gre-csum-segmentation on +tx-udp_tnl-segmentation on +tx-udp_tnl-csum-segmentation on +tx-gso-partial on +tx-nocache-copy off +rx-all off +``` + +</div> + +<div class="opcmd"> + +show interfaces ethernet \<interface\> transceiver + +Show transceiver information from plugin modules, e.g SFP+, QSFP + +``` none +vyos@vyos:~$ show interfaces ethernet eth5 transceiver + Identifier : 0x03 (SFP) + Extended identifier : 0x04 (GBIC/SFP defined by 2-wire interface ID) + Connector : 0x07 (LC) + Transceiver codes : 0x00 0x00 0x00 0x01 0x00 0x00 0x00 0x00 0x00 + Transceiver type : Ethernet: 1000BASE-SX + Encoding : 0x01 (8B/10B) + BR, Nominal : 1300MBd + Rate identifier : 0x00 (unspecified) + Length (SMF,km) : 0km + Length (SMF) : 0m + Length (50um) : 550m + Length (62.5um) : 270m + Length (Copper) : 0m + Length (OM3) : 0m + Laser wavelength : 850nm + Vendor name : CISCO-FINISAR + Vendor OUI : 00:90:65 + Vendor PN : FTRJ-8519-7D-CS4 + Vendor rev : A + Option values : 0x00 0x1a + Option : RX_LOS implemented + Option : TX_FAULT implemented + Option : TX_DISABLE implemented + BR margin, max : 0% + BR margin, min : 0% + Vendor SN : FNS092xxxxx + Date code : 0506xx +``` + +</div> diff --git a/docs/configuration/interfaces/md-geneve.md b/docs/configuration/interfaces/md-geneve.md new file mode 100644 index 00000000..8bb145df --- /dev/null +++ b/docs/configuration/interfaces/md-geneve.md @@ -0,0 +1,102 @@ +lastproofread +2023-01-20 + +# GENEVE + +`GENEVE (Generic Network Virtualization Encapsulation)` supports all of +the capabilities of `VXLAN (Virtual Extensible LAN)`, `NVGRE +(Network Virtualization using Generic Routing Encapsulation)`, and `STT +(Stateless Transport Tunneling)` and was designed to overcome their perceived +limitations. Many believe GENEVE could eventually replace these earlier formats +entirely. + +GENEVE is designed to support network virtualization use cases, where tunnels +are typically established to act as a backplane between the virtual switches +residing in hypervisors, physical switches, or middleboxes or other appliances. +An arbitrary IP network can be used as an underlay although Clos networks - A +technique for composing network fabrics larger than a single switch while +maintaining non-blocking bandwidth across connection points. ECMP is used to +divide traffic across the multiple links and switches that constitute the +fabric. Sometimes termed "leaf and spine" or "fat tree" topologies. + +Geneve Header: + +``` none ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +|Ver| Opt Len |O|C| Rsvd. | Protocol Type | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Virtual Network Identifier (VNI) | Reserved | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Variable Length Options | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +``` + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="geneve" var1="gnv0"> + +/\_include/interface-address.txt + +</div> + +<div class="cmdinclude" var0="geneve" var1="gnv0"> + +/\_include/interface-description.txt + +</div> + +<div class="cmdinclude" var0="geneve" var1="gnv0"> + +/\_include/interface-disable.txt + +</div> + +<div class="cmdinclude" var0="geneve" var1="gnv0"> + +/\_include/interface-mac.txt + +</div> + +<div class="cmdinclude" var0="geneve" var1="gnv0"> + +/\_include/interface-mtu.txt + +</div> + +<div class="cmdinclude" var0="geneve" var1="gnv0"> + +/\_include/interface-ip.txt + +</div> + +<div class="cmdinclude" var0="geneve" var1="gnv0"> + +/\_include/interface-ipv6.txt + +</div> + +### GENEVE options + +<div class="cfgcmd"> + +set interfaces geneve gnv0 remote \<address\> + +Configure GENEVE tunnel far end/remote tunnel endpoint. + +</div> + +<div class="cfgcmd"> + +set interfaces geneve gnv0 vni \<vni\> + +`VNI (Virtual Network Identifier)` is an identifier for a unique +element of a virtual network. In many situations this may represent an L2 +segment, however, the control plane defines the forwarding semantics of +decapsulated packets. The VNI MAY be used as part of ECMP forwarding +decisions or MAY be used as a mechanism to distinguish between overlapping +address spaces contained in the encapsulated packet when load balancing +across CPUs. + +</div> diff --git a/docs/configuration/interfaces/md-index.md b/docs/configuration/interfaces/md-index.md new file mode 100644 index 00000000..5d66b2d0 --- /dev/null +++ b/docs/configuration/interfaces/md-index.md @@ -0,0 +1,25 @@ +# Interfaces + +<div class="toctree" maxdepth="1" includehidden=""> + +bonding +bridge +dummy +ethernet +geneve +l2tpv3 +loopback +macsec +openvpn +wireguard +pppoe +pseudo-ethernet +sstp-client +tunnel +virtual-ethernet +vti +vxlan +wireless +wwan + +</div> diff --git a/docs/configuration/interfaces/md-l2tpv3.md b/docs/configuration/interfaces/md-l2tpv3.md new file mode 100644 index 00000000..84e190f5 --- /dev/null +++ b/docs/configuration/interfaces/md-l2tpv3.md @@ -0,0 +1,206 @@ +lastproofread +2023-01-20 + +# L2TPv3 + +Layer 2 Tunnelling Protocol Version 3 is an IETF standard related to L2TP that +can be used as an alternative protocol to `mpls` for encapsulation of +multiprotocol Layer 2 communications traffic over IP networks. Like L2TP, +L2TPv3 provides a pseudo-wire service but is scaled to fit carrier requirements. + +L2TPv3 can be regarded as being to MPLS what IP is to ATM: a simplified version +of the same concept, with much of the same benefit achieved at a fraction of the +effort, at the cost of losing some technical features considered less important +in the market. + +In the case of L2TPv3, the features lost are teletraffic engineering features +considered important in MPLS. However, there is no reason these features could +not be re-engineered in or on top of L2TPv3 in later products. + +The protocol overhead of L2TPv3 is also significantly bigger than MPLS. + +L2TPv3 is described in `3931`. + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="l2tpv3" var1="l2tpeth0"> + +/\_include/interface-common-without-dhcp.txt + +</div> + +### L2TPv3 options + +<div class="cfgcmd"> + +set interfaces l2tpv3 \<interface\> encapsulation \<udp | ip\> + +Set the encapsulation type of the tunnel. Valid values for encapsulation are: +udp, ip. + +This defaults to UDP + +</div> + +<div class="cfgcmd"> + +set interfaces l2tpv3 \<interface\> source-address \<address\> + +Set the IP address of the local interface to be used for the tunnel. + +This address must be the address of a local interface. It may be specified as +an IPv4 address or an IPv6 address. + +</div> + +<div class="cfgcmd"> + +set interfaces l2tpv3 \<interface\> remote \<address\> + +Set the IP address of the remote peer. It may be specified as +an IPv4 address or an IPv6 address. + +</div> + +<div class="cfgcmd"> + +set interfaces l2tpv3 \<interface\> session-id \<id\> + +Set the session id, which is a 32-bit integer value. Uniquely identifies the +session being created. The value used must match the peer_session_id value +being used at the peer. + +</div> + +<div class="cfgcmd"> + +set interfaces l2tpv3 \<interface\> peer-session-id \<id\> + +Set the peer-session-id, which is a 32-bit integer value assigned to the +session by the peer. The value used must match the session_id value being +used at the peer. + +</div> + +<div class="cfgcmd"> + +set interfaces l2tpv3 \<interface\> tunnel-id \<id\> + +Set the tunnel id, which is a 32-bit integer value. Uniquely identifies the +tunnel into which the session will be created. + +</div> + +<div class="cfgcmd"> + +set interfaces l2tpv3 \<interface\> peer-tunnel-id \<id\> + +Set the tunnel id, which is a 32-bit integer value. Uniquely identifies the +tunnel into which the session will be created. + +</div> + +## Example + +### Over IP + +``` none +# show interfaces l2tpv3 +l2tpv3 l2tpeth10 { + address 192.168.37.1/27 + encapsulation ip + source-address 192.0.2.1 + peer-session-id 100 + peer-tunnel-id 200 + remote 203.0.113.24 + session-id 100 + tunnel-id 200 +} +``` + +The inverse configuration has to be applied to the remote side. + +### Over UDP + +UDP mode works better with NAT: + +- Set source-address to your local IP (LAN). +- Add a forwarding rule matching UDP port on your internet router. + +``` none +# show interfaces l2tpv3 +l2tpv3 l2tpeth10 { + address 192.168.37.1/27 + destination-port 9001 + encapsulation udp + source-address 192.0.2.1 + peer-session-id 100 + peer-tunnel-id 200 + remote 203.0.113.24 + session-id 100 + source-port 9000 + tunnel-id 200 +} +``` + +To create more than one tunnel, use distinct UDP ports. + +### Over IPSec, L2 VPN (bridge) + +This is the LAN extension use case. The eth0 port of the distant VPN peers +will be directly connected like if there was a switch between them. + +IPSec: + +``` none +set vpn ipsec authentication psk <pre-shared-name> id '%any' +set vpn ipsec authentication psk <pre-shared-name> secret <pre-shared-key> +set vpn ipsec interface <VPN-interface> +set vpn ipsec esp-group test-ESP-1 lifetime '3600' +set vpn ipsec esp-group test-ESP-1 mode 'transport' +set vpn ipsec esp-group test-ESP-1 pfs 'enable' +set vpn ipsec esp-group test-ESP-1 proposal 1 encryption 'aes128' +set vpn ipsec esp-group test-ESP-1 proposal 1 hash 'sha1' +set vpn ipsec ike-group test-IKE-1 key-exchange 'ikev1' +set vpn ipsec ike-group test-IKE-1 lifetime '3600' +set vpn ipsec ike-group test-IKE-1 proposal 1 dh-group '5' +set vpn ipsec ike-group test-IKE-1 proposal 1 encryption 'aes128' +set vpn ipsec ike-group test-IKE-1 proposal 1 hash 'sha1' +set vpn ipsec site-to-site peer <connection-name> authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer <connection-name> connection-type 'initiate' +set vpn ipsec site-to-site peer <connection-name> ike-group 'test-IKE-1' +set vpn ipsec site-to-site peer <connection-name> ikev2-reauth 'inherit' +set vpn ipsec site-to-site peer <connection-name> local-address <local-ip> +set vpn ipsec site-to-site peer <connection-name> tunnel 1 esp-group 'test-ESP-1' +set vpn ipsec site-to-site peer <connection-name> tunnel 1 protocol 'l2tp' +``` + +Bridge: + +``` none +set interfaces bridge br0 description 'L2 VPN Bridge' +# remote side in this example: +# set interfaces bridge br0 address '172.16.30.18/30' +set interfaces bridge br0 address '172.16.30.17/30' +set interfaces bridge br0 member interface eth0 +set interfaces ethernet eth0 description 'L2 VPN Physical port' +``` + +L2TPv3: + +``` none +set interfaces bridge br0 member interface 'l2tpeth0' +set interfaces l2tpv3 l2tpeth0 description 'L2 VPN Tunnel' +set interfaces l2tpv3 l2tpeth0 destination-port '5000' +set interfaces l2tpv3 l2tpeth0 encapsulation 'ip' +set interfaces l2tpv3 l2tpeth0 source-address <local-ip> +set interfaces l2tpv3 l2tpeth0 mtu '1500' +set interfaces l2tpv3 l2tpeth0 peer-session-id '110' +set interfaces l2tpv3 l2tpeth0 peer-tunnel-id '10' +set interfaces l2tpv3 l2tpeth0 remote <peer-ip> +set interfaces l2tpv3 l2tpeth0 session-id '110' +set interfaces l2tpv3 l2tpeth0 source-port '5000' +set interfaces l2tpv3 l2tpeth0 tunnel-id '10' +``` diff --git a/docs/configuration/interfaces/md-loopback.md b/docs/configuration/interfaces/md-loopback.md new file mode 100644 index 00000000..1d8d6766 --- /dev/null +++ b/docs/configuration/interfaces/md-loopback.md @@ -0,0 +1,97 @@ +lastproofread +2023-01-20 + +# Loopback + +The loopback networking interface is a virtual network device implemented +entirely in software. All traffic sent to it "loops back" and just targets +services on your local machine. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +There can only be one loopback `lo` interface on the system. If +you need multiple interfaces, please use the `dummy-interface` +interface type. + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +A loopback interface is always up, thus it could be used for +management traffic or as source/destination for and `IGP (Interior +Gateway Protocol)` like `routing-bgp` so your internal BGP link is not +dependent on physical link states and multiple routes can be chosen to the +destination. A `dummy-interface` Interface should always be preferred +over a `loopback-interface` interface. + +</div> + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="loopback" var1="lo"> + +/\_include/interface-address.txt + +</div> + +<div class="cmdinclude" var0="loopback" var1="lo"> + +/\_include/interface-description.txt + +</div> + +## Operation + +<div class="opcmd"> + +show interfaces loopback + +Show brief interface information. + +``` none +vyos@vyos:~$ show interfaces loopback +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +lo 127.0.0.1/8 u/u + ::1/128 +``` + +</div> + +<div class="opcmd"> + +show interfaces loopback lo + +Show detailed information on the given loopback interface <span class="title-ref">lo</span>. + +``` none +vyos@vyos:~$ show interfaces loopback lo +lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000 + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 + inet 127.0.0.1/8 scope host lo + valid_lft forever preferred_lft forever + inet6 ::1/128 scope host + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 300 6 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 300 6 0 0 0 0 +``` + +</div> diff --git a/docs/configuration/interfaces/md-macsec.md b/docs/configuration/interfaces/md-macsec.md new file mode 100644 index 00000000..17dfff1c --- /dev/null +++ b/docs/configuration/interfaces/md-macsec.md @@ -0,0 +1,332 @@ +lastproofread +2023-01-20 + +# MACsec + +MACsec is an IEEE standard (IEEE 802.1AE) for MAC security, introduced in 2006. +It defines a way to establish a protocol independent connection between two +hosts with data confidentiality, authenticity and/or integrity, using +GCM-AES-128. MACsec operates on the Ethernet layer and as such is a layer 2 +protocol, which means it's designed to secure traffic within a layer 2 network, +including DHCP or ARP requests. It does not compete with other security +solutions such as IPsec (layer 3) or TLS (layer 4), as all those solutions are +used for their own specific use cases. + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="macsec" var1="macsec0"> + +/\_include/interface-common-with-dhcp.txt + +</div> + +### MACsec options + +<div class="cfgcmd"> + +set interfaces macsec \<interface\> security cipher \<gcm-aes-128|gcm-aes-256\> + +Select cipher suite used for cryptographic operations. This setting is +mandatory. + +</div> + +<div class="cfgcmd"> + +set interfaces macsec \<interface\> security encrypt + +MACsec only provides authentication by default, encryption is optional. This +command will enable encryption for all outgoing packets. + +</div> + +<div class="cfgcmd"> + +set interfaces macsec \<interface\> source-interface \<physical-source\> + +A physical interface is required to connect this MACsec instance to. Traffic +leaving this interface will now be authenticated/encrypted. + +</div> + +#### Static Keys + +Static `SAK (Secure Authentication Key)` mode can be configured manually on each +device wishing to use MACsec. Keys must be set statically on all devices for traffic +to flow properly. Key rotation is dependent on the administrator updating all keys +manually across connected devices. Static SAK mode can not be used with MKA. + +<div class="cfgcmd"> + +set interfaces macsec \<interface\> security static key \<key\> + +Set the device's transmit (TX) key. This key must be a hex string that is 16-bytes +(GCM-AES-128) or 32-bytes (GCM-AES-256). + +</div> + +<div class="cfgcmd"> + +set interfaces macsec \<interface\> security static peer \<peer\> mac \<mac address\> + +Set the peer's MAC address + +</div> + +<div class="cfgcmd"> + +set interfaces macsec \<interface\> security static peer \<peer\> key \<key\> + +Set the peer's key used to receive (RX) traffic + +</div> + +<div class="cfgcmd"> + +set interfaces macsec \<interface\> security static peer \<peer\> disable + +Disable the peer configuration + +</div> + +#### Key Management + +`MKA (MACsec Key Agreement protocol)` is used to synchronize keys between +individual peers. + +<div class="cfgcmd"> + +set interfaces macsec \<interface\> security mka cak \<key\> + +IEEE 802.1X/MACsec pre-shared key mode. This allows configuring MACsec with +a pre-shared key using a `CAK (MACsec connectivity association key)` and +`CKN (MACsec connectivity association name)` pair. + +</div> + +<div class="cfgcmd"> + +set interfaces macsec \<interface\> security mka ckn \<key\> + +`CKN (MACsec connectivity association name)` key + +</div> + +<div class="cfgcmd"> + +set interfaces macsec \<interface\> security mka priority \<priority\> + +The peer with lower priority will become the key server and start +distributing SAKs. + +</div> + +#### Replay protection + +<div class="cfgcmd"> + +set interfaces macsec \<interface\> security replay-window \<window\> + +IEEE 802.1X/MACsec replay protection window. This determines a window in which +replay is tolerated, to allow receipt of frames that have been misordered by +the network. + +- `0`: No replay window, strict check +- `1-4294967295`: Number of packets that could be misordered + +</div> + +## Operation + +<div class="opcmd"> + +run generate macsec mka cak \<gcm-aes-128|gcm-aes-256\> + +Generate `MKA (MACsec Key Agreement protocol)` CAK key 128 or 256 bits. + +``` none +vyos@vyos:~$ generate macsec mka cak gcm-aes-128 +20693b6e08bfa482703a563898c9e3ad +``` + +</div> + +<div class="opcmd"> + +run generate macsec mka ckn + +Generate `MKA (MACsec Key Agreement protocol)` CAK key. + +``` none +vyos@vyos:~$ generate macsec mka ckn +88737efef314ee319b2cbf30210a5f164957d884672c143aefdc0f5f6bc49eb2 +``` + +</div> + +<div class="opcmd"> + +show interfaces macsec + +List all MACsec interfaces. + +``` none +vyos@vyos:~$ show interfaces macsec +17: macsec1: protect on validate strict sc off sa off encrypt on send_sci on end_station off scb off replay off + cipher suite: GCM-AES-128, using ICV length 16 + TXSC: 005056bfefaa0001 on SA 0 +20: macsec0: protect on validate strict sc off sa off encrypt off send_sci on end_station off scb off replay off + cipher suite: GCM-AES-128, using ICV length 16 + TXSC: 005056bfefaa0001 on SA 0 +``` + +</div> + +<div class="opcmd"> + +show interfaces macsec \<interface\> + +Show specific MACsec interface information + +``` none +vyos@vyos:~$ show interfaces macsec macsec1 +17: macsec1: protect on validate strict sc off sa off encrypt on send_sci on end_station off scb off replay off + cipher suite: GCM-AES-128, using ICV length 16 + TXSC: 005056bfefaa0001 on SA 0 +``` + +</div> + +## Examples + +- Two routers connected both via eth1 through an untrusted switch +- R1 has 192.0.2.1/24 & 2001:db8::1/64 +- R2 has 192.0.2.2/24 & 2001:db8::2/64 + +**R1** + +``` none +set interfaces macsec macsec1 address '192.0.2.1/24' +set interfaces macsec macsec1 address '2001:db8::1/64' +set interfaces macsec macsec1 security cipher 'gcm-aes-128' +set interfaces macsec macsec1 security encrypt +set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4' +set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836' +set interfaces macsec macsec1 source-interface 'eth1' +``` + +**R2** + +``` none +set interfaces macsec macsec1 address '192.0.2.2/24' +set interfaces macsec macsec1 address '2001:db8::2/64' +set interfaces macsec macsec1 security cipher 'gcm-aes-128' +set interfaces macsec macsec1 security encrypt +set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4' +set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836' +set interfaces macsec macsec1 source-interface 'eth1' +``` + +Pinging (IPv6) the other host and intercepting the traffic in `eth1` will +show you the content is encrypted. + +``` none +17:35:44.586668 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150: + 0x0000: 2c00 0000 000a 0050 56bf efaa 0001 d9fb ,......PV....... + 0x0010: 920a 8b8d 68ed 9609 29dd e767 25a4 4466 ....h...)..g%.Df + 0x0020: 5293 487b 9990 8517 3b15 22c7 ea5c ac83 R.H{....;."..\.. + 0x0030: 4c6e 13cf 0743 f917 2c4e 694e 87d1 0f09 Ln...C..,NiN.... + 0x0040: 0f77 5d53 ed75 cfe1 54df 0e5a c766 93cb .w]S.u..T..Z.f.. + 0x0050: c4f2 6e23 f200 6dfe 3216 c858 dcaa a73b ..n#..m.2..X...; + 0x0060: 4dd1 9358 d9e4 ed0e 072f 1acc 31c4 f669 M..X...../..1..i + 0x0070: e93a 9f38 8a62 17c6 2857 6ac5 ec11 8b0e .:.8.b..(Wj..... + 0x0080: 6b30 92a5 7ccc 720b k0..|.r. +``` + +Disabling the encryption on the link by removing `security encrypt` will show +the unencrypted but authenticated content. + +``` none +17:37:00.746155 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150: + 0x0000: 2000 0000 0009 0050 56bf efaa 0001 86dd .......PV....... + 0x0010: 6009 86f3 0040 3a40 2001 0db8 0000 0000 `....@:@........ + 0x0020: 0000 0000 0000 0001 2001 0db8 0000 0000 ................ + 0x0030: 0000 0000 0000 0002 8100 d977 0f30 0003 ...........w.0.. + 0x0040: 1ca0 c65e 0000 0000 8d93 0b00 0000 0000 ...^............ + 0x0050: 1011 1213 1415 1617 1819 1a1b 1c1d 1e1f ................ + 0x0060: 2021 2223 2425 2627 2829 2a2b 2c2d 2e2f .!"#$%&'()*+,-./ + 0x0070: 3031 3233 3435 3637 87d5 eed3 3a39 d52b 01234567....:9.+ + 0x0080: a282 c842 5254 ef28 ...BRT.( +``` + +**R1 Static Key** + +``` none +set interfaces macsec macsec1 address '192.0.2.1/24' +set interfaces macsec macsec1 address '2001:db8::1/64' +set interfaces macsec macsec1 security cipher 'gcm-aes-128' +set interfaces macsec macsec1 security encrypt +set interfaces macsec macsec1 security static key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' +set interfaces macsec macsec1 security static peer R2 mac 00:11:22:33:44:02 +set interfaces macsec macsec1 security static peer R2 key 'eadcc0aa9cf203f3ce651b332bd6e6c7' +set interfaces macsec macsec1 source-interface 'eth1' +``` + +**R2 Static Key** + +``` none +set interfaces macsec macsec1 address '192.0.2.2/24' +set interfaces macsec macsec1 address '2001:db8::2/64' +set interfaces macsec macsec1 security cipher 'gcm-aes-128' +set interfaces macsec macsec1 security encrypt +set interfaces macsec macsec1 security static key 'eadcc0aa9cf203f3ce651b332bd6e6c7' +set interfaces macsec macsec1 security static peer R2 mac 00:11:22:33:44:01 +set interfaces macsec macsec1 security static peer R2 key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' +set interfaces macsec macsec1 source-interface 'eth1' +``` + +## MACsec over wan + +MACsec is an interesting alternative to existing tunneling solutions that +protects layer 2 by performing integrity, origin authentication, and optionally +encryption. The typical use case is to use MACsec between hosts and access +switches, between two hosts, or between two switches. in this example below, +we use VXLAN and MACsec to secure the tunnel. + +**R1 MACsec01** + +``` none +set interfaces macsec macsec1 address '192.0.2.1/24' +set interfaces macsec macsec1 address '2001:db8::1/64' +set interfaces macsec macsec1 security cipher 'gcm-aes-128' +set interfaces macsec macsec1 security encrypt +set interfaces macsec macsec1 security static key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' +set interfaces macsec macsec1 security static peer SEC02 key 'eadcc0aa9cf203f3ce651b332bd6e6c7' +set interfaces macsec macsec1 security static peer SEC02 mac '00:11:22:33:44:02' +set interfaces macsec macsec1 source-interface 'vxlan1' +set interfaces vxlan vxlan1 mac '00:11:22:33:44:01' +set interfaces vxlan vxlan1 remote '10.1.3.3' +set interfaces vxlan vxlan1 source-address '172.16.100.1' +set interfaces vxlan vxlan1 vni '10' +set protocols static route 10.1.3.3/32 next-hop 172.16.100.2 +``` + +**R2 MACsec02** + +``` none +set interfaces macsec macsec1 address '192.0.2.2/24' +set interfaces macsec macsec1 address '2001:db8::2/64' +set interfaces macsec macsec1 security cipher 'gcm-aes-128' +set interfaces macsec macsec1 security encrypt +set interfaces macsec macsec1 security static key 'eadcc0aa9cf203f3ce651b332bd6e6c7' +set interfaces macsec macsec1 security static peer SEC01 key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' +set interfaces macsec macsec1 security static peer SEC01 mac '00:11:22:33:44:01' +set interfaces macsec macsec1 source-interface 'vxlan1' +set interfaces vxlan vxlan1 mac '00:11:22:33:44:02' +set interfaces vxlan vxlan1 remote '10.1.2.2' +set interfaces vxlan vxlan1 source-address '172.16.100.2' +set interfaces vxlan vxlan1 vni '10' +set protocols static route 10.1.2.2/32 next-hop 172.16.100.1 +``` diff --git a/docs/configuration/interfaces/md-openvpn.md b/docs/configuration/interfaces/md-openvpn.md new file mode 100644 index 00000000..b9df5971 --- /dev/null +++ b/docs/configuration/interfaces/md-openvpn.md @@ -0,0 +1,924 @@ +lastproofread +2021-07-05 + +# OpenVPN + +Traditionally hardware routers implement IPsec exclusively due to relative +ease of implementing it in hardware and insufficient CPU power for doing +encryption in software. Since VyOS is a software router, this is less of a +concern. OpenVPN has been widely used on UNIX platform for a long time and is +a popular option for remote access VPN, though it's also capable of +site-to-site connections. + +Advantages of OpenVPN are: + +- It uses a single TCP or UDP connection and does not rely on packet source + addresses, so it will work even through a double NAT: perfect for public + hotspots and such +- It's easy to setup and offers very flexible split tunneling +- There's a variety of client GUI frontends for any platform + +Disadvantages are: + +- It's slower than IPsec due to higher protocol overhead and the fact it runs + in user mode while IPsec, on Linux, is in kernel mode +- None of the operating systems have client software installed by default + +In the VyOS CLI, a key point often overlooked is that rather than being +configured using the <span class="title-ref">set vpn</span> stanza, OpenVPN is configured as a network +interface using <span class="title-ref">set interfaces openvpn</span>. + +## Site-to-Site + +<figure> +<img src="/_static/images/openvpn_site2site_diagram.webp" /> +</figure> + +OpenVPN is popular for client-server setups, but its site-to-site mode +remains a relatively obscure feature, and many router appliances +still don't support it. However, it's very useful for quickly setting up +tunnels between routers. + +As of VyOS 1.4, OpenVPN site-to-site mode can use either pre-shared keys or x.509 certificates. + +The pre-shared key mode is deprecated and will be removed from future OpenVPN versions, +so VyOS will have to remove support for that option as well. The reason is that using pre-shared keys +is significantly less secure than using TLS. + +We'll configure OpenVPN using self-signed certificates, and then discuss the legacy +pre-shared key mode. + +In both cases, we will use the following settings: + +- The public IP address of the local side of the VPN will be 198.51.100.10. +- The public IP address of the remote side of the VPN will be 203.0.113.11. +- The tunnel will use 10.255.1.1 for the local IP and 10.255.1.2 for the remote. +- The local site will have a subnet of 10.0.0.0/16. +- The remote site will have a subnet of 10.1.0.0/16. +- The official port for OpenVPN is 1194, which we reserve for client VPN; we + will use 1195 for site-to-site VPN. +- The `persistent-tunnel` directive will allow us to configure tunnel-related + attributes, such as firewall policy as we would on any normal network + interface. +- If known, the IP of the remote router can be configured using the + `remote-host` directive; if unknown, it can be omitted. We will assume a + dynamic IP for our remote router. + +### Setting up certificates + +Setting up a full-blown PKI with a CA certificate would arguably defeat the purpose +of site-to-site OpenVPN, since its main goal is supposed to be configuration simplicity, +compared to server setups that need to support multiple clients. + +However, since VyOS 1.4, it is possible to verify self-signed certificates using +certificate fingerprints. + +On both sides, you need to generate a self-signed certificate, preferrably using the "ec" (elliptic curve) type. +You can generate them by executing command `run generate pki certificate self-signed install <name>` in the configuration mode. +Once the command is complete, it will add the certificate to the configuration session, to the `pki` subtree. +You can then review the proposed changes and commit them. + +``` none +vyos@vyos# run generate pki certificate self-signed install openvpn-local +Enter private key type: [rsa, dsa, ec] (Default: rsa) ec +Enter private key bits: (Default: 256) +Enter country code: (Default: GB) +Enter state: (Default: Some-State) +Enter locality: (Default: Some-City) +Enter organization name: (Default: VyOS) +Enter common name: (Default: vyos.io) +Do you want to configure Subject Alternative Names? [y/N] +Enter how many days certificate will be valid: (Default: 365) +Enter certificate type: (client, server) (Default: server) +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +[edit] + +vyos@vyos# compare +[pki] ++ certificate openvpn-local { ++ certificate "MIICJTCCAcugAwIBAgIUMXLfRNJ5iOjk/ uAZqUe4phW8MdgwCgYIKoZIzj0EAwIwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA5MDcyMTQzMTNaFw0yNDA5MDYyMTQzMTNaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxEDAOBgNVBAMMB3Z5b3MuaW8wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASp7D0vE3SKSAWAzr/lw9Eq9Q89r247AJR6ec/GT26AIcVA1bsongV1YaWvRwzTPC/yi5pkzV/PcT/WU7JQIyMWo3UwczAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDATAdBgNVHQ4EFgQUBrAxRdFppdG/UBRdo7qNyHutaTQwHwYDVR0jBBgwFoAUBrAxRdFppdG/UBRdo7qNyHutaTQwCgYIKoZIzj0EAwIDSAAwRQIhAI2+8C92z9wTcTWkQ/goRxs10EBC+h78O+vgo9k97z5iAiBSeqfaVr5taQTS31+McGTAK3cYWNTg0DlOBI8aKO2oRg==" ++ private { ++ key "MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgtOeEb0dMb5P/2Exi09WWvk6Cvz0oOBoDuP68ZimS2LShRANCAASp7D0vE3SKSAWAzr/lw9Eq9Q89r247AJR6ec/GT26AIcVA1bsongV1YaWvRwzTPC/yi5pkzV/PcT/WU7JQIyMW" ++ } ++ } + +[edit] + +vyos@vyos# commit +``` + +You do **not** need to copy the certificate to the other router. Instead, you need to retrieve its SHA-256 fingerprint. +OpenVPN only supports SHA-256 fingerprints at the moment, so you need to use the following command: + +``` none +vyos@vyos# run show pki certificate openvpn-local fingerprint sha256 +5C:B8:09:64:8B:59:51:DC:F4:DF:2C:12:5C:B7:03:D1:68:94:D7:5B:62:C2:E1:83:79:F1:F0:68:B2:81:26:79 +``` + +Note: certificate names don't matter, we use 'openvpn-local' and 'openvpn-remote' but they can be arbitrary. + +Repeat the procedure on the other router. + +### Setting up OpenVPN + +Local Configuration: + +``` none +Configure the tunnel: + +set interfaces openvpn vtun1 mode site-to-site +set interfaces openvpn vtun1 protocol udp +set interfaces openvpn vtun1 persistent-tunnel +set interfaces openvpn vtun1 remote-host '203.0.113.11' # Public IP of the other side +set interfaces openvpn vtun1 local-port '1195' +set interfaces openvpn vtun1 remote-port '1195' +set interfaces openvpn vtun1 local-address '10.255.1.1' # Local IP of vtun interface +set interfaces openvpn vtun1 remote-address '10.255.1.2' # Remote IP of vtun interface +set interfaces openvpn vtun1 tls certificate 'openvpn-local' # The self-signed certificate +set interfaces openvpn vtun1 tls peer-fingerprint <remote cert fingerprint> # The output of 'run show pki certificate <name> fingerprint sha256 + on the remote rout +``` + +Remote Configuration: + +``` none +set interfaces openvpn vtun1 mode site-to-site +set interfaces openvpn vtun1 protocol udp +set interfaces openvpn vtun1 persistent-tunnel +set interfaces openvpn vtun1 remote-host '198.51.100.10' # Pub IP of other site +set interfaces openvpn vtun1 local-port '1195' +set interfaces openvpn vtun1 remote-port '1195' +set interfaces openvpn vtun1 local-address '10.255.1.2' # Local IP of vtun interface +set interfaces openvpn vtun1 remote-address '10.255.1.1' # Remote IP of vtun interface +set interfaces openvpn vtun1 tls certificate 'openvpn-remote' # The self-signed certificate +set interfaces openvpn vtun1 tls peer-fingerprint <local cert fingerprint> # The output of 'run show pki certificate <name> fingerprint sha256 + on the local router +``` + +### Pre-shared keys + +Until VyOS 1.4, the only option for site-to-site OpenVPN without PKI was to use pre-shared keys. +That option is still available but it is deprecated and will be removed in the future. +However, if you need to set up a tunnel to an older VyOS version or a system with older OpenVPN, +you need to still need to know how to use it. + +First, you need to generate a key by running `run generate pki openvpn shared-secret install <name>` from configuration mode. +You can use any name, we will use `s2s`. + +``` none +vyos@local# run generate pki openvpn shared-secret install s2s +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +[edit] +vyos@local# compare +[pki openvpn shared-secret] ++ s2s { ++ key "7c73046a9da91e874d31c7ad894a32688cda054bde157c64270f28eceebc0bb2f44dbb70335fad45148b0456aaa78cb34a34c0958eeed4f75e75fd99ff519ef940f7029a316c436d2366a2b0fb8ea1d1c792a65f67d10a461af83ef4530adc25d1c872de6d9c7d5f338223d1f3b66dc3311bbbddc0e05228c47b91c817c721aadc7ed18f0662df52ad14f898904372679e3d9697d062b0869d12de47ceb2e626fa12e1926a3119be37dd29c9b0ad81997230f4038926900d5edb78522d2940cfe207f8e2b948e0d459fa137ebb18064ac5982b28dd1899020b4f2b082a20d5d4eb65710fbb1e62b5e061df39620267eab429d3eedd9a1ae85957457c8e4655f3" ++ version "1" ++ } + +[edit] + +vyos@local# commit +[edit] +``` + +Then you need to install the key on the remote router: + +``` none +vyos@remote# set pki openvpn shared-secret s2s key <generated key string> +``` + +Then you need to set the key in your OpenVPN interface settings: + +``` none +set interfaces openvpn vtun1 shared-secret-key s2s +``` + +### Firewall Exceptions + +For the OpenVPN traffic to pass through the WAN interface, you must create a +firewall exception. + +``` none +set firewall name OUTSIDE_LOCAL rule 10 action accept +set firewall name OUTSIDE_LOCAL rule 10 description 'Allow established/related' +set firewall name OUTSIDE_LOCAL rule 10 state established enable +set firewall name OUTSIDE_LOCAL rule 10 state related enable +set firewall name OUTSIDE_LOCAL rule 20 action accept +set firewall name OUTSIDE_LOCAL rule 20 description OpenVPN_IN +set firewall name OUTSIDE_LOCAL rule 20 destination port 1195 +set firewall name OUTSIDE_LOCAL rule 20 log enable +set firewall name OUTSIDE_LOCAL rule 20 protocol udp +set firewall name OUTSIDE_LOCAL rule 20 source +``` + +You should also ensure that the OUTISDE_LOCAL firewall group is applied to the +WAN interface and a direction (local). + +``` none +set firewall interface eth0 local name 'OUTSIDE-LOCAL' +``` + +Static Routing: + +Static routes can be configured referencing the tunnel interface; for example, +the local router will use a network of 10.0.0.0/16, while the remote has a +network of 10.1.0.0/16: + +Local Configuration: + +``` none +set protocols static route 10.1.0.0/16 interface vtun1 +``` + +Remote Configuration: + +``` none +set protocols static route 10.0.0.0/16 interface vtun1 +``` + +The configurations above will default to using 256-bit AES in GCM mode +for encryption (if both sides support NCP) and SHA-1 for HMAC authentication. +SHA-1 is considered weak, but other hashing algorithms are available, as are +encryption algorithms: + +For Encryption: + +This sets the cipher when NCP (Negotiable Crypto Parameters) is disabled or +OpenVPN version \< 2.4.0. + +``` none +vyos@vyos# set interfaces openvpn vtun1 encryption cipher +Possible completions: + des DES algorithm + 3des DES algorithm with triple encryption + bf128 Blowfish algorithm with 128-bit key + bf256 Blowfish algorithm with 256-bit key + aes128 AES algorithm with 128-bit key CBC + aes128gcm AES algorithm with 128-bit key GCM + aes192 AES algorithm with 192-bit key CBC + aes192gcm AES algorithm with 192-bit key GCM + aes256 AES algorithm with 256-bit key CBC + aes256gcm AES algorithm with 256-bit key GCM +``` + +This sets the accepted ciphers to use when version =\> 2.4.0 and NCP is +enabled (which is the default). Default NCP cipher for versions \>= 2.4.0 is +aes256gcm. The first cipher in this list is what server pushes to clients. + +``` none +vyos@vyos# set int open vtun0 encryption ncp-ciphers +Possible completions: + des DES algorithm + 3des DES algorithm with triple encryption + aes128 AES algorithm with 128-bit key CBC + aes128gcm AES algorithm with 128-bit key GCM + aes192 AES algorithm with 192-bit key CBC + aes192gcm AES algorithm with 192-bit key GCM + aes256 AES algorithm with 256-bit key CBC + aes256gcm AES algorithm with 256-bit key GCM +``` + +For Hashing: + +``` none +vyos@vyos# set interfaces openvpn vtun1 hash +Possible completions: + md5 MD5 algorithm + sha1 SHA-1 algorithm + sha256 SHA-256 algorithm + sha512 SHA-512 algorithm +``` + +If you change the default encryption and hashing algorithms, be sure that the +local and remote ends have matching configurations, otherwise the tunnel will +not come up. + +Firewall policy can also be applied to the tunnel interface for <span class="title-ref">local</span>, <span class="title-ref">in</span>, +and <span class="title-ref">out</span> directions and functions identically to ethernet interfaces. + +If making use of multiple tunnels, OpenVPN must have a way to distinguish +between different tunnels aside from the pre-shared-key. This is either by +referencing IP address or port number. One option is to dedicate a public IP +to each tunnel. Another option is to dedicate a port number to each tunnel +(e.g. 1195,1196,1197...). + +OpenVPN status can be verified using the <span class="title-ref">show openvpn</span> operational commands. +See the built-in help for a complete list of options. + +## Server + +Multi-client server is the most popular OpenVPN mode on routers. It always uses +x.509 authentication and therefore requires a PKI setup. Refer this topic +`configuration/pki/index:pki` to generate a CA certificate, +a server certificate and key, a certificate revocation list, a Diffie-Hellman +key exchange parameters file. You do not need client certificates and keys for +the server setup. + +In this example we will use the most complicated case: a setup where each +client is a router that has its own subnet (think HQ and branch offices), since +simpler setups are subsets of it. + +Suppose you want to use 10.23.1.0/24 network for client tunnel endpoints and +all client subnets belong to 10.23.0.0/20. All clients need access to the +192.168.0.0/16 network. + +First we need to specify the basic settings. 1194/UDP is the default. The +`persistent-tunnel` option is recommended, it prevents the TUN/TAP device from +closing on connection resets or daemon reloads. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Using **openvpn-option -reneg-sec** can be tricky. This option is +used to renegotiate data channel after n seconds. When used at both server +and client, the lower value will trigger the renegotiation. If you set it to +0 on one side of the connection (to disable it), the chosen value on the +other side will determine when the renegotiation will occur. + +</div> + +``` none +set interfaces openvpn vtun10 mode server +set interfaces openvpn vtun10 local-port 1194 +set interfaces openvpn vtun10 persistent-tunnel +set interfaces openvpn vtun10 protocol udp +``` + +Then we need to generate, add and specify the names of the cryptographic materials. +Each of the install command should be applied to the configuration and commited +before using under the openvpn interface configuration. + +``` none +run generate pki ca install ca-1 # Follow the instructions to generate CA cert. +Configure mode commands to install: +set pki ca ca-1 certificate 'generated_cert_string' +set pki ca ca-1 private key 'generated_private_key' + +run generate pki certificate sign ca-1 install srv-1 # Follow the instructions to generate server cert. +Configure mode commands to install: +set pki certificate srv-1 certificate 'generated_server_cert' +set pki certificate srv-1 private key 'generated_private_key' + +run generate pki dh install dh-1 # Follow the instructions to generate set of + Diffie-Hellman parameters. +Generating parameters... +Configure mode commands to install DH parameters: +set pki dh dh-1 parameters 'generated_dh_params_set' + +set interfaces openvpn vtun10 tls ca-certificate ca-1 +set interfaces openvpn vtun10 tls certificate srv-1 +set interfaces openvpn vtun10 tls dh-params dh-1 +``` + +Now we need to specify the server network settings. In all cases we need to +specify the subnet for client tunnel endpoints. Since we want clients to access +a specific network behind our router, we will use a push-route option for +installing that route on clients. + +``` none +set interfaces openvpn vtun10 server push-route 192.168.0.0/16 +set interfaces openvpn vtun10 server subnet 10.23.1.0/24 +``` + +Since it's a HQ and branch offices setup, we will want all clients to have +fixed addresses and we will route traffic to specific subnets through them. We +need configuration for each client to achieve this. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Clients are identified by the CN field of their x.509 certificates, +in this example the CN is `client0`: + +</div> + +``` none +set interfaces openvpn vtun10 server client client0 ip 10.23.1.10 +set interfaces openvpn vtun10 server client client0 subnet 10.23.2.0/25 +``` + +OpenVPN **will not** automatically create routes in the kernel for client +subnets when they connect and will only use client-subnet association +internally, so we need to create a route to the 10.23.0.0/20 network ourselves: + +``` none +set protocols static route 10.23.0.0/20 interface vtun10 +``` + +Additionally, each client needs a copy of ca cert and its own client key and +cert files. The files are plaintext so they may be copied either manually from the CLI. +Client key and cert files should be signed with the proper ca cert and generated on the +server side. + +HQ's router requires the following steps to generate crypto materials for the Branch 1: + +``` none +run generate pki certificate sign ca-1 install branch-1 # Follow the instructions to generate client + cert for Branch 1 +Configure mode commands to install: +``` + +Branch 1's router might have the following lines: + +``` none +set pki ca ca-1 certificate 'generated_cert_string' # CA cert generated on HQ router +set pki certificate branch-1 certificate 'generated_branch_cert' # Client cert generated and signed on HQ router +set pki certificate branch-1 private key 'generated_private_key' # Client cert key generated on HQ router + +set interfaces openvpn vtun10 tls ca-cert ca-1 +set interfaces openvpn vtun10 tls certificate branch-1 +``` + +### Client Authentication + +#### LDAP + +Enterprise installations usually ship a kind of directory service which is used +to have a single password store for all employees. VyOS and OpenVPN support +using LDAP/AD as single user backend. + +Authentication is done by using the `openvpn-auth-ldap.so` plugin which is +shipped with every VyOS installation. A dedicated configuration file is +required. It is best practise to store it in `/config` to survive image +updates + +``` none +set interfaces openvpn vtun0 openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" +``` + +The required config file may look like this: + +``` none +<LDAP> +# LDAP server URL +URL ldap://ldap.example.com +# Bind DN (If your LDAP server doesn't support anonymous binds) +BindDN cn=LDAPUser,dc=example,dc=com +# Bind Password password +Password S3cr3t +# Network timeout (in seconds) +Timeout 15 +</LDAP> + +<Authorization> +# Base DN +BaseDN "ou=people,dc=example,dc=com" +# User Search Filter +SearchFilter "(&(uid=%u)(objectClass=shadowAccount))" +# Require Group Membership - allow all users +RequireGroup false +</Authorization> +``` + +##### Active Directory + +Despite the fact that AD is a superset of LDAP + +``` none +<LDAP> + # LDAP server URL + URL ldap://dc01.example.com + # Bind DN (If your LDAP server doesn’t support anonymous binds) + BindDN CN=LDAPUser,DC=example,DC=com + # Bind Password + Password mysecretpassword + # Network timeout (in seconds) + Timeout 15 + # Enable Start TLS + TLSEnable no + # Follow LDAP Referrals (anonymously) + FollowReferrals no +</LDAP> + +<Authorization> + # Base DN + BaseDN "DC=example,DC=com" + # User Search Filter, user must be a member of the VPN AD group + SearchFilter "(&(sAMAccountName=%u)(memberOf=CN=VPN,OU=Groups,DC=example,DC=com))" + # Require Group Membership + RequireGroup false # already handled by SearchFilter + <Group> + BaseDN "OU=Groups,DC=example,DC=com" + SearchFilter "(|(cn=VPN))" + MemberAttribute memberOf + </Group> +</Authorization> +``` + +If you only want to check if the user account is enabled and can authenticate +(against the primary group) the following snipped is sufficient: + +``` none +<LDAP> + URL ldap://dc01.example.com + BindDN CN=SA_OPENVPN,OU=ServiceAccounts,DC=example,DC=com + Password ThisIsTopSecret + Timeout 15 + TLSEnable no + FollowReferrals no +</LDAP> + +<Authorization> + BaseDN "DC=example,DC=com" + SearchFilter "sAMAccountName=%u" + RequireGroup false +</Authorization> +``` + +A complete LDAP auth OpenVPN configuration could look like the following +example: + +``` none +vyos@vyos# show interfaces openvpn + openvpn vtun0 { + mode server + openvpn-option "--tun-mtu 1500 --fragment 1300 --mssfix" + openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" + openvpn-option "--push redirect-gateway" + openvpn-option --duplicate-cn + openvpn-option "--verify-client-cert none" + openvpn-option --comp-lzo + openvpn-option --persist-key + openvpn-option --persist-tun + server { + domain-name example.com + max-connections 5 + name-server 203.0.113.0.10 + name-server 198.51.100.3 + subnet 172.18.100.128/29 + } + tls { + ca-certificate ca.crt + certificate server.crt + dh-params dh1024.pem + } + } +``` + +## Client + +VyOS can not only act as an OpenVPN site-to-site or server for multiple clients. +You can indeed also configure any VyOS OpenVPN interface as an OpenVPN client +connecting to a VyOS OpenVPN server or any other OpenVPN server. + +Given the following example we have one VyOS router acting as OpenVPN server +and another VyOS router acting as OpenVPN client. The server also pushes a +static client IP address to the OpenVPN client. Remember, clients are identified +using their CN attribute in the SSL certificate. + +### Configuration + +#### Server Side + +``` none +set interfaces openvpn vtun10 encryption cipher 'aes256' +set interfaces openvpn vtun10 hash 'sha512' +set interfaces openvpn vtun10 local-host '172.18.201.10' +set interfaces openvpn vtun10 local-port '1194' +set interfaces openvpn vtun10 mode 'server' +set interfaces openvpn vtun10 persistent-tunnel +set interfaces openvpn vtun10 protocol 'udp' +set interfaces openvpn vtun10 server client client1 ip '10.10.0.10' +set interfaces openvpn vtun10 server domain-name 'vyos.net' +set interfaces openvpn vtun10 server max-connections '250' +set interfaces openvpn vtun10 server name-server '172.16.254.30' +set interfaces openvpn vtun10 server subnet '10.10.0.0/24' +set interfaces openvpn vtun10 server topology 'subnet' +set interfaces openvpn vtun10 tls ca-cert ca-1 +set interfaces openvpn vtun10 tls certificate srv-1 +set interfaces openvpn vtun10 tls crypt-key srv-1 +set interfaces openvpn vtun10 tls dh-params dh-1 +set interfaces openvpn vtun10 use-lzo-compression +``` + +#### Client Side + +``` none +set interfaces openvpn vtun10 encryption cipher 'aes256' +set interfaces openvpn vtun10 hash 'sha512' +set interfaces openvpn vtun10 mode 'client' +set interfaces openvpn vtun10 persistent-tunnel +set interfaces openvpn vtun10 protocol 'udp' +set interfaces openvpn vtun10 remote-host '172.18.201.10' +set interfaces openvpn vtun10 remote-port '1194' +set interfaces openvpn vtun10 tls ca-cert ca-1 +set interfaces openvpn vtun10 tls certificate client-1 +set interfaces openvpn vtun10 tls crypt-key client-1 +set interfaces openvpn vtun10 use-lzo-compression +``` + +### Options + +We do not have CLI nodes for every single OpenVPN option. If an option is +missing, a feature request should be opened at [Phabricator]() so all users can +benefit from it (see `issues_features`). + +If you are a hacker or want to try on your own we support passing raw OpenVPN +options to OpenVPN. + +<div class="cfgcmd"> + +set interfaces openvpn vtun10 openvpn-option 'persistent-key' + +</div> + +Will add `persistent-key` at the end of the generated OpenVPN configuration. +Please use this only as last resort - things might break and OpenVPN won't start +if you pass invalid options/syntax. + +<div class="cfgcmd"> + +set interfaces openvpn vtun10 openvpn-option +'push \"keepalive 1 10\"' + +</div> + +Will add `push "keepalive 1 10"` to the generated OpenVPN config file. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Sometimes option lines in the generated OpenVPN configuration require +quotes. This is done through a hack on our config generator. You can pass +quotes using the `"` statement. + +</div> + +### Server bridge + +In Ethernet bridging configurations, OpenVPN's server mode can be set as a +'bridge' where the VPN tunnel encapsulates entire Ethernet frames +(up to 1514 bytes) instead of just IP packets (up to 1500 bytes). This setup +allows clients to transmit Layer 2 frames through the OpenVPN tunnel. Below, +we outline a basic configuration to achieve this: + +Server Side: + +``` none +set interfaces bridge br10 member interface eth1.10 +set interfaces bridge br10 member interface vtun10 +set interfaces openvpn vtun10 device-type 'tap' +set interfaces openvpn vtun10 encryption data-ciphers 'aes192' +set interfaces openvpn vtun10 hash 'sha256'' +set interfaces openvpn vtun10 local-host '172.18.201.10' +set interfaces openvpn vtun10 local-port '1194' +set interfaces openvpn vtun10 mode 'server' +set interfaces openvpn vtun10 server bridge gateway '10.10.0.1' +set interfaces openvpn vtun10 server bridge start '10.10.0.100' +set interfaces openvpn vtun10 server bridge stop '10.10.0.200' +set interfaces openvpn vtun10 server bridge subnet-mask '255.255.255.0' +set interfaces openvpn vtun10 server topology 'subnet' +set interfaces openvpn vtun10 tls ca-certificate 'ca-1' +set interfaces openvpn vtun10 tls certificate 'srv-1' +set interfaces openvpn vtun10 tls dh-params 'srv-1' +``` + +Client Side : + +``` none +set interfaces openvpn vtun10 device-type 'tap' +set interfaces openvpn vtun10 encryption data-ciphers 'aes192' +set interfaces openvpn vtun10 hash 'sha256'' +set interfaces openvpn vtun10 mode 'client' +set interfaces openvpn vtun10 protocol 'udp' +set interfaces openvpn vtun10 remote-host '172.18.201.10' +set interfaces openvpn vtun10 remote-port '1194' +set interfaces openvpn vtun10 tls ca-certificate 'ca-1' +set interfaces openvpn vtun10 tls certificate 'client-1' +``` + +## Multi-factor Authentication + +VyOS supports multi-factor authentication (MFA) or two-factor authentication +using Time-based One-Time Password (TOTP). Compatible with Google Authenticator +software token, other software tokens. + +### MFA TOTP options + +<div class="cfgcmd"> + +set interfaces openvpn \<interface\> server mfa totp challenge \<enable | disable\> + +If set to enable, openvpn-otp will expect password as result of challenge/ +response protocol. + +</div> + +<div class="cfgcmd"> + +set interfaces openvpn \<interface\> server mfa totp digits \<1-65535\> + +Configure number of digits to use for totp hash (default: 6) + +</div> + +<div class="cfgcmd"> + +set interfaces openvpn \<interface\> server mfa totp drift \<1-65535\> + +Configure time drift in seconds (default: 0) + +</div> + +<div class="cfgcmd"> + +set interfaces openvpn \<interface\> server mfa totp slop \<1-65535\> + +Configure maximum allowed clock slop in seconds (default: 180) + +</div> + +<div class="cfgcmd"> + +set interfaces openvpn \<interface\> server mfa totp step \<1-65535\> + +Configure step value for totp in seconds (default: 30) + +</div> + +### Example + +``` none +set interfaces openvpn vtun20 encryption cipher 'aes256' +set interfaces openvpn vtun20 hash 'sha512' +set interfaces openvpn vtun20 mode 'server' +set interfaces openvpn vtun20 persistent-tunnel +set interfaces openvpn vtun20 server client user1 +set interfaces openvpn vtun20 server mfa totp challenge 'disable' +set interfaces openvpn vtun20 server subnet '10.10.2.0/24' +set interfaces openvpn vtun20 server topology 'subnet' +set interfaces openvpn vtun20 tls ca-certificate 'openvpn_vtun20' +set interfaces openvpn vtun20 tls certificate 'openvpn_vtun20' +set interfaces openvpn vtun20 tls dh-params 'dh-pem' +``` + +For every client in the openvpn server configuration a totp secret is created. +To display the authentication information, use the command: + +<div class="cfgcmd"> + +show interfaces openvpn \<interface\> user \<username\> mfa \<qrcode[|secret|](##SUBST##|secret|)uri\> + +</div> + +An example: + +``` none +vyos@vyos:~$ sh interfaces openvpn vtun20 user user1 mfa qrcode +█████████████████████████████████████ +█████████████████████████████████████ +████ ▄▄▄▄▄ █▀▄▀ ▀▀▄▀ ▀▀▄ █ ▄▄▄▄▄ ████ +████ █ █ █▀▀▄ █▀▀▀█▀██ █ █ █ ████ +████ █▄▄▄█ █▀█ ▄ █▀▀ █▄▄▄█ █▄▄▄█ ████ +████▄▄▄▄▄▄▄█▄█ █ █ ▀ █▄▀▄█▄▄▄▄▄▄▄████ +████▄▄ ▄ █▄▄ ▄▀▄█▄ ▄▀▄█ ▄▄▀ ▀▄█ ▀████ +████ ▀██▄▄▄█▄ ██ █▄▄▄▄ █▄▀█ █ █▀█████ +████ ▄█▀▀▄▄ ▄█▀ ▀▄ ▄▄▀▄█▀▀▀ ▄▄▀████ +████▄█ ▀▄▄▄▀ ▀ ▄█ ▄ █▄█▀ █▀ █▀█████ +████▀█▀ ▀ ▄█▀▄▀▀█▄██▄█▀▀ ▀ ▀ ▄█▀████ +████ ██▄▄▀▄▄█ ██ ▀█ ▄█ ▀▄█ █▀██▀████ +████▄███▄█▄█ ▀█▄ ██▄▄▄█▀ ▄▄▄ █ ▀ ████ +████ ▄▄▄▄▄ █▄█▀▄ ▀▄ ▀█▀ █▄█ ██▀█████ +████ █ █ █ ▄█▀█▀▀▄ ▄▀▀▄▄▄▄▄▄ ████ +████ █▄▄▄█ █ ▄ ▀ █▄▄▄██▄▀█▄▀▄█▄ █████ +████▄▄▄▄▄▄▄█▄██▄█▄▄▄▄▄█▄█▄█▄██▄██████ +█████████████████████████████████████ +█████████████████████████████████████ +``` + +Use the QR code to add the user account in Google authenticator application and +on client side, use the OTP number as password. + +## OpenVPN Data Channel Offload (DCO) + +OpenVPN Data Channel Offload (DCO) enables significant performance enhancement +in encrypted OpenVPN data processing. By minimizing context switching for each +packet, DCO effectively reduces overhead. This optimization is achieved by +keeping most data handling tasks within the kernel, avoiding frequent switches +between kernel and user space for encryption and packet handling. + +As a result, the processing of each packet becomes more efficient, potentially +leveraging hardware encryption offloading support available in the kernel. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +OpenVPN DCO is not full OpenVPN features supported , is currently +considered experimental. Furthermore, there are certain OpenVPN features and +use cases that remain incompatible with DCO. To get a comprehensive +understanding of the limitations associated with DCO, refer to the list of +known limitations in the documentation. + +<https://community.openvpn.net/openvpn/wiki/DataChannelOffload/Features> + +</div> + +### Enabling OpenVPN DCO + +DCO support is a per-tunnel option and it is not automatically enabled by +default for new or upgraded tunnels. Existing tunnels will continue to function +as they have in the past. + +DCO can be enabled for both new and existing tunnels,VyOS adds an option in each +tunnel configuration where we can enable this function .The current best +practice is to create a new tunnel with DCO to minimize the chance of problems +with existing clients. + +<div class="cfgcmd"> + +set interfaces openvpn \<name\> offload dco + +Enable OpenVPN Data Channel Offload feature by loading the appropriate kernel +module. + +Disabled by default - no kernel module loaded. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Enable this feature causes an interface reset. + +</div> + +</div> + +### Troubleshooting + +VyOS provides some operational commands on OpenVPN. + +#### Check status + +The following commands let you check tunnel status. + +<div class="opcmd"> + +show openvpn client + +Use this command to check the tunnel status for OpenVPN client interfaces. + +</div> + +<div class="opcmd"> + +show openvpn server + +Use this command to check the tunnel status for OpenVPN server interfaces. + +</div> + +<div class="opcmd"> + +show openvpn site-to-site + +Use this command to check the tunnel status for OpenVPN site-to-site +interfaces. + +</div> + +#### Reset OpenVPN + +The following commands let you reset OpenVPN. + +<div class="opcmd"> + +reset openvpn client \<text\> + +Use this command to reset the specified OpenVPN client. + +</div> + +<div class="opcmd"> + +reset openvpn interface \<interface\> + +Use this command to reset the OpenVPN process on a specific interface. + +</div> diff --git a/docs/configuration/interfaces/md-pppoe.md b/docs/configuration/interfaces/md-pppoe.md new file mode 100644 index 00000000..f228aab2 --- /dev/null +++ b/docs/configuration/interfaces/md-pppoe.md @@ -0,0 +1,562 @@ +lastproofread +2022-07-27 + +# PPPoE + +`PPPoE (Point-to-Point Protocol over Ethernet)` is a network protocol +for encapsulating PPP frames inside Ethernet frames. It appeared in 1999, +in the context of the boom of DSL as the solution for tunneling packets +over the DSL connection to the `ISPs (Internet Service Providers)` +IP network, and from there to the rest of the Internet. A 2005 networking +book noted that "Most DSL providers use PPPoE, which provides authentication, +encryption, and compression." Typical use of PPPoE involves leveraging the +PPP facilities for authenticating the user with a username and password, +predominately via the PAP protocol and less often via CHAP. + +## Operating Modes + +VyOS supports setting up PPPoE in two different ways to a PPPoE internet +connection. This is because most ISPs provide a modem that is also a wireless +router. + +### Home Users + +In this method, the DSL Modem/Router connects to the ISP for you with your +credentials preprogrammed into the device. This gives you an `1918` +address, such as `192.168.1.0/24` by default. + +For a simple home network using just the ISP's equipment, this is usually +desirable. But if you want to run VyOS as your firewall and router, this +will result in having a double NAT and firewall setup. This results in a +few extra layers of complexity, particularly if you use some NAT or +tunnel features. + +### Business Users + +In order to have full control and make use of multiple static public IP +addresses, your VyOS will have to initiate the PPPoE connection and control +it. In order for this method to work, you will have to figure out how to make +your DSL Modem/Router switch into a Bridged Mode so it only acts as a DSL +Transceiver device to connect between the Ethernet link of your VyOS and the +phone cable. Once your DSL Transceiver is in Bridge Mode, you should get no +IP address from it. Please make sure you connect to the Ethernet Port 1 if +your DSL Transceiver has a switch, as some of them only work this way. + +Once you have an Ethernet device connected, i.e. <span class="title-ref">eth0</span>, then you can +configure it to open the PPPoE session for you and your DSL Transceiver +(Modem/Router) just acts to translate your messages in a way that +vDSL/aDSL understands. + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="pppoe" var1="pppoe0"> + +/\_include/interface-description.txt + +</div> + +<div class="cmdinclude" var0="pppoe" var1="pppoe0"> + +/\_include/interface-disable.txt + +</div> + +<div class="cmdinclude" var0="pppoe" var1="pppoe0"> + +/\_include/interface-mtu.txt + +</div> + +<div class="cmdinclude" var0="pppoe" var1="pppoe0"> + +/\_include/interface-vrf.txt + +</div> + +### PPPoE options + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> access-concentrator \<name\> + +Use this command to restrict the PPPoE session on a given access +concentrator. Normally, a host sends a PPPoE initiation packet to start the +PPPoE discovery process, a number of access concentrators respond with offer +packets and the host selects one of the responding access concentrators to +serve this session. + +This command allows you to select a specific access concentrator when you +know the access concentrators <span class="title-ref">\<name\></span>. + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> authentication username \<username\> + +Use this command to set the username for authenticating with a remote PPPoE +endpoint. Authentication is optional from the system's point of view but +most service providers require it. + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> authentication password \<password\> + +Use this command to set the password for authenticating with a remote PPPoE +endpoint. Authentication is optional from the system's point of view but +most service providers require it. + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> connect-on-demand + +When set the interface is enabled for "dial-on-demand". + +Use this command to instruct the system to establish a PPPoE connection +automatically once traffic passes through the interface. A disabled on-demand +connection is established at boot time and remains up. If the link fails for +any reason, the link is brought back up immediately. + +Enabled on-demand PPPoE connections bring up the link only when traffic needs +to pass this link. If the link fails for any reason, the link is brought +back up automatically once traffic passes the interface again. If you +configure an on-demand PPPoE connection, you must also configure the idle +timeout period, after which an idle PPPoE link will be disconnected. A +non-zero idle timeout will never disconnect the link after it first came up. + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> no-default-route + +Only request an address from the PPPoE server but do not install any default +route. + +Example: + +``` none +set interfaces pppoe pppoe0 no-default-route +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +This command got added in VyOS 1.4 and inverts the logic from the old +`default-route` CLI option. + +</div> + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> default-route-distance \<distance\> + +Set the distance for the default gateway sent by the PPPoE server. + +Example: + +``` none +set interfaces pppoe pppoe0 default-route-distance 220 +``` + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> mru \<mru\> + +Set the `MRU (Maximum Receive Unit)` to <span class="title-ref">mru</span>. PPPd will ask the peer to +send packets of no more than <span class="title-ref">mru</span> bytes. The value of <span class="title-ref">mru</span> must be between 128 +and 16384. + +A value of 296 works well on very slow links (40 bytes for TCP/IP header + 256 +bytes of data). + +The default is 1492. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +When using the IPv6 protocol, MRU must be at least 1280 bytes. + +</div> + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> idle-timeout \<time\> + +Use this command to set the idle timeout interval to be used with on-demand +PPPoE sessions. When an on-demand connection is established, the link is +brought up only when traffic is sent and is disabled when the link is idle +for the interval specified. + +If this parameter is not set or 0, an on-demand link will not be taken down +when it is idle and after the initial establishment of the connection. It +will stay up forever. + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> holdoff \<time\> + +Use this command to set re-dial delay time to be used with persist PPPoE +sessions. When the PPPoE session is terminated by peer, and on-demand +option is not set, the router will attempt to re-establish the PPPoE link. + +If this parameter is not set, the default holdoff time is 30 seconds. + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> local-address \<address\> + +Use this command to set the IP address of the local endpoint of a PPPoE +session. If it is not set it will be negotiated. + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> no-peer-dns + +Use this command to not install advertised DNS nameservers into the local +system. + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> remote-address \<address\> + +Use this command to set the IP address of the remote endpoint of a PPPoE +session. If it is not set it will be negotiated. + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> service-name \<name\> + +Use this command to specify a service name by which the local PPPoE interface +can select access concentrators to connect with. It will connect to any +access concentrator if not set. + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> source-interface \<source-interface\> + +Use this command to link the PPPoE connection to a physical interface. Each +PPPoE connection must be established over a physical interface. Interfaces +can be regular Ethernet interfaces, VIFs or bonding interfaces/VIFs. + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> ip adjust-mss \<mss | clamp-mss-to-pmtu\> + +As Internet wide PMTU discovery rarely works, we sometimes need to clamp our +TCP MSS value to a specific value. This is a field in the TCP options part of +a SYN packet. By setting the MSS value, you are telling the remote side +unequivocally 'do not try to send me packets bigger than this value'. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +This command was introduced in VyOS 1.4 - it was previously called: +`set firewall options interface <name> adjust-mss <value>` + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting in +1452 bytes on a 1492 byte MTU. + +</div> + +Instead of a numerical MSS value <span class="title-ref">clamp-mss-to-pmtu</span> can be used to +automatically set the proper value. + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> ip disable-forwarding + +Configure interface-specific Host/Router behaviour. If set, the interface will +switch to host mode and IPv6 forwarding will be disabled on this interface. + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> ip source-validation \<strict | loose | disable\> + +Enable policy for source validation by reversed path, as specified in +`3704`. Current recommended practice in `3704` is to enable strict +mode to prevent IP spoofing from DDos attacks. If using asymmetric routing +or other complicated routing, then loose mode is recommended. + +- strict: Each incoming packet is tested against the FIB and if the interface + is not the best reverse path the packet check will fail. By default failed + packets are discarded. +- loose: Each incoming packet's source address is also tested against the FIB + and if the source address is not reachable via any interface the packet + check will fail. +- disable: No source validation + +</div> + +#### IPv6 + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> ipv6 address autoconf + +Use this command to enable acquisition of IPv6 address using stateless +autoconfig (SLAAC). + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> ipv6 adjust-mss \<mss | clamp-mss-to-pmtu\> + +As Internet wide PMTU discovery rarely works, we sometimes need to clamp our +TCP MSS value to a specific value. This is a field in the TCP options part of +a SYN packet. By setting the MSS value, you are telling the remote side +unequivocally 'do not try to send me packets bigger than this value'. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +This command was introduced in VyOS 1.4 - it was previously called: +`set firewall options interface <name> adjust-mss <value>` + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +MSS value = MTU - 40 (IPv6 header) - 20 (TCP header), resulting in +1432 bytes on a 1492 byte MTU. + +</div> + +Instead of a numerical MSS value <span class="title-ref">clamp-mss-to-pmtu</span> can be used to +automatically set the proper value. + +</div> + +<div class="cfgcmd"> + +set interfaces pppoe \<interface\> ipv6 disable-forwarding + +Configure interface-specific Host/Router behaviour. If set, the interface will +switch to host mode and IPv6 forwarding will be disabled on this interface. + +</div> + +<div class="cmdinclude" var0="pppoe" var1="pppoe0"> + +/\_include/interface-dhcpv6-prefix-delegation.txt + +</div> + +## Operation + +<div class="opcmd"> + +show interfaces pppoe \<interface\> + +Show detailed information on given <span class="title-ref">\<interface\></span> + +``` none +vyos@vyos:~$ show interfaces pppoe pppoe0 +pppoe0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1492 qdisc pfifo_fast state UNKNOWN group default qlen 3 + link/ppp + inet 192.0.2.1 peer 192.0.2.255/32 scope global pppoe0 + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 7002658233 5064967 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 533822843 1620173 0 0 0 0 +``` + +</div> + +<div class="opcmd"> + +show interfaces pppoe \<interface\> queue + +Displays queue information for a PPPoE interface. + +``` none +vyos@vyos:~$ show interfaces pppoe pppoe0 queue +qdisc pfifo_fast 0: root refcnt 2 bands 3 priomap 1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1 + Sent 534625359 bytes 1626761 pkt (dropped 62, overlimits 0 requeues 0) + backlog 0b 0p requeues 0 +``` + +</div> + +### Connect/Disconnect + +<div class="opcmd"> + +disconnect interface \<interface\> + +Test disconnecting given connection-oriented interface. <span class="title-ref">\<interface\></span> can be +`pppoe0` as the example. + +</div> + +<div class="opcmd"> + +connect interface \<interface\> + +Test connecting given connection-oriented interface. <span class="title-ref">\<interface\></span> can be +`pppoe0` as the example. + +</div> + +## Example + +Requirements: + +- Your ISPs modem is connected to port `eth0` of your VyOS box. +- No VLAN tagging required by your ISP. +- You need your PPPoE credentials from your DSL ISP in order to configure + this. The usual username is in the form of <name@host.net> but may vary + depending on ISP. +- The largest MTU size you can use with DSL is 1492 due to PPPoE overhead. + If you are switching from a DHCP based ISP like cable then be aware that + things like VPN links may need to have their MTU sizes adjusted to work + within this limit. +- With the `name-server` option set to `none`, VyOS will ignore the + nameservers your ISP sends you and thus you can fully rely on the ones you + have configured statically. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Syntax has changed from VyOS 1.2 (crux) and it will be automatically +migrated during an upgrade. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +A default route is automatically installed once the interface is up. +To change this behavior use the `no-default-route` CLI option. + +</div> + +``` none +set interfaces pppoe pppoe0 authentication username 'userid' +set interfaces pppoe pppoe0 authentication password 'secret' +set interfaces pppoe pppoe0 source-interface 'eth0' +``` + +You should add a firewall to your configuration above as well by +assigning it to the pppoe0 itself as shown here: + +``` none +set firewall interface pppoe0 in name NET-IN +set firewall interface pppoe0 local name NET-LOCAL +set firewall interface pppoe0 out name NET-OUT +``` + +### VLAN Example + +Some recent ISPs require you to build the PPPoE connection through a VLAN +interface. One of those ISPs is e.g. Deutsche Telekom in Germany. VyOS +can easily create a PPPoE session through an encapsulated VLAN interface. +The following configuration will run your PPPoE connection through VLAN7 +which is the default VLAN for Deutsche Telekom: + +``` none +set interfaces pppoe pppoe0 authentication username 'userid' +set interfaces pppoe pppoe0 authentication password 'secret' +set interfaces pppoe pppoe0 source-interface 'eth0.7' +``` + +#### IPv6 DHCPv6-PD Example + +The following configuration will setup a PPPoE session source from eth1 and +assign a /64 prefix out of a /56 delegation (requested from the ISP) to eth0. +The IPv6 address assigned to eth0 will be \<prefix\>::1/64. If you do not know +the prefix size delegated to you, start with sla-len 0. + +In addition we setup IPv6 `RA (Router Advertisements)` to make the +prefix known on the eth0 link. + +``` none +set interfaces pppoe pppoe0 authentication username vyos +set interfaces pppoe pppoe0 authentication password vyos +set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth0 address '1' +set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth0 sla-id '0' +set interfaces pppoe pppoe0 dhcpv6-options pd 0 length '56' +set interfaces pppoe pppoe0 ipv6 address autoconf +set interfaces pppoe pppoe0 source-interface eth1 + +set service router-advert interface eth0 prefix ::/64 +``` diff --git a/docs/configuration/interfaces/md-pseudo-ethernet.md b/docs/configuration/interfaces/md-pseudo-ethernet.md new file mode 100644 index 00000000..a58ccfc6 --- /dev/null +++ b/docs/configuration/interfaces/md-pseudo-ethernet.md @@ -0,0 +1,67 @@ +lastproofread +2023-01-26 + +# MACVLAN - Pseudo Ethernet + +Pseudo-Ethernet or MACVLAN interfaces can be seen as subinterfaces to regular +ethernet interfaces. Each and every subinterface is created a different media +access control (MAC) address, for a single physical Ethernet port. Pseudo- +Ethernet interfaces have most of their application in virtualized environments, + +By using Pseudo-Ethernet interfaces there will be less system overhead compared +to running a traditional bridging approach. Pseudo-Ethernet interfaces can also +be used to workaround the general limit of 4096 virtual LANs (VLANs) per +physical Ethernet port, since that limit is with respect to a single MAC +address. + +Every Virtual Ethernet interfaces behaves like a real Ethernet interface. They +can have IPv4/IPv6 addresses configured, or can request addresses by DHCP/ +DHCPv6 and are associated/mapped with a real ethernet port. This also makes +Pseudo-Ethernet interfaces interesting for testing purposes. A Pseudo-Ethernet +device will inherit characteristics (speed, duplex, ...) from its physical +parent (the so called link) interface. + +Once created in the system, Pseudo-Ethernet interfaces can be referenced in +the exact same way as other Ethernet interfaces. Notes about using Pseudo- +Ethernet interfaces: + +- Pseudo-Ethernet interfaces can not be reached from your internal host. This + means that you can not try to ping a Pseudo-Ethernet interface from the host + system on which it is defined. The ping will be lost. +- Loopbacks occurs at the IP level the same way as for other interfaces, + ethernet frames are not forwarded between Pseudo-Ethernet interfaces. +- Pseudo-Ethernet interfaces may not work in environments which expect a + `NIC (Network Interface Card)` to only have a single address. This + applies to: + - VMware machines using default settings + - Network switches with security settings allowing only a single MAC address + - xDSL modems that try to learn the MAC address of the NIC + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="pseudo-ethernet" var1="peth0"> + +/\_include/interface-common-with-dhcp.txt + +</div> + +### Pseudo Ethernet/MACVLAN options + +<div class="cfgcmd"> + +set interfaces pseudo-ethernet \<interface\> source-interface \<ethX\> + +Specifies the physical <span class="title-ref">\<ethX\></span> Ethernet interface associated with a Pseudo +Ethernet <span class="title-ref">\<interface\></span>. + +</div> + +### VLAN + +<div class="cmdinclude" var0="pseudo-ethernet" var1="peth0"> + +/\_include/interface-vlan-8021q.txt + +</div> diff --git a/docs/configuration/interfaces/md-sstp-client.md b/docs/configuration/interfaces/md-sstp-client.md new file mode 100644 index 00000000..d5c19d8f --- /dev/null +++ b/docs/configuration/interfaces/md-sstp-client.md @@ -0,0 +1,225 @@ +lastproofread +2022-12-11 + +# SSTP Client + +`SSTP (Secure Socket Tunneling Protocol)` is a form of `VTP (Virtual +Private Network)` tunnel that provides a mechanism to transport PPP traffic +through an SSL/TLS channel. SSL/TLS provides transport-level security with key +negotiation, encryption and traffic integrity checking. The use of SSL/TLS over +TCP port 443 (by default, port can be changed) allows SSTP to pass through +virtually all firewalls and proxy servers except for authenticated web proxies. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +VyOS also comes with a build in SSTP server, see `sstp`. + +</div> + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="sstpc" var1="sstpc0"> + +/\_include/interface-description.txt + +</div> + +<div class="cmdinclude" var0="sstpc" var1="sstpc0"> + +/\_include/interface-disable.txt + +</div> + +<div class="cmdinclude" var0="sstpc" var1="sstpc0"> + +/\_include/interface-mtu.txt + +</div> + +<div class="cmdinclude" var0="sstpc" var1="sstpc0"> + +/\_include/interface-vrf.txt + +</div> + +### SSTP Client Options + +<div class="cfgcmd"> + +set interfaces sstpc \<interface\> no-default-route + +Only request an address from the SSTP server but do not install any default +route. + +Example: + +``` none +set interfaces sstpc sstpc0 no-default-route +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +This command got added in VyOS 1.4 and inverts the logic from the old +`default-route` CLI option. + +</div> + +</div> + +<div class="cfgcmd"> + +set interfaces sstpc \<interface\> default-route-distance \<distance\> + +Set the distance for the default gateway sent by the SSTP server. + +Example: + +``` none +set interfaces sstpc sstpc0 default-route-distance 220 +``` + +</div> + +<div class="cfgcmd"> + +set interfaces sstpc \<interface\> no-peer-dns + +Use this command to not install advertised DNS nameservers into the local +system. + +</div> + +<div class="cfgcmd"> + +set interfaces sstpc \<interface\> server \<address\> + +SSTP remote server to connect to. Can be either an IP address or FQDN. + +</div> + +<div class="cfgcmd"> + +set interfaces sstpc \<interface\> ip adjust-mss \<mss | clamp-mss-to-pmtu\> + +As Internet wide PMTU discovery rarely works, we sometimes need to clamp our +TCP MSS value to a specific value. This is a field in the TCP options part of +a SYN packet. By setting the MSS value, you are telling the remote side +unequivocally 'do not try to send me packets bigger than this value'. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +This command was introduced in VyOS 1.4 - it was previously called: +`set firewall options interface <name> adjust-mss <value>` + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting in +1452 bytes on a 1492 byte MTU. + +</div> + +Instead of a numerical MSS value <span class="title-ref">clamp-mss-to-pmtu</span> can be used to +automatically set the proper value. + +</div> + +<div class="cfgcmd"> + +set interfaces sstpc \<interface\> ip disable-forwarding + +Configure interface-specific Host/Router behaviour. If set, the interface will +switch to host mode and IPv6 forwarding will be disabled on this interface. + +</div> + +<div class="cfgcmd"> + +set interfaces sstpc \<interface\> ip source-validation \<strict | loose | disable\> + +Enable policy for source validation by reversed path, as specified in +`3704`. Current recommended practice in `3704` is to enable strict +mode to prevent IP spoofing from DDos attacks. If using asymmetric routing +or other complicated routing, then loose mode is recommended. + +- strict: Each incoming packet is tested against the FIB and if the interface + is not the best reverse path the packet check will fail. By default failed + packets are discarded. +- loose: Each incoming packet's source address is also tested against the FIB + and if the source address is not reachable via any interface the packet + check will fail. +- disable: No source validation + +</div> + +## Operation + +<div class="opcmd"> + +show interfaces sstpc \<interface\> + +Show detailed information on given <span class="title-ref">\<interface\></span> + +``` none +vyos@vyos:~$ show interfaces sstpc sstpc10 +sstpc10: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 3 + link/ppp + inet 192.0.2.5 peer 192.0.2.254/32 scope global sstpc10 + valid_lft forever preferred_lft forever + inet6 fe80::fd53:c7ff:fe8b:144f/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 215 9 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 539 14 0 0 0 0 +``` + +</div> + +### Connect/Disconnect + +<div class="opcmd"> + +disconnect interface \<interface\> + +Test disconnecting given connection-oriented interface. <span class="title-ref">\<interface\></span> can be +`sstpc0` as the example. + +</div> + +<div class="opcmd"> + +connect interface \<interface\> + +Test connecting given connection-oriented interface. <span class="title-ref">\<interface\></span> can be +`sstpc0` as the example. + +</div> diff --git a/docs/configuration/interfaces/md-tunnel.md b/docs/configuration/interfaces/md-tunnel.md new file mode 100644 index 00000000..53ba1a3e --- /dev/null +++ b/docs/configuration/interfaces/md-tunnel.md @@ -0,0 +1,283 @@ +lastproofread +2023-01-26 + +# Tunnel + +This article touches on 'classic' IP tunneling protocols. + +GRE is often seen as a one size fits all solution when it comes to classic IP +tunneling protocols, and for a good reason. However, there are more specialized +options, and many of them are supported by VyOS. There are also rather obscure +GRE options that can be useful. + +All those protocols are grouped under `interfaces tunnel` in VyOS. Let's take +a closer look at the protocols and options currently supported by VyOS. + +## Common interface configuration + +<div class="cmdinclude" var0="tunnel" var1="tun0"> + +/\_include/interface-address.txt + +</div> + +<div class="cmdinclude" var0="tunnel" var1="tun0"> + +/\_include/interface-common-without-mac.txt + +</div> + +## IPIP + +This is one of the simplest types of tunnels, as defined by `2003`. +It takes an IPv4 packet and sends it as a payload of another IPv4 packet. For +this reason, there are no other configuration options for this kind of tunnel. + +An example: + +``` none +set interfaces tunnel tun0 encapsulation ipip +set interfaces tunnel tun0 source-address 192.0.2.10 +set interfaces tunnel tun0 remote 203.0.113.20 +set interfaces tunnel tun0 address 192.168.100.200/24 +``` + +## IP6IP6 + +This is the IPv6 counterpart of IPIP. I'm not aware of an RFC that defines this +encapsulation specifically, but it's a natural specific case of IPv6 +encapsulation mechanisms described in :rfc:2473\`. + +It's not likely that anyone will need it any time soon, but it does exist. + +An example: + +``` none +set interfaces tunnel tun0 encapsulation ip6ip6 +set interfaces tunnel tun0 source-address 2001:db8:aa::1 +set interfaces tunnel tun0 remote 2001:db8:aa::2 +set interfaces tunnel tun0 address 2001:db8:bb::1/64 +``` + +## IPIP6 + +In the future this is expected to be a very useful protocol (though there are +[other proposals](https://www.isc.org/othersoftware/)). + +As the name implies, it's IPv4 encapsulated in IPv6, as simple as that. + +An example: + +``` none +set interfaces tunnel tun0 encapsulation ipip6 +set interfaces tunnel tun0 source-address 2001:db8:aa::1 +set interfaces tunnel tun0 remote 2001:db8:aa::2 +set interfaces tunnel tun0 address 192.168.70.80/24 +``` + +## 6in4 (SIT) + +6in4 uses tunneling to encapsulate IPv6 traffic over IPv4 links as defined in +`4213`. The 6in4 traffic is sent over IPv4 inside IPv4 packets whose IP +headers have the IP protocol number set to 41. This protocol number is +specifically designated for IPv6 encapsulation, the IPv4 packet header is +immediately followed by the IPv6 packet being carried. The encapsulation +overhead is the size of the IPv4 header of 20 bytes, therefore with an MTU of +1500 bytes, IPv6 packets of 1480 bytes can be sent without fragmentation. This +tunneling technique is frequently used by IPv6 tunnel brokers like [Hurricane +Electric](https://tunnelbroker.net/). + +An example: + +``` none +set interfaces tunnel tun0 encapsulation sit +set interfaces tunnel tun0 source-address 192.0.2.10 +set interfaces tunnel tun0 remote 192.0.2.20 +set interfaces tunnel tun0 address 2001:db8:bb::1/64 +``` + +A full example of a Tunnelbroker.net config can be found at +`here <examples-tunnelbroker-ipv6>`. + +## Generic Routing Encapsulation (GRE) + +A GRE tunnel operates at layer 3 of the OSI model and is represented by IP +protocol 47. The main benefit of a GRE tunnel is that you are able to carry +multiple protocols inside the same tunnel. GRE also supports multicast traffic +and supports routing protocols that leverage multicast to form neighbor +adjacencies. + +A VyOS GRE tunnel can carry both IPv4 and IPv6 traffic and can also be created +over either IPv4 (gre) or IPv6 (ip6gre). + +### Configuration + +A basic configuration requires a tunnel source (source-address), a tunnel +destination (remote), an encapsulation type (gre), and an address (ipv4/ipv6). +Below is a basic IPv4 only configuration example taken from a VyOS router and +a Cisco IOS router. The main difference between these two configurations is +that VyOS requires you explicitly configure the encapsulation type. The Cisco +router defaults to GRE IP otherwise it would have to be configured as well. + +**VyOS Router:** + +``` none +set interfaces tunnel tun100 address '10.0.0.1/30' +set interfaces tunnel tun100 encapsulation 'gre' +set interfaces tunnel tun100 source-address '198.51.100.2' +set interfaces tunnel tun100 remote '203.0.113.10' +``` + +**Cisco IOS Router:** + +``` none +interface Tunnel100 +ip address 10.0.0.2 255.255.255.252 +tunnel source 203.0.113.10 +tunnel destination 198.51.100.2 +``` + +Here is a second example of a dual-stack tunnel over IPv6 between a VyOS router +and a Linux host using systemd-networkd. + +**VyOS Router:** + +``` none +set interfaces tunnel tun101 address '2001:db8:feed:beef::1/126' +set interfaces tunnel tun101 address '192.168.5.1/30' +set interfaces tunnel tun101 encapsulation 'ip6gre' +set interfaces tunnel tun101 source-address '2001:db8:babe:face::3afe:3' +set interfaces tunnel tun101 remote '2001:db8:9bb:3ce::5' +``` + +**Linux systemd-networkd:** + +This requires two files, one to create the device (XXX.netdev) and one +to configure the network on the device (XXX.network) + +``` none +# cat /etc/systemd/network/gre-example.netdev +[NetDev] +Name=gre-example +Kind=ip6gre +MTUBytes=14180 + +[Tunnel] +Remote=2001:db8:babe:face::3afe:3 + + +# cat /etc/systemd/network/gre-example.network +[Match] +Name=gre-example + +[Network] +Address=2001:db8:feed:beef::2/126 + +[Address] +Address=192.168.5.2/30 +``` + +### Tunnel keys + +GRE is also the only classic protocol that allows creating multiple tunnels +with the same source and destination due to its support for tunnel keys. +Despite its name, this feature has nothing to do with security: it's simply +an identifier that allows routers to tell one tunnel from another. + +An example: + +``` none +set interfaces tunnel tun0 source-address 192.0.2.10 +set interfaces tunnel tun0 remote 192.0.2.20 +set interfaces tunnel tun0 address 10.40.50.60/24 +set interfaces tunnel tun0 parameters ip key 10 +``` + +``` none +set interfaces tunnel tun0 source-address 192.0.2.10 +set interfaces tunnel tun0 remote 192.0.2.20 +set interfaces tunnel tun0 address 172.16.17.18/24 +set interfaces tunnel tun0 parameters ip key 20 +``` + +### GRETAP + +While normal GRE is for layer 3, GRETAP is for layer 2. GRETAP can encapsulate +Ethernet frames, thus it can be bridged with other interfaces to create +datalink layer segments that span multiple remote sites. + +``` none +set interfaces bridge br0 member interface eth0 +set interfaces bridge br0 member interface tun0 +set interfaces tunnel tun0 encapsulation gretap +set interfaces tunnel tun0 source-address 198.51.100.2 +set interfaces tunnel tun0 remote 203.0.113.10 +``` + +### Troubleshooting + +GRE is a well defined standard that is common in most networks. While not +inherently difficult to configure there are a couple of things to keep in mind +to make sure the configuration performs as expected. A common cause for GRE +tunnels to fail to come up correctly include ACL or Firewall configurations +that are discarding IP protocol 47 or blocking your source/destination traffic. + +**1. Confirm IP connectivity between tunnel source-address and remote:** + +``` none +vyos@vyos:~$ ping 203.0.113.10 interface 198.51.100.2 count 4 +PING 203.0.113.10 (203.0.113.10) from 198.51.100.2 : 56(84) bytes of data. +64 bytes from 203.0.113.10: icmp_seq=1 ttl=254 time=0.807 ms +64 bytes from 203.0.113.10: icmp_seq=2 ttl=254 time=1.50 ms +64 bytes from 203.0.113.10: icmp_seq=3 ttl=254 time=0.624 ms +64 bytes from 203.0.113.10: icmp_seq=4 ttl=254 time=1.41 ms + +--- 203.0.113.10 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 3007ms +rtt min/avg/max/mdev = 0.624/1.087/1.509/0.381 ms +``` + +**2. Confirm the link type has been set to GRE:** + +``` none +vyos@vyos:~$ show interfaces tunnel tun100 +tun100@NONE: <POINTOPOINT,NOARP,UP,LOWER_UP> mtu 1476 qdisc noqueue state UNKNOWN group default qlen 1000 + link/gre 198.51.100.2 peer 203.0.113.10 + inet 10.0.0.1/30 brd 10.0.0.3 scope global tun100 + valid_lft forever preferred_lft forever + inet6 fe80::5efe:c612:2/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 2183 27 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 836 9 0 0 0 0 +``` + +**3. Confirm IP connectivity across the tunnel:** + +``` none +vyos@vyos:~$ ping 10.0.0.2 interface 10.0.0.1 count 4 +PING 10.0.0.2 (10.0.0.2) from 10.0.0.1 : 56(84) bytes of data. +64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=1.05 ms +64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=1.88 ms +64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=1.98 ms +64 bytes from 10.0.0.2: icmp_seq=4 ttl=255 time=1.98 ms + +--- 10.0.0.2 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 3008ms +rtt min/avg/max/mdev = 1.055/1.729/1.989/0.395 ms +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +There is also a GRE over IPv6 encapsulation available, it is +called: `ip6gre`. + +</div> diff --git a/docs/configuration/interfaces/md-virtual-ethernet.md b/docs/configuration/interfaces/md-virtual-ethernet.md new file mode 100644 index 00000000..2d3f4c63 --- /dev/null +++ b/docs/configuration/interfaces/md-virtual-ethernet.md @@ -0,0 +1,127 @@ +lastproofread +2022-11-25 + +# Virtual Ethernet + +The veth devices are virtual Ethernet devices. They can act as tunnels between +network namespaces to create a bridge to a physical network device in another +namespace or VRF, but can also be used as standalone network devices. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +veth interfaces need to be created in pairs - it's called the peer name + +</div> + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="virtual-ethernet" var1="veth0"> + +/\_include/interface-address-with-dhcp.txt + +</div> + +<div class="cmdinclude" var0="virtual-ethernet" var1="veth0"> + +/\_include/interface-description.txt + +</div> + +### VLAN + +#### Regular VLANs (802.1q) + +<div class="cmdinclude" var0="virtual-ethernet" var1="veth0"> + +/\_include/interface-vlan-8021q.txt + +</div> + +#### QinQ (802.1ad) + +<div class="cmdinclude" var0="virtual-ethernet" var1="veth0"> + +/\_include/interface-vlan-8021ad.txt + +</div> + +<div class="cmdinclude" var0="virtual-ethernet" var1="veth0"> + +/\_include/interface-disable.txt + +</div> + +<div class="cmdinclude" var0="virtual-ethernet" var1="veth0"> + +/\_include/interface-vrf.txt + +</div> + +## Operation + +<div class="opcmd"> + +show interfaces virtual-ethernet + +Show brief interface information. + +``` none +vyos@vyos:~$ show interfaces virtual-ethernet +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +veth10 100.64.0.0/31 u/u +veth11 100.64.0.1/31 u/u +``` + +</div> + +<div class="opcmd"> + +show interfaces virtual-ethernet \<interface\> + +Show detailed information on given <span class="title-ref">\<interface\></span> + +``` none +vyos@vyos:~$ show interfaces virtual-ethernet veth11 +10: veth11@veth10: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue master red state UP group default qlen 1000 + link/ether b2:7b:df:47:e9:11 brd ff:ff:ff:ff:ff:ff + inet 100.64.0.1/31 scope global veth11 + valid_lft forever preferred_lft forever + inet6 fe80::b07b:dfff:fe47:e911/64 scope link + valid_lft forever preferred_lft forever + + + RX: bytes packets errors dropped overrun mcast + 0 0 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 1369707 4267 0 0 0 0 +``` + +</div> + +## Example + +Interconnect the global VRF with vrf "red" using the veth10 \<-\> veth 11 pair + +``` none +set interfaces virtual-ethernet veth10 address '100.64.0.0/31' +set interfaces virtual-ethernet veth10 peer-name 'veth11' +set interfaces virtual-ethernet veth11 address '100.64.0.1/31' +set interfaces virtual-ethernet veth11 peer-name 'veth10' +set interfaces virtual-ethernet veth11 vrf 'red' +set vrf name red table '1000' + +vyos@vyos:~$ ping 100.64.0.1 +PING 100.64.0.1 (100.64.0.1) 56(84) bytes of data. +64 bytes from 100.64.0.1: icmp_seq=1 ttl=64 time=0.080 ms +64 bytes from 100.64.0.1: icmp_seq=2 ttl=64 time=0.119 ms +``` diff --git a/docs/configuration/interfaces/md-vti.md b/docs/configuration/interfaces/md-vti.md new file mode 100644 index 00000000..0d924f65 --- /dev/null +++ b/docs/configuration/interfaces/md-vti.md @@ -0,0 +1,46 @@ +# VTI - Virtual Tunnel Interface + +Set Virtual Tunnel Interface + +``` none +set interfaces vti vti0 address 192.168.2.249/30 +set interfaces vti vti0 address 2001:db8:2::249/64 +``` + +Results in: + +``` none +vyos@vyos# show interfaces vti +vti vti0 { + address 192.168.2.249/30 + address 2001:db8:2::249/64 + description "Description" +} +``` + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +When using site-to-site IPsec with VTI interfaces, +be sure to disable route autoinstall + +</div> + +``` none +set vpn ipsec options disable-route-autoinstall +``` + +More details about the IPsec and VTI issue and option disable-route-autoinstall +<https://blog.vyos.io/vyos-1-dot-2-0-development-news-in-july> + +The root cause of the problem is that for VTI tunnels to work, their traffic +selectors have to be set to 0.0.0.0/0 for traffic to match the tunnel, even +though actual routing decision is made according to netfilter marks. Unless +route insertion is disabled entirely, StrongSWAN thus mistakenly inserts a +default route through the VTI peer address, which makes all traffic routed +to nowhere. diff --git a/docs/configuration/interfaces/md-vxlan.md b/docs/configuration/interfaces/md-vxlan.md new file mode 100644 index 00000000..9a991c08 --- /dev/null +++ b/docs/configuration/interfaces/md-vxlan.md @@ -0,0 +1,396 @@ +lastproofread +2023-01-26 + +# VXLAN + +`VXLAN (Virtual Extensible LAN)` is a network virtualization technology +that attempts to address the scalability problems associated with large cloud +computing deployments. It uses a VLAN-like encapsulation technique to +encapsulate OSI layer 2 Ethernet frames within layer 4 UDP datagrams, using +4789 as the default IANA-assigned destination UDP port number. VXLAN +endpoints, which terminate VXLAN tunnels and may be either virtual or physical +switch ports, are known as `VTEPs (VXLAN tunnel endpoints)`. + +VXLAN is an evolution of efforts to standardize an overlay encapsulation +protocol. It increases the scalability up to 16 million logical networks and +allows for layer 2 adjacency across IP networks. Multicast or unicast with +head-end replication (HER) is used to flood broadcast, unknown unicast, +and multicast (BUM) traffic. + +The VXLAN specification was originally created by VMware, Arista Networks +and Cisco. Other backers of the VXLAN technology include Huawei, Broadcom, +Citrix, Pica8, Big Switch Networks, Cumulus Networks, Dell EMC, Ericsson, +Mellanox, FreeBSD, OpenBSD, Red Hat, Joyent, and Juniper Networks. + +VXLAN was officially documented by the IETF in `7348`. + +If configuring VXLAN in a VyOS virtual machine, ensure that MAC spoofing +(Hyper-V) or Forged Transmits (ESX) are permitted, otherwise forwarded frames +may be blocked by the hypervisor. + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="vxlan" var1="vxlan0"> + +/\_include/interface-common-without-dhcp.txt + +</div> + +### VXLAN specific options + +<div class="cfgcmd"> + +set interfaces vxlan \<interface\> vni \<number\> + +Each VXLAN segment is identified through a 24-bit segment ID, termed the +`VNI (VXLAN Network Identifier (or VXLAN Segment ID))`, This allows +up to 16M VXLAN segments to coexist within the same administrative domain. + +</div> + +<div class="cfgcmd"> + +set interfaces vxlan \<interface\> port \<port\> + +Configure port number of remote VXLAN endpoint. + +</div> + +<div class="cfgcmd"> + +set interfaces vxlan \<interface\> source-address \<IP address\> + +Source IP address used for VXLAN underlay. This is mandatory when using VXLAN +via L2VPN/EVPN. + +</div> + +<div class="cfgcmd"> + +set interfaces vxlan \<interface\> gpe + +Enables the Generic Protocol extension (VXLAN-GPE). Currently, this is only +supported together with the external keyword. + +</div> + +<div class="cfgcmd"> + +set interfaces vxlan \<interface\> parameters external + +Specifies whether an external control plane (e.g. BGP L2VPN/EVPN) or the +internal FDB should be used. + +</div> + +<div class="cfgcmd"> + +set interfaces vxlan \<interface\> parameters neighbor-suppress + +In order to minimize the flooding of ARP and ND messages in the VXLAN network, +EVPN includes provisions `7432#section-10` that allow participating VTEPs +to suppress such messages in case they know the MAC-IP binding and can reply +on behalf of the remote host. + +</div> + +<div class="cfgcmd"> + +set interfaces vxlan \<interface\> parameters nolearning + +Specifies if unknown source link layer addresses and IP addresses are entered +into the VXLAN device forwarding database. + +</div> + +<div class="cfgcmd"> + +set interfaces vxlan \<interface\> parameters vni-filter + +Specifies whether the VXLAN device is capable of vni filtering. + +Only works with a VXLAN device with external flag set. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The device can only receive packets with VNIs configured in +the VNI filtering table. + +</div> + +</div> + +#### Unicast + +<div class="cfgcmd"> + +set interfaces vxlan \<interface\> remote \<address\> + +IPv4/IPv6 remote address of the VXLAN tunnel. Alternative to multicast, the +remote IPv4/IPv6 address can set directly. + +</div> + +#### Multicast + +<div class="cfgcmd"> + +set interfaces vxlan \<interface\> source-interface \<interface\> + +Interface used for VXLAN underlay. This is mandatory when using VXLAN via +a multicast network. VXLAN traffic will always enter and exit this interface. + +</div> + +<div class="cfgcmd"> + +set interfaces vxlan \<interface\> group \<address\> + +Multicast group address for VXLAN interface. VXLAN tunnels can be built +either via Multicast or via Unicast. + +Both IPv4 and IPv6 multicast is possible. + +</div> + +## Multicast VXLAN + +Topology: PC4 - Leaf2 - Spine1 - Leaf3 - PC5 + +PC4 has IP 10.0.0.4/24 and PC5 has IP 10.0.0.5/24, so they believe they are in +the same broadcast domain. + +Let's assume PC4 on Leaf2 wants to ping PC5 on Leaf3. Instead of setting Leaf3 +as our remote end manually, Leaf2 encapsulates the packet into a UDP-packet and +sends it to its designated multicast-address via Spine1. When Spine1 receives +this packet it forwards it to all other leaves who has joined the same +multicast-group, in this case Leaf3. When Leaf3 receives the packet it forwards +it, while at the same time learning that PC4 is reachable behind Leaf2, because +the encapsulated packet had Leaf2's IP address set as source IP. + +PC5 receives the ping echo, responds with an echo reply that Leaf3 receives and +this time forwards to Leaf2's unicast address directly because it learned the +location of PC4 above. When Leaf2 receives the echo reply from PC5 it sees that +it came from Leaf3 and so remembers that PC5 is reachable via Leaf3. + +Thanks to this discovery, any subsequent traffic between PC4 and PC5 will not +be using the multicast-address between the leaves as they both know behind which +Leaf the PCs are connected. This saves traffic as less multicast packets sent +reduces the load on the network, which improves scalability when more leaves are +added. + +For optimal scalability, Multicast shouldn't be used at all, but instead use BGP +to signal all connected devices between leaves. Unfortunately, VyOS does not yet +support this. + +## Single VXLAN device (SVD) + +FRR supports a new way of configuring VLAN-to-VNI mappings for EVPN-VXLAN, when +working with the Linux kernel. In this new way, the mapping of a VLAN to a +`VNI (VXLAN Network Identifier (or VXLAN Segment ID))` is configured +against a container VXLAN interface which is referred to as a +`SVD (Single VXLAN device)`. + +Multiple VLAN to VNI mappings can be configured against the same SVD. This +allows for a significant scaling of the number of VNIs since a separate VXLAN +interface is no longer required for each VNI. + +<div class="cfgcmd"> + +set interfaces vxlan \<interface\> vlan-to-vni \<vlan\> vni \<vni\> + +Maps the VNI to the specified VLAN id. The VLAN can then be consumed by +a bridge. + +Sample configuration of SVD with VLAN to VNI mappings is shown below. + +``` none +set interfaces bridge br0 member interface vxlan0 +set interfaces vxlan vxlan0 parameters external +set interfaces vxlan vxlan0 source-interface 'dum0' +set interfaces vxlan vxlan0 vlan-to-vni 10 vni '10010' +set interfaces vxlan vxlan0 vlan-to-vni 11 vni '10011' +set interfaces vxlan vxlan0 vlan-to-vni 30 vni '10030' +set interfaces vxlan vxlan0 vlan-to-vni 31 vni '10031' +``` + +</div> + +### Example + +The setup is this: Leaf2 - Spine1 - Leaf3 + +Spine1 is a Cisco IOS router running version 15.4, Leaf2 and Leaf3 is each a +VyOS router running 1.2. + +This topology was built using GNS3. + +Topology: + +``` none +Spine1: +fa0/2 towards Leaf2, IP-address: 10.1.2.1/24 +fa0/3 towards Leaf3, IP-address: 10.1.3.1/24 + +Leaf2: +Eth0 towards Spine1, IP-address: 10.1.2.2/24 +Eth1 towards a vlan-aware switch + +Leaf3: +Eth0 towards Spine1, IP-address 10.1.3.3/24 +Eth1 towards a vlan-aware switch +``` + +**Spine1 Configuration:** + +``` none +conf t +ip multicast-routing +! +interface fastethernet0/2 + ip address 10.1.2.1 255.255.255.0 + ip pim sparse-dense-mode +! +interface fastethernet0/3 + ip address 10.1.3.1 255.255.255.0 + ip pim sparse-dense-mode +! +router ospf 1 + network 10.0.0.0 0.255.255.255 area 0 +``` + +Multicast-routing is required for the leaves to forward traffic between each +other in a more scalable way. This also requires PIM to be enabled towards the +leaves so that the Spine can learn what multicast groups each Leaf expects +traffic from. + +**Leaf2 configuration:** + +``` none +set interfaces ethernet eth0 address '10.1.2.2/24' +set protocols ospf area 0 network '10.0.0.0/8' + +! Our first vxlan interface +set interfaces bridge br241 address '172.16.241.1/24' +set interfaces bridge br241 member interface 'eth1.241' +set interfaces bridge br241 member interface 'vxlan241' + +set interfaces vxlan vxlan241 group '239.0.0.241' +set interfaces vxlan vxlan241 source-interface 'eth0' +set interfaces vxlan vxlan241 vni '241' + +! Our seconds vxlan interface +set interfaces bridge br242 address '172.16.242.1/24' +set interfaces bridge br242 member interface 'eth1.242' +set interfaces bridge br242 member interface 'vxlan242' + +set interfaces vxlan vxlan242 group '239.0.0.242' +set interfaces vxlan vxlan242 source-interface 'eth0' +set interfaces vxlan vxlan242 vni '242' +``` + +**Leaf3 configuration:** + +``` none +set interfaces ethernet eth0 address '10.1.3.3/24' +set protocols ospf area 0 network '10.0.0.0/8' + +! Our first vxlan interface +set interfaces bridge br241 address '172.16.241.1/24' +set interfaces bridge br241 member interface 'eth1.241' +set interfaces bridge br241 member interface 'vxlan241' + +set interfaces vxlan vxlan241 group '239.0.0.241' +set interfaces vxlan vxlan241 source-interface 'eth0' +set interfaces vxlan vxlan241 vni '241' + +! Our seconds vxlan interface +set interfaces bridge br242 address '172.16.242.1/24' +set interfaces bridge br242 member interface 'eth1.242' +set interfaces bridge br242 member interface 'vxlan242' + +set interfaces vxlan vxlan242 group '239.0.0.242' +set interfaces vxlan vxlan242 source-interface 'eth0' +set interfaces vxlan vxlan242 vni '242' +``` + +As you can see, Leaf2 and Leaf3 configuration is almost identical. There are +lots of commands above, I'll try to into more detail below, command +descriptions are placed under the command boxes: + +``` none +set interfaces bridge br241 address '172.16.241.1/24' +``` + +This commands creates a bridge that is used to bind traffic on eth1 vlan 241 +with the vxlan241-interface. The IP address is not required. It may however be +used as a default gateway for each Leaf which allows devices on the vlan to +reach other subnets. This requires that the subnets are redistributed by OSPF +so that the Spine will learn how to reach it. To do this you need to change the +OSPF network from '10.0.0.0/8' to '0.0.0.0/0' to allow 172.16/12-networks to be +advertised. + +``` none +set interfaces bridge br241 member interface 'eth1.241' +set interfaces bridge br241 member interface 'vxlan241' +``` + +Binds eth1.241 and vxlan241 to each other by making them both member +interfaces of the same bridge. + +``` none +set interfaces vxlan vxlan241 group '239.0.0.241' +``` + +The multicast-group used by all leaves for this vlan extension. Has to be the +same on all leaves that has this interface. + +``` none +set interfaces vxlan vxlan241 source-interface 'eth0' +``` + +Sets the interface to listen for multicast packets on. Could be a loopback, not +yet tested. + +``` none +set interfaces vxlan vxlan241 vni '241' +``` + +Sets the unique id for this vxlan-interface. Not sure how it correlates with +multicast-address. + +``` none +set interfaces vxlan vxlan241 port 12345 +``` + +The destination port used for creating a VXLAN interface defaults to +4789. Aconfiguration directive to support a user-specified destination port +to override that behavior is available using the above command. + +## Unicast VXLAN + +Alternative to multicast, the remote IPv4 address of the VXLAN tunnel can be +set directly. Let's change the Multicast example from above: + +``` none +# leaf2 and leaf3 +delete interfaces vxlan vxlan241 group '239.0.0.241' +delete interfaces vxlan vxlan241 source-interface 'eth0' + +# leaf2 +set interface vxlan vxlan241 remote 10.1.3.3 + +# leaf3 +set interface vxlan vxlan241 remote 10.1.2.2 +``` + +The default port udp is set to 4789. +It can be changed with `set interface vxlan <vxlanN> port <port>` diff --git a/docs/configuration/interfaces/md-wireguard.md b/docs/configuration/interfaces/md-wireguard.md new file mode 100644 index 00000000..4e2689f5 --- /dev/null +++ b/docs/configuration/interfaces/md-wireguard.md @@ -0,0 +1,480 @@ +lastproofread +2023-01-26 + +# WireGuard + +WireGuard is an extremely simple yet fast and modern VPN that utilizes +state-of-the-art cryptography. See <https://www.wireguard.com> for more +information. + +## Site to Site VPN + +This diagram corresponds with the example site to site configuration below. + +<figure> +<img src="/_static/images/wireguard_site2site_diagram.webp" /> +</figure> + +## Keypairs + +WireGuard requires the generation of a keypair, which includes a private key to +decrypt incoming traffic, and a public key for peer(s) to encrypt traffic. + +### Generate Keypair + +<div class="opcmd"> + +generate pki wireguard key-pair + +It generates the keypair, which includes the public and private parts. +The key is not stored on the system - only a keypair is generated. + +``` none +vyos@vyos:~$ generate pki wireguard key-pair +Private key: iJJyEARGK52Ls1GYRCcFvPuTj7WyWYDo//BknoDU0XY= +Public key: EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw= +``` + +</div> + +<div class="opcmd"> + +generate pki wireguard key-pair install interface \<interface\> + +Generates a keypair, which includes the public and private parts, and build +a configuration command to install this key to `interface`. + +``` none +vyos@vyos:~$ generate pki wireguard key-pair install interface wg10 +"generate" CLI command executed from operational level. +Generated private-key is not stored to CLI, use configure mode commands to install key: + +set interfaces wireguard wg10 private-key '4Krkv8h6NkAYMMaBWI957yYDJDMvj9URTHstdlOcDU0=' + +Corresponding public-key to use on peer system is: 'UxDsYT6EnpTIOKUzvMlw2p0sNOKQvFxEdSVrnNrX1Ro=' +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If this command is invoked from configure mode with the `run` +prefix the key is automatically installed to the appropriate interface: + +``` none +vyos@vyos# run generate pki wireguard key-pair install interface wg10 +"generate" CLI command executed from config session. +Generated private-key was imported to CLI! + +Use the following command to verify: show interfaces wireguard wg10 +Corresponding public-key to use on peer system is: '7d9KwabjLhHpJiEJeIGd0CBlao/eTwFOh6xyCovTfG8=' + +vyos@vyos# compare +[edit interfaces] ++wireguard wg10 { ++ private-key CJweb8FC6BU3Loj4PC2pn5V82cDjIPs7G1saW0ZfLWc= ++} +``` + +</div> + +</div> + +<div class="opcmd"> + +show interfaces wireguard \<interface\> public-key + +Retrieve public key portion from configured WIreGuard interface. + +``` none +vyos@vyos:~$ show interfaces wireguard wg01 public-key +EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw= +``` + +</div> + +#### Optional + +<div class="opcmd"> + +generate pki wireguard preshared-key + +An additional layer of symmetric-key crypto can be used on top of the +asymmetric crypto. + +This is optional. + +``` none +vyos@vyos:~$ generate pki wireguard preshared-key +Pre-shared key: OHH2EwZfMNK+1L6BXbYw3bKCtMrfjpR4mCAEeBlFnRs= +``` + +</div> + +<div class="opcmd"> + +generate pki wireguard preshared-key install interface \<interface\> peer \<peer\> + +An additional layer of symmetric-key crypto can be used on top of the +asymmetric crypto. This command automatically creates for you the required +CLI command to install this PSK for a given peer. + +This is optional. + +``` none +vyos@vyos:~$ generate pki wireguard preshared-key install interface wg10 peer foo +"generate" CLI command executed from operational level. +Generated preshared-key is not stored to CLI, use configure mode commands to install key: + +set interfaces wireguard wg10 peer foo preshared-key '32vQ1w1yFKTna8n7Gu7EimubSe2Y63m8bafz55EG3Ro=' + +Pre-shared key: +LuaZ8W6DjsDFJFX3jJzoNqrsXHhvq08JztM9z8LHCs= +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If this command is invoked from configure mode with the `run` +prefix the key is automatically installed to the appropriate interface: + +</div> + +</div> + +## Interface configuration + +The next step is to configure your local side as well as the policy based +trusted destination addresses. If you only initiate a connection, the listen +port and address/port is optional; however, if you act like a server and +endpoints initiate the connections to your system, you need to define a port +your clients can connect to, otherwise the port is randomly chosen and may +make connection difficult with firewall rules, since the port may be different +each time the system is rebooted. + +You will also need the public key of your peer as well as the network(s) you +want to tunnel (allowed-ips) to configure a WireGuard tunnel. The public key +below is always the public key from your peer, not your local one. + +**local side - commands** + +- WireGuard interface itself uses address 10.1.0.1/30 +- We only allow the 192.168.2.0/24 subnet to travel over the tunnel +- Our remote end of the tunnel for peer <span class="title-ref">to-wg02</span> is reachable at 192.0.2.1 + port 51820 +- The remote peer <span class="title-ref">to-wg02</span> uses XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI= + as its public key portion +- We listen on port 51820 +- We route all traffic for the 192.168.2.0/24 network to interface <span class="title-ref">wg01</span> + +``` none +set interfaces wireguard wg01 address '10.1.0.1/30' +set interfaces wireguard wg01 description 'VPN-to-wg02' +set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.2.0/24' +set interfaces wireguard wg01 peer to-wg02 address '192.0.2.1' +set interfaces wireguard wg01 peer to-wg02 port '51820' +set interfaces wireguard wg01 peer to-wg02 public-key 'XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI=' +set interfaces wireguard wg01 port '51820' + +set protocols static route 192.168.2.0/24 interface wg01 +``` + +The last step is to define an interface route for 192.168.2.0/24 to get through +the WireGuard interface <span class="title-ref">wg01</span>. Multiple IPs or networks can be defined and +routed. The last check is allowed-ips which either prevents or allows the +traffic. + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +You can not assign the same allowed-ips statement to multiple +WireGuard peers. This a design decision. For more information please +check the [WireGuard mailing list](https://lists.zx2c4.com/pipermail/wireguard/2018-December/003704.html). + +</div> + +<div class="cfgcmd"> + +set interfaces wireguard \<interface\> private-key \<private-key\> + +Associates the previously generated private key to a specific WireGuard +interface. The private key can be generate via the command + +`generate pki wireguard key-pair`. + +``` none +set interfaces wireguard wg01 private-key 'iJJyEARGK52Ls1GYRCcFvPuTj7WyWYDo//BknoDU0XY=' +``` + +The command `show interfaces wireguard wg01 public-key` will then show the +public key, which needs to be shared with the peer. + +</div> + +<div class="cmdinclude" var0="wireguard" var1="wg01"> + +/\_include/interface-per-client-thread.txt + +</div> + +**remote side - commands** + +``` none +set interfaces wireguard wg01 address '10.1.0.2/30' +set interfaces wireguard wg01 description 'VPN-to-wg01' +set interfaces wireguard wg01 peer to-wg01 allowed-ips '192.168.1.0/24' +set interfaces wireguard wg01 peer to-wg01 address '192.0.2.2' +set interfaces wireguard wg01 peer to-wg01 port '51820' +set interfaces wireguard wg01 peer to-wg01 public-key 'EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw=' +set interfaces wireguard wg01 port '51820' +set interfaces wireguard wg01 private-key 'OLTQY3HuK5qWDgVs6fJR093SwPgOmCKkDI1+vJLGoFU=' + +set protocols static route 192.168.1.0/24 interface wg01 +``` + +## Firewall Exceptions + +For the WireGuard traffic to pass through the WAN interface, you must create a +firewall exception. + +``` none +set firewall ipv4 name OUTSIDE_LOCAL rule 10 action accept +set firewall ipv4 name OUTSIDE_LOCAL rule 10 description 'Allow established/related' +set firewall ipv4 name OUTSIDE_LOCAL rule 10 state established enable +set firewall ipv4 name OUTSIDE_LOCAL rule 10 state related enable +set firewall ipv4 name OUTSIDE_LOCAL rule 20 action accept +set firewall ipv4 name OUTSIDE_LOCAL rule 20 description WireGuard_IN +set firewall ipv4 name OUTSIDE_LOCAL rule 20 destination port 51820 +set firewall ipv4 name OUTSIDE_LOCAL rule 20 log enable +set firewall ipv4 name OUTSIDE_LOCAL rule 20 protocol udp +``` + +You should also ensure that the OUTISDE_LOCAL firewall group is applied to the +WAN interface and in an input (local) direction. + +``` none +set firewall ipv4 input filter rule 10 action jump +set firewall ipv4 input filter rule 10 jump-target 'OUTSIDE_LOCAL' +set firewall ipv4 input filter rule 10 inbound-interface name 'eth0' +``` + +Assure that your firewall rules allow the traffic, in which case you have a +working VPN using WireGuard. + +``` none +wg01# ping 192.168.1.1 +PING 192.168.1.1 (192.168.1.1) 56(84) bytes of data. +64 bytes from 192.168.1.1: icmp_seq=1 ttl=64 time=1.16 ms +64 bytes from 192.168.1.1: icmp_seq=2 ttl=64 time=1.77 ms + +wg02# ping 192.168.2.1 +PING 192.168.2.1 (192.168.2.1) 56(84) bytes of data. +64 bytes from 192.168.2.1: icmp_seq=1 ttl=64 time=4.40 ms +64 bytes from 192.168.2.1: icmp_seq=2 ttl=64 time=1.02 ms +``` + +An additional layer of symmetric-key crypto can be used on top of the +asymmetric crypto. This is optional. + +``` none +vyos@vyos:~$ generate pki wireguard preshared-key +Pre-shared key: rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc= +``` + +Copy the key, as it is not stored on the local filesystem. Because it +is a symmetric key, only you and your peer should have knowledge of +its content. Make sure you distribute the key in a safe manner, + +``` none +wg01# set interfaces wireguard wg01 peer to-wg02 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=' +wg02# set interfaces wireguard wg01 peer to-wg01 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=' +``` + +## Remote Access "RoadWarrior" Example + +With WireGuard, a Road Warrior VPN config is similar to a site-to-site +VPN. It just lacks the `address` and `port` statements. + +In the following example, the IPs for the remote clients are defined in +the peers. This allows the peers to interact with one another. In +comparison to the site-to-site example the `persistent-keepalive` +flag is set to 15 seconds to assure the connection is kept alive. +This is mainly relevant if one of the peers is behind NAT and can't +be connected to if the connection is lost. To be effective this +value needs to be lower than the UDP timeout. + +``` none +wireguard wg01 { + address 10.172.24.1/24 + address 2001:db8:470:22::1/64 + description RoadWarrior + peer MacBook { + allowed-ips 10.172.24.30/32 + allowed-ips 2001:db8:470:22::30/128 + persistent-keepalive 15 + public-key F5MbW7ye7DsoxdOaixjdrudshjjxN5UdNV+pGFHqehc= + } + peer iPhone { + allowed-ips 10.172.24.20/32 + allowed-ips 2001:db8:470:22::20/128 + persistent-keepalive 15 + public-key BknHcLFo8nOo8Dwq2CjaC/TedchKQ0ebxC7GYn7Al00= + } + port 2224 + private-key OLTQY3HuK5qWDgVs6fJR093SwPgOmCKkDI1+vJLGoFU= +} +``` + +The following is the config for the iPhone peer above. It's important to +note that the `AllowedIPs` wildcard setting directs all IPv4 and IPv6 traffic +through the connection. + +``` none +[Interface] +PrivateKey = ARAKLSDJsadlkfjasdfiowqeruriowqeuasdf= +Address = 10.172.24.20/24, 2001:db8:470:22::20/64 +DNS = 10.0.0.53, 10.0.0.54 + +[Peer] +PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc= +AllowedIPs = 0.0.0.0/0, ::/0 +Endpoint = 192.0.2.1:2224 +PersistentKeepalive = 25 +``` + +However, split-tunneling can be achieved by specifying the remote subnets. +This ensures that only traffic destined for the remote site is sent over the +tunnel. All other traffic is unaffected. + +``` none +[Interface] +PrivateKey = 8Iasdfweirousd1EVGUk5XsT+wYFZ9mhPnQhmjzaJE6Go= +Address = 10.172.24.30/24, 2001:db8:470:22::30/64 + +[Peer] +PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc= +AllowedIPs = 10.172.24.30/24, 2001:db8:470:22::/64 +Endpoint = 192.0.2.1:2224 +PersistentKeepalive = 25 +``` + +## Operational Commands + +### Status + +<div class="opcmd"> + +show interfaces wireguard wg01 summary + +Show info about the Wireguard service. +It also shows the latest handshake. + +``` none +vyos@vyos:~$ show interfaces wireguard wg01 summary +interface: wg01 + public key: + private key: (hidden) + listening port: 51820 + +peer: <peer public-key> + endpoint: <peer public IP> + allowed ips: 10.69.69.2/32 + latest handshake: 23 hours, 45 minutes, 26 seconds ago + transfer: 1.26 MiB received, 6.47 MiB sent +``` + +</div> + +<div class="opcmd"> + +show interfaces wireguard + +Get a list of all wireguard interfaces + +``` none +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +wg01 10.0.0.1/24 u/u +``` + +</div> + +<div class="opcmd"> + +show interfaces wireguard \<interface\> + +Show general information about specific WireGuard interface + +``` none +vyos@vyos:~$ show interfaces wireguard wg01 +interface: wg01 + address: 10.0.0.1/24 + public key: h1HkYlSuHdJN6Qv4Hz4bBzjGg5WUty+U1L7DJsZy1iE= + private key: (hidden) + listening port: 41751 + + RX: bytes packets errors dropped overrun mcast + 0 0 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 0 0 0 0 0 0 +``` + +</div> + +## Remote Access "RoadWarrior" clients + +Some users tend to connect their mobile devices using WireGuard to their VyOS +router. To ease deployment one can generate a "per mobile" configuration from +the VyOS CLI. + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +From a security perspective, it is not recommended to let a third +party create and share the private key for a secured connection. +You should create the private portion on your own and only hand out the +public key. Please keep this in mind when using this convenience feature. + +</div> + +<div class="opcmd"> + +generate wireguard client-config \<name\> interface \<interface\> server +\<ip|fqdn\> address \<client-ip\> + +Using this command, you will create a new client configuration which can +connect to `interface` on this router. The public key from the specified +interface is automatically extracted and embedded into the configuration. + +The command also generates a configuration snipped which can be copy/pasted +into the VyOS CLI if needed. The supplied `<name>` on the CLI will become +the peer name in the snippet. + +In addition you will specifiy the IP address or FQDN for the client where it +will connect to. The address parameter can be used up to two times and is used +to assign the clients specific IPv4 (/32) or IPv6 (/128) address. + +<figure> +<img src="/_static/images/wireguard_qrcode.webp" alt="WireGuard Client QR code" /> +</figure> + +</div> diff --git a/docs/configuration/interfaces/md-wireless.md b/docs/configuration/interfaces/md-wireless.md new file mode 100644 index 00000000..4a09b78b --- /dev/null +++ b/docs/configuration/interfaces/md-wireless.md @@ -0,0 +1,823 @@ +lastproofread +2023-01-26 + +# WLAN/WIFI - Wireless LAN + +`WLAN (Wireless LAN)` interface provide 802.11 (a/b/g/n/ac) wireless +support (commonly referred to as Wi-Fi) by means of compatible hardware. If your +hardware supports it, VyOS supports multiple logical wireless interfaces per +physical device. + +There are three modes of operation for a wireless interface: + +- `WAP (Wireless Access-Point)` provides network access to connecting + stations if the physical hardware supports acting as a WAP +- A station acts as a Wi-Fi client accessing the network through an available + WAP +- Monitor, the system passively monitors any kind of wireless traffic + +If the system detects an unconfigured wireless device, it will be automatically +added the configuration tree, specifying any detected settings (for example, +its MAC address) and configured to run in monitor mode. + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="wireless" var1="wlan0"> + +/\_include/interface-common-with-dhcp.txt + +</div> + +### Wireless options + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> channel \<number\> + +Channel number (IEEE 802.11), for 2.4Ghz (802.11 b/g/n) channels range from +1-14. On 5Ghz (802.11 a/h/j/n/ac) channels available are 0, 34 to 173 + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> country-code \<cc\> + +Country code (ISO/IEC 3166-1). Used to set regulatory domain. Set as needed +to indicate country in which device is operating. This can limit available +channels and transmit power. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +This option is mandatory in Access-Point mode. + +</div> + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> disable-broadcast-ssid + +Send empty SSID in beacons and ignore probe request frames that do not specify +full SSID, i.e., require stations to know SSID. + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> expunge-failing-stations + +Disassociate stations based on excessive transmission failures or other +indications of connection loss. + +This depends on the driver capabilities and may not be available with all +drivers. + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> isolate-stations + +Client isolation can be used to prevent low-level bridging of frames between +associated stations in the BSS. + +By default, this bridging is allowed. + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> max-stations + +Maximum number of stations allowed in station table. New stations will be +rejected after the station table is full. IEEE 802.11 has a limit of 2007 +different association IDs, so this number should not be larger than that. + +This defaults to 2007. + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> mgmt-frame-protection + +Management Frame Protection (MFP) according to IEEE 802.11w + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> mode \<a | b | g | n | ac\> + +Operation mode of wireless radio. + +- `a` - 802.11a - 54 Mbits/sec +- `b` - 802.11b - 11 Mbits/sec +- `g` - 802.11g - 54 Mbits/sec (default) +- `n` - 802.11n - 600 Mbits/sec +- `ac` - 802.11ac - 1300 Mbits/sec + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> physical-device \<device\> + +Wireless hardware device used as underlay radio. + +This defaults to phy0. + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> reduce-transmit-power \<number\> + +Add Power Constraint element to Beacon and Probe Response frames. + +This option adds Power Constraint element when applicable and Country element +is added. Power Constraint element is required by Transmit Power Control. + +Valid values are 0..255. + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> ssid \<ssid\> + +SSID to be used in IEEE 802.11 management frames + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> type +\<access-point | station | monitor\> + +Wireless device type for this interface + +- `access-point` - Access-point forwards packets between other nodes +- `station` - Connects to another access point +- `monitor` - Passively monitor all packets on the frequency/channel + +</div> + +<div class="cmdinclude" var0="wireless" var1="wlan0"> + +/\_include/interface-per-client-thread.txt + +</div> + +#### PPDU + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities require-ht + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities require-hvt + +</div> + +##### HT (High Throughput) capabilities (802.11n) + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht 40mhz-incapable + +Device is incapable of 40 MHz, do not advertise. This sets `[40-INTOLERANT]` + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht auto-powersave + +WMM-PS Unscheduled Automatic Power Save Delivery \[U-APSD\] + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht +channel-set-width \<ht20 | ht40+ | ht40-\> + +Supported channel width set. + +- `ht40-` - Both 20 MHz and 40 MHz with secondary channel below the primary + channel +- `ht40+` - Both 20 MHz and 40 MHz with secondary channel above the primary + channel + +<div class="note"> + +<div class="title"> + +Note + +</div> + +There are limits on which channels can be used with HT40- and HT40+. +Following table shows the channels that may be available for HT40- and HT40+ +use per IEEE 802.11n Annex J: + +Depending on the location, not all of these channels may be available for +use! + +``` none +freq HT40- HT40+ +2.4 GHz 5-13 1-7 (1-9 in Europe/Japan) +5 GHz 40,48,56,64 36,44,52,60 +``` + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +40 MHz channels may switch their primary and secondary channels if +needed or creation of 40 MHz channel maybe rejected based on overlapping +BSSes. These changes are done automatically when hostapd is setting up the +40 MHz channel. + +</div> + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht +delayed-block-ack + +Enable HT-delayed Block Ack `[DELAYED-BA]` + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht dsss-cck-40 + +DSSS/CCK Mode in 40 MHz, this sets `[DSSS_CCK-40]` + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht greenfield + +This enables the greenfield option which sets the `[GF]` option + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht ldpc + +Enable LDPC coding capability + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht lsig-protection + +Enable L-SIG TXOP protection capability + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht max-amsdu +\<3839 | 7935\> + +Maximum A-MSDU length 3839 (default) or 7935 octets + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht +short-gi \<20 | 40\> + +Short GI capabilities for 20 and 40 MHz + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht +smps \<static | dynamic\> + +Spatial Multiplexing Power Save (SMPS) settings + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht stbc rx \<num\> + +Enable receiving PPDU using STBC (Space Time Block Coding) + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities ht stbc tx + +Enable sending PPDU using STBC (Space Time Block Coding) + +</div> + +##### VHT (Very High Throughput) capabilities (802.11ac) + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht antenna-count + +Number of antennas on this card + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht +antenna-pattern-fixed + +Set if antenna pattern does not change during the lifetime of an association + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht beamform +\<single-user-beamformer | single-user-beamformee | multi-user-beamformer | +multi-user-beamformee\> + +Beamforming capabilities: + +- `single-user-beamformer` - Support for operation as single user beamformer +- `single-user-beamformee` - Support for operation as single user beamformee +- `multi-user-beamformer` - Support for operation as single user beamformer +- `multi-user-beamformee` - Support for operation as single user beamformer + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht +center-channel-freq \<freq-1 | freq-2\> \<number\> + +VHT operating channel center frequency - center freq 1 +(for use with 80, 80+80 and 160 modes) + +VHT operating channel center frequency - center freq 2 +(for use with the 80+80 mode) + +\<number\> must be from 34 - 173. For 80 MHz channels it should be channel + 6. + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht +channel-set-width \<0 | 1 | 2 | 3\> + +- `0` - 20 or 40 MHz channel width (default) +- `1` - 80 MHz channel width +- `2` - 160 MHz channel width +- `3` - 80+80 MHz channel width + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht ldpc + +Enable LDPC (Low Density Parity Check) coding capability + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht link-adaptation + +VHT link adaptation capabilities + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht +max-mpdu \<value\> + +Increase Maximum MPDU length to 7991 or 11454 octets (default 3895 octets) + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht +max-mpdu-exp \<value\> + +Set the maximum length of A-MPDU pre-EOF padding that the station can receive + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht +short-gi \<80 | 160\> + +Short GI capabilities + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht stbc rx \<num\> + +Enable receiving PPDU using STBC (Space Time Block Coding) + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht stbc tx + +Enable sending PPDU using STBC (Space Time Block Coding) + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht tx-powersave + +Enable VHT TXOP Power Save Mode + +</div> + +<div class="cfgcmd"> + +set interfaces wireless \<interface\> capabilities vht vht-cf + +Station supports receiving VHT variant HT Control field + +</div> + +### Wireless options (Station/Client) + +The example creates a wireless station (commonly referred to as Wi-Fi client) +that accesses the network through the WAP defined in the above example. The +default physical device (`phy0`) is used. + +``` none +set interfaces wireless wlan0 type station +set interfaces wireless wlan0 address dhcp +set interfaces wireless wlan0 country-code de +set interfaces wireless wlan0 ssid Test +set interfaces wireless wlan0 security wpa passphrase '12345678' +``` + +Resulting in + +``` none +interfaces { + [...] + wireless wlan0 { + address dhcp + country-code de + security { + wpa { + passphrase "12345678" + } + } + ssid TEST + type station + } +``` + +### Security + +`WPA (Wi-Fi Protected Access)` and WPA2 Enterprise in combination with +802.1x based authentication can be used to authenticate users or computers +in a domain. + +The wireless client (supplicant) authenticates against the RADIUS server +(authentication server) using an `EAP (Extensible Authentication +Protocol)` method configured on the RADIUS server. The WAP (also referred +to as authenticator) role is to send all authentication messages between the +supplicant and the configured authentication server, thus the RADIUS server +is responsible for authenticating the users. + +The WAP in this example has the following characteristics: + +- IP address `192.168.2.1/24` +- Network ID (SSID) `Enterprise-TEST` +- WPA passphrase `12345678` +- Use 802.11n protocol +- Wireless channel `1` +- RADIUS server at `192.168.3.10` with shared-secret `VyOSPassword` + +``` none +set interfaces wireless wlan0 address '192.168.2.1/24' +set interfaces wireless wlan0 country-code de +set interfaces wireless wlan0 type access-point +set interfaces wireless wlan0 channel 1 +set interfaces wireless wlan0 mode n +set interfaces wireless wlan0 ssid 'TEST' +set interfaces wireless wlan0 security wpa mode wpa2 +set interfaces wireless wlan0 security wpa cipher CCMP +set interfaces wireless wlan0 security wpa radius server 192.168.3.10 key 'VyOSPassword' +set interfaces wireless wlan0 security wpa radius server 192.168.3.10 port 1812 +``` + +Resulting in + +``` none +interfaces { + [...] + wireless wlan0 { + address 192.168.2.1/24 + country-code de + channel 1 + mode n + security { + wpa { + cipher CCMP + mode wpa2 + radius { + server 192.168.3.10 { + key 'VyOSPassword' + port 1812 + } + } + } + } + ssid "Enterprise-TEST" + type access-point + } +} +``` + +### VLAN + +#### Regular VLANs (802.1q) + +<div class="cmdinclude" var0="wireless" var1="wlan0"> + +/\_include/interface-vlan-8021q.txt + +</div> + +#### QinQ (802.1ad) + +<div class="cmdinclude" var0="wireless" var1="wlan0"> + +/\_include/interface-vlan-8021ad.txt + +</div> + +## Operation + +<div class="opcmd"> + +show interfaces wireless info + +</div> + +Use this command to view operational status and wireless-specific information +about all wireless interfaces. + +``` none +vyos@vyos:~$ show interfaces wireless info +Interface Type SSID Channel +wlan0 access-point VyOS-TEST-0 1 +``` + +<div class="opcmd"> + +show interfaces wireless detail + +</div> + +Use this command to view operational status and details wireless-specific +information about all wireless interfaces. + +``` none +vyos@vyos:~$ show interfaces wireless detail +wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 + link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff + inet xxx.xxx.99.254/24 scope global wlan0 + valid_lft forever preferred_lft forever + inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 66072 282 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 83413 430 0 0 0 0 + +wlan1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 + link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff + inet xxx.xxx.100.254/24 scope global wlan0 + valid_lft forever preferred_lft forever + inet6 fe80::xxxx:xxxx:ffff:2ed3/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 166072 5282 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 183413 5430 0 0 0 0 +``` + +<div class="opcmd"> + +show interfaces wireless \<wlanX\> + +</div> + +This command shows both status and statistics on the specified wireless +interface. The wireless interface identifier can range from wlan0 to wlan999. + +``` none +vyos@vyos:~$ show interfaces wireless wlan0 +wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 + link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff + inet xxx.xxx.99.254/24 scope global wlan0 + valid_lft forever preferred_lft forever + inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 66072 282 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 83413 430 0 0 0 0 +``` + +<div class="opcmd"> + +show interfaces wireless \<wlanX\> brief + +</div> + +This command gives a brief status overview of a specified wireless interface. +The wireless interface identifier can range from wlan0 to wlan999. + +``` none +vyos@vyos:~$ show interfaces wireless wlan0 brief +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +wlan0 192.168.2.254/24 u/u +``` + +<div class="opcmd"> + +show interfaces wireless \<wlanX\> queue + +</div> + +Use this command to view wireless interface queue information. +The wireless interface identifier can range from wlan0 to wlan999. + +``` none +vyos@vyos:~$ show interfaces wireless wlan0 queue +qdisc pfifo_fast 0: root bands 3 priomap 1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1 + Sent 810323 bytes 6016 pkt (dropped 0, overlimits 0 requeues 0) + rate 0bit 0pps backlog 0b 0p requeues 0 +``` + +<div class="opcmd"> + +show interfaces wireless \<wlanX\> scan + +</div> + +This command is used to retrieve information about WAP within the range of your +wireless interface. This command is useful on wireless interfaces configured +in station mode. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Scanning is not supported on all wireless drivers and wireless +hardware. Refer to your driver and wireless hardware documentation for +further details. + +</div> + +``` none +vyos@vyos:~$ show interfaces wireless wlan0 scan +Address SSID Channel Signal (dbm) +00:53:3b:88:6e:d8 WLAN-576405 1 -64.00 +00:53:3b:88:6e:da Telekom_FON 1 -64.00 +00:53:00:f2:c2:a4 BabyView_F2C2A4 6 -60.00 +00:53:3b:88:6e:d6 Telekom_FON 100 -72.00 +00:53:3b:88:6e:d4 WLAN-576405 100 -71.00 +00:53:44:a4:96:ec KabelBox-4DC8 56 -81.00 +00:53:d9:7a:67:c2 WLAN-741980 1 -75.00 +00:53:7c:99:ce:76 Vodafone Homespot 1 -86.00 +00:53:44:a4:97:21 KabelBox-4DC8 1 -78.00 +00:53:44:a4:97:21 Vodafone Hotspot 1 -79.00 +00:53:44:a4:97:21 Vodafone Homespot 1 -79.00 +00:53:86:40:30:da Telekom_FON 1 -86.00 +00:53:7c:99:ce:76 Vodafone Hotspot 1 -86.00 +00:53:44:46:d2:0b Vodafone Hotspot 1 -87.00 +``` + +## Examples + +The following example creates a WAP. When configuring multiple WAP interfaces, +you must specify unique IP addresses, channels, Network IDs commonly referred +to as `SSID (Service Set Identifier)`, and MAC addresses. + +The WAP in this example has the following characteristics: + +- IP address `192.168.2.1/24` +- Network ID (SSID) `TEST` +- WPA passphrase `12345678` +- Use 802.11n protocol +- Wireless channel `1` + +``` none +set interfaces wireless wlan0 address '192.168.2.1/24' +set interfaces wireless wlan0 type access-point +set interfaces wireless wlan0 channel 1 +set interfaces wireless wlan0 mode n +set interfaces wireless wlan0 ssid 'TEST' +set interfaces wireless wlan0 security wpa mode wpa2 +set interfaces wireless wlan0 security wpa cipher CCMP +set interfaces wireless wlan0 security wpa passphrase '12345678' +set interfaces wireless wlan0 country-code de +``` + +Resulting in + +``` none +interfaces { + [...] + wireless wlan0 { + address 192.168.2.1/24 + channel 1 + country-code de + mode n + security { + wpa { + cipher CCMP + mode wpa2 + passphrase "12345678" + } + } + ssid "TEST" + type access-point + } +} +system { + [...] + wifi-regulatory-domain DE +} +``` + +To get it to work as an access point with this configuration you will need +to set up a DHCP server to work with that network. You can - of course - also +bridge the Wireless interface with any configured bridge +(`bridge-interface`) on the system. + +### Intel AX200 + +The Intel AX200 card does not work out of the box in AP mode, see +<https://unix.stackexchange.com/questions/598275/intel-ax200-ap-mode>. You can +still put this card into AP mode using the following configuration: + +``` none +set interfaces wireless wlan0 channel '1' +set interfaces wireless wlan0 country-code 'us' +set interfaces wireless wlan0 mode 'n' +set interfaces wireless wlan0 physical-device 'phy0' +set interfaces wireless wlan0 ssid 'VyOS' +set interfaces wireless wlan0 type 'access-point' +``` diff --git a/docs/configuration/interfaces/md-wwan.md b/docs/configuration/interfaces/md-wwan.md new file mode 100644 index 00000000..2475e809 --- /dev/null +++ b/docs/configuration/interfaces/md-wwan.md @@ -0,0 +1,390 @@ +lastproofread +2023-01-27 + +# WWAN - Wireless Wide-Area-Network + +The Wireless Wide-Area-Network interface provides access (through a wireless +modem/wwan) to wireless networks provided by various cellular providers. + +VyOS uses the <span class="title-ref">interfaces wwan</span> subsystem for configuration. + +## Configuration + +### Common interface configuration + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-address-with-dhcp.txt + +</div> + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-description.txt + +</div> + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-disable.txt + +</div> + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-disable-link-detect.txt + +</div> + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-mtu.txt + +</div> + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-ip.txt + +</div> + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-ipv6.txt + +</div> + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-vrf.txt + +</div> + +**DHCP(v6)** + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-dhcp-options.txt + +</div> + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-dhcpv6-options.txt + +</div> + +<div class="cmdinclude" var0="wwan" var1="wwan0"> + +/\_include/interface-dhcpv6-prefix-delegation.txt + +</div> + +### WirelessModem (WWAN) options + +<div class="cfgcmd"> + +set interfaces wwan \<interface\> apn \<apn\> + +Every WWAN connection requires an `APN (Access Point Name)` which is +used by the client to dial into the ISPs network. This is a mandatory +parameter. Contact your Service Provider for correct APN. + +</div> + +## Operation + +<div class="opcmd"> + +show interfaces wwan \<interface\> + +Show detailed information on given <span class="title-ref">\<interface\></span> + +``` none +vyos@vyos:~$ show interfaces wwan wwan0 +wwan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 1000 + link/ether 02:c2:f3:00:01:02 brd ff:ff:ff:ff:ff:ff + inet 10.155.144.12/30 brd 10.155.144.15 scope global dynamic wwan0 + valid_lft 7012sec preferred_lft 7012sec + inet6 fe80::c2:f3ff:fe00:0102/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 640 2 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 3229 16 0 0 0 0 +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> summary + +Show detailed information summary on given <span class="title-ref">\<interface\></span> + +``` none +vyos@vyos:~$ show interfaces wwan wwan0 summary + -------------------------------- + General | dbus path: /org/freedesktop/ModemManager1/Modem/0 + | device id: 79f4e9cc2e9fc8d4a3b8c8f6327c2e363170194d + -------------------------------- + Hardware | manufacturer: Sierra Wireless, Incorporated + | model: MC7710 + | revision: SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15 + | h/w revision: 1.0 + | supported: gsm-umts, lte + | current: gsm-umts, lte + | equipment id: 358xxxxxxxxxxxx + -------------------------------- + System | device: /sys/devices/pci0000:00/0000:00:13.0/usb3/3-1/3-1.3 + | drivers: qcserial, qmi_wwan + | plugin: Generic + | primary port: cdc-wdm0 + | ports: ttyUSB0 (qcdm), ttyUSB2 (at), cdc-wdm0 (qmi), wwan0 (net) + -------------------------------- + Numbers | own: 4917xxxxxxxx + -------------------------------- + Status | lock: sim-pin2 + | unlock retries: sim-pin (3), sim-pin2 (3), sim-puk (10), sim-puk2 (10) + | state: connected + | power state: on + | access tech: lte + | signal quality: 63% (recent) + -------------------------------- + Modes | supported: allowed: 2g; preferred: none + | allowed: 3g; preferred: none + | allowed: 4g; preferred: none + | allowed: 2g, 3g; preferred: 3g + | allowed: 2g, 3g; preferred: 2g + | allowed: 2g, 4g; preferred: 4g + | allowed: 2g, 4g; preferred: 2g + | allowed: 3g, 4g; preferred: 3g + | allowed: 3g, 4g; preferred: 4g + | allowed: 2g, 3g, 4g; preferred: 4g + | allowed: 2g, 3g, 4g; preferred: 3g + | allowed: 2g, 3g, 4g; preferred: 2g + | current: allowed: 2g, 3g, 4g; preferred: 2g + -------------------------------- + Bands | supported: egsm, dcs, pcs, utran-1, utran-8, eutran-1, eutran-3, + | eutran-7, eutran-8, eutran-20 + | current: egsm, dcs, pcs, utran-1, utran-8, eutran-1, eutran-3, + | eutran-7, eutran-8, eutran-20 + -------------------------------- + IP | supported: ipv4, ipv6, ipv4v6 + -------------------------------- + 3GPP | imei: 358xxxxxxxxxxxx + | operator id: 26201 + | operator name: Telekom.de + | registration: home + -------------------------------- + 3GPP EPS | ue mode of operation: ps-1 + -------------------------------- + SIM | dbus path: /org/freedesktop/ModemManager1/SIM/0 + -------------------------------- + Bearer | dbus path: /org/freedesktop/ModemManager1/Bearer/0 +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> capabilities + +Show WWAN module hardware capabilities. + +``` none +vyos@vyos:~$ show interfaces wwan wwan0 capabilities +Max TX channel rate: '50000000' +Max RX channel rate: '100000000' +Data Service: 'simultaneous-cs-ps' +SIM: 'supported' +Networks: 'gsm, umts, lte' +Bands: 'gsm-dcs-1800, gsm-900-extended, gsm-900-primary, gsm-pcs-1900, wcdma-2100, wcdma-900' +LTE bands: '1, 3, 7, 8, 20' +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> firmware + +Show WWAN module firmware. + +``` none +vyos@vyos:~$ show interfaces wwan wwan0 firmware +Model: MC7710 +Boot version: SWI9200X_03.05.29.03bt r6485 CNSHZ-ED-XP0031 2014/12/02 17:33:08 +AMSS version: SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15 +SKU ID: unknown +Package ID: unknown +Carrier ID: 0 +Config version: unknown +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> imei + +Show WWAN module IMEI. + +``` none +vyos@vyos:~$ show interfaces wwan wwan0 imei +ESN: '0' +IMEI: '358xxxxxxxxxxxx' +MEID: 'unknown' +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> imsi + +Show WWAN module IMSI. + +``` none +vyos@vyos:~$ show interfaces wwan wwan0 imsi +IMSI: '262xxxxxxxxxxxx' +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> model + +Show WWAN module model. + +``` none +vyos@vyos:~$ show interfaces wwan wwan0 model +Model: 'MC7710' +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> msisdn + +Show WWAN module MSISDN. + +``` none +vyos@vyos:~$ show interfaces wwan wwan0 msisdn +MSISDN: '4917xxxxxxxx' +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> revision + +Show WWAN module hardware revision. + +``` none +vyos@vyos:~$ show interfaces wwan wwan0 revision +Revision: 'SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15' +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> signal + +Show WWAN module signal strength. + +``` none +vyos@vyos:~$ show interfaces wwan wwan0 signal +LTE: +RSSI: '-74 dBm' +RSRQ: '-7 dB' +RSRP: '-100 dBm' +SNR: '13.0 dB' +Radio Interface: 'lte' +Active Band Class: 'eutran-3' +Active Channel: '1300' +``` + +</div> + +<div class="opcmd"> + +show interfaces wwan \<interface\> sim + +Show WWAN module SIM card information. + +``` none +vyos@vyos:~$ show interfaces wwan wwan0 sim +Provisioning applications: +Primary GW: slot '1', application '1' +Primary 1X: session doesn't exist +Secondary GW: session doesn't exist +Secondary 1X: session doesn't exist +Slot [1]: +Card state: 'present' +UPIN state: 'not-initialized' +UPIN retries: '0' +UPUK retries: '0' +Application [1]: +Application type: 'usim (2)' +Application state: 'ready' +Application ID: +A0:00:00:00:87:10:02:FF:49:94:20:89:03:10:00:00 +Personalization state: 'ready' +UPIN replaces PIN1: 'no' +PIN1 state: 'disabled' +PIN1 retries: '3' +PUK1 retries: '10' +PIN2 state: 'enabled-not-verified' +PIN2 retries: '3' +PUK2 retries: '10' +``` + +</div> + +## Example + +The following example is based on a Sierra Wireless MC7710 miniPCIe card (only +the form factor in reality it runs UBS) and Deutsche Telekom as ISP. The card +is assembled into a `pc-engines-apu4`. + +``` none +set interfaces wwan wwan0 apn 'internet.telekom' +set interfaces wwan wwan0 address 'dhcp' +``` + +## Supported Modules + +The following hardware modules have been tested successfully in an +`pc-engines-apu4` board: + +- Sierra Wireless AirPrime MC7304 miniPCIe card (LTE) +- Sierra Wireless AirPrime MC7430 miniPCIe card (LTE) +- Sierra Wireless AirPrime MC7455 miniPCIe card (LTE) +- Sierra Wireless AirPrime MC7710 miniPCIe card (LTE) +- Huawei ME909u-521 miniPCIe card (LTE) +- Huawei ME909s-120 miniPCIe card (LTE) +- HP LT4120 Snapdragon X5 LTE + +## Firmware Update + +All available WWAN cards have a build in, reprogrammable firmware. Most of the +vendors provide a regular update to the firmware used in the baseband chip. + +As VyOS makes use of the QMI interface to connect to the WWAN modem cards, also +the firmware can be reprogrammed. + +To update the firmware, VyOS also ships the <span class="title-ref">qmi-firmware-update</span> binary. To +upgrade the firmware of an e.g. Sierra Wireless MC7710 module to the firmware +provided in the file `9999999_9999999_9200_03.05.14.00_00_generic_000.000_001_SPKG_MC.cwe` +use the following command: + +``` bash +$ sudo qmi-firmware-update --update -d 1199:68a2 \ + 9999999_9999999_9200_03.05.14.00_00_generic_000.000_001_SPKG_MC.cwe +``` diff --git a/docs/configuration/loadbalancing/md-index.md b/docs/configuration/loadbalancing/md-index.md new file mode 100644 index 00000000..5526c11d --- /dev/null +++ b/docs/configuration/loadbalancing/md-index.md @@ -0,0 +1,8 @@ +# Load-balancing + +<div class="toctree" maxdepth="1" includehidden=""> + +wan +reverse-proxy + +</div> diff --git a/docs/configuration/loadbalancing/md-reverse-proxy.md b/docs/configuration/loadbalancing/md-reverse-proxy.md new file mode 100644 index 00000000..0e4ebe77 --- /dev/null +++ b/docs/configuration/loadbalancing/md-reverse-proxy.md @@ -0,0 +1,552 @@ +# Reverse-proxy + +VyOS reverse-proxy is balancer and proxy server that provides +high-availability, load balancing and proxying for TCP (level 4) +and HTTP-based (level 7) applications. + +## Configuration + +Service configuration is responsible for binding to a specific port, +while the backend configuration determines the type of load balancing +to be applied and specifies the real servers to be utilized. + +### Service + +<div class="cfgcmd"> + +set load-balancing reverse-proxy service \<name\> listen-address +\<address\> + +Set service to bind on IP address, by default listen on any IPv4 and IPv6 + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy service \<name\> port +\<port\> + +Create service <span class="title-ref">\<name\></span> to listen on \<port\> + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy service \<name\> mode +\<tcp|http\> + +Configure service <span class="title-ref">\<name\></span> mode TCP or HTTP + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy service \<name\> backend +\<name\> + +Configure service <span class="title-ref">\<name\></span> to use the backend \<name\> + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy service \<name\> ssl +certificate \<name\> + +Set SSL certificate \<name\> for service \<name\> + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy service \<name\> +http-response-headers \<header-name\> value \<header-value\> + +Set custom HTTP headers to be included in all responses + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy service \<name\> logging facility +\<facility\> level \<level\> + +Specify facility and level for logging. +For an explanation on `syslog_facilities` and `syslog_severity_level` +see tables in syslog configuration section. + +</div> + +#### Rules + +Rules allow to control and route incoming traffic to specific backend based +on predefined conditions. Rules allow to define matching criteria and +perform action accordingly. + +<div class="cfgcmd"> + +set load-balancing reverse-proxy service \<name\> rule \<rule\> +domain-name \<name\> + +Match domain name + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy service \<name\> rule \<rule\> +ssl \<sni\> + +SSL match Server Name Indication (SNI) option: +- `req-ssl-sni` SSL Server Name Indication (SNI) request match + +- `ssl-fc-sni` SSL frontend connection Server Name Indication match + +- `ssl-fc-sni-end` SSL frontend match end of connection Server Name + + > Indication + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy service \<name\> rule \<rule\> +url-path \<match\> \<url\> + +Allows to define URL path matching rules for a specific service. + +With this command, you can specify how the URL path should be matched +against incoming requests. + +The available options for \<match\> are: +- `begin` Matches the beginning of the URL path +- `end` Matches the end of the URL path. +- `exact` Requires an exactly match of the URL path + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy service \<name\> rule \<rule\> +set backend \<name\> + +Assign a specific backend to a rule + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy service \<name\> rule \<rule\> +redirect-location \<url\> + +Redirect URL to a new location + +</div> + +### Backend + +<div class="cfgcmd"> + +set load-balancing reverse-proxy backend \<name\> balance +\<balance\> + +Load-balancing algorithms to be used for distributed requests among the +available servers + +Balance algorithms: +- `source-address` Distributes requests based on the source IP address + of the client +- `round-robin` Distributes requests in a circular manner, + sequentially sending each request to the next server in line +- `least-connection` Distributes requests to the server with the fewest + active connections + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy backend \<name\> mode +\<mode\> + +Configure backend <span class="title-ref">\<name\></span> mode TCP or HTTP + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy backend \<name\> server +\<name\> address \<x.x.x.x\> + +Set the address of the backend server to which the incoming traffic will +be forwarded + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy backend \<name\> server +\<name\> port \<port\> + +Set the address of the backend port + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy backend \<name\> server +\<name\> check + +Active health check backend server + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy backend \<name\> server +\<name\> send-proxy + +Send a Proxy Protocol version 1 header (text format) + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy backend \<name\> server +\<name\> send-proxy-v2 + +Send a Proxy Protocol version 2 header (binary format) + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy backend \<name\> ssl +ca-certificate \<ca-certificate\> + +Configure requests to the backend server to use SSL encryption and +authenticate backend against \<ca-certificate\> + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy backend \<name\> ssl no-verify + +Configure requests to the backend server to use SSL encryption without +validating server certificate + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy backend \<name\> +http-response-headers \<header-name\> value \<header-value\> + +Set custom HTTP headers to be included in all responses using the backend + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy backend \<name\> logging facility +\<facility\> level \<level\> + +Specify facility and level for logging. +For an explanation on `syslog_facilities` and `syslog_severity_level` +see tables in syslog configuration section. + +</div> + +### Global + +Global parameters + +<div class="cfgcmd"> + +set load-balancing reverse-proxy global-parameters max-connections +\<num\> + +Limit maximum number of connections + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy global-parameters ssl-bind-ciphers +\<ciphers\> + +Limit allowed cipher algorithms used during SSL/TLS handshake + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy global-parameters tls-version-min +\<version\> + +Specify the minimum required TLS version 1.2 or 1.3 + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy global-parameters logging +facility \<facility\> level \<level\> + +Specify facility and level for logging. +For an explanation on `syslog_facilities` and `syslog_severity_level` +see tables in syslog configuration section. + +</div> + +## Health checks + +### HTTP checks + +For web application providing information about their state HTTP health +checks can be used to determine their availability. + +<div class="cfgcmd"> + +set load-balancing reverse-proxy backend \<name\> http-check + +Enables HTTP health checks using OPTION HTTP requests against '/' and +expecting a successful response code in the 200-399 range. + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy backend \<name\> http-check +method \<method\> + +Sets the HTTP method to be used, can be either: option, get, post, put + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy backend \<name\> http-check +uri \<path\> + +Sets the endpoint to be used for health checks + +</div> + +<div class="cfgcmd"> + +set load-balancing reverse-proxy backend \<name\> http-check +expect \<condition\> + +Sets the expected result condition for considering a server healthy. + +Some possible examples are: +- `status 200` Expecting a 200 response code +- `status 200-399` Expecting a non-failure response code +- `string success` Expecting the string <span class="title-ref">success</span> in the response body + +</div> + +### TCP checks + +Health checks can also be configured for TCP mode backends. You can configure +protocol aware checks for a range of Layer 7 protocols: + +<div class="cfgcmd"> + +set load-balancing reverse-proxy backend \<name\> health-check \<protocol\> + +Available health check protocols: +- `ldap` LDAP protocol check. +- `redis` Redis protocol check. +- `mysql` MySQL protocol check. +- `pgsql` PostgreSQL protocol check. +- `smtp` SMTP protocol check. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you specify a server to be checked but do not configure a +protocol, a basic TCP health check will be attempted. A server shall be +deemed online if it responses to a connection attempt with a valid +`SYN/ACK` packet. + +</div> + +## Redirect HTTP to HTTPS + +Configure the load-balancing reverse-proxy service for HTTP. + +This configuration listen on port 80 and redirect incoming +requests to HTTPS: + +``` none +set load-balancing reverse-proxy service http port '80' +set load-balancing reverse-proxy service http redirect-http-to-https +``` + +The name of the service can be different, in this example it is only for +convenience. + +## Examples + +### Level 4 balancing + +This configuration enables the TCP reverse proxy for the "my-tcp-api" service. +Incoming TCP connections on port 8888 will be load balanced across the backend +servers (srv01 and srv02) using the round-robin load-balancing algorithm. + +``` none +set load-balancing reverse-proxy service my-tcp-api backend 'bk-01' +set load-balancing reverse-proxy service my-tcp-api mode 'tcp' +set load-balancing reverse-proxy service my-tcp-api port '8888' + +set load-balancing reverse-proxy backend bk-01 balance 'round-robin' +set load-balancing reverse-proxy backend bk-01 mode 'tcp' + +set load-balancing reverse-proxy backend bk-01 server srv01 address '192.0.2.11' +set load-balancing reverse-proxy backend bk-01 server srv01 port '8881' +set load-balancing reverse-proxy backend bk-01 server srv02 address '192.0.2.12' +set load-balancing reverse-proxy backend bk-01 server srv02 port '8882' +``` + +### Balancing based on domain name + +The following configuration demonstrates how to use VyOS +to achieve load balancing based on the domain name. + +The HTTP service listen on TCP port 80. + +Rule 10 matches requests with the domain name `node1.example.com` forwards +to the backend `bk-api-01` + +Rule 20 matches requests with the domain name `node2.example.com` forwards +to the backend `bk-api-02` + +``` none +set load-balancing reverse-proxy service http description 'bind app listen on 443 port' +set load-balancing reverse-proxy service http mode 'tcp' +set load-balancing reverse-proxy service http port '80' + +set load-balancing reverse-proxy service http rule 10 domain-name 'node1.example.com' +set load-balancing reverse-proxy service http rule 10 set backend 'bk-api-01' +set load-balancing reverse-proxy service http rule 20 domain-name 'node2.example.com' +set load-balancing reverse-proxy service http rule 20 set backend 'bk-api-02' + +set load-balancing reverse-proxy backend bk-api-01 description 'My API-1' +set load-balancing reverse-proxy backend bk-api-01 mode 'tcp' +set load-balancing reverse-proxy backend bk-api-01 server api01 address '127.0.0.1' +set load-balancing reverse-proxy backend bk-api-01 server api01 port '4431' +set load-balancing reverse-proxy backend bk-api-02 description 'My API-2' +set load-balancing reverse-proxy backend bk-api-02 mode 'tcp' +set load-balancing reverse-proxy backend bk-api-02 server api01 address '127.0.0.2' +set load-balancing reverse-proxy backend bk-api-02 server api01 port '4432' +``` + +### Terminate SSL + +The following configuration terminates SSL on the router. + +The `http` service is listens on port 80 and force redirects from HTTP to +HTTPS. + +The `https` service listens on port 443 with backend `bk-default` to +handle HTTPS traffic. It uses certificate named `cert` for SSL termination. +HSTS header is set with a 1-year expiry, to tell browsers to always use SSL for site. + +Rule 10 matches requests with the exact URL path `/.well-known/xxx` +and redirects to location `/certs/`. + +Rule 20 matches requests with URL paths ending in `/mail` or exact +path `/email/bar` redirect to location `/postfix/`. + +Additional global parameters are set, including the maximum number +connection limit of 4000 and a minimum TLS version of 1.3. + +``` none +set load-balancing reverse-proxy service http description 'Force redirect to HTTPS' +set load-balancing reverse-proxy service http port '80' +set load-balancing reverse-proxy service http redirect-http-to-https + +set load-balancing reverse-proxy service https backend 'bk-default' +set load-balancing reverse-proxy service https description 'listen on 443 port' +set load-balancing reverse-proxy service https mode 'http' +set load-balancing reverse-proxy service https port '443' +set load-balancing reverse-proxy service https ssl certificate 'cert' +set load-balancing reverse-proxy service https http-response-headers Strict-Transport-Security value 'max-age=31536000' + +set load-balancing reverse-proxy service https rule 10 url-path exact '/.well-known/xxx' +set load-balancing reverse-proxy service https rule 10 set redirect-location '/certs/' +set load-balancing reverse-proxy service https rule 20 url-path end '/mail' +set load-balancing reverse-proxy service https rule 20 url-path exact '/email/bar' +set load-balancing reverse-proxy service https rule 20 set redirect-location '/postfix/' + +set load-balancing reverse-proxy backend bk-default description 'Default backend' +set load-balancing reverse-proxy backend bk-default mode 'http' +set load-balancing reverse-proxy backend bk-default server sr01 address '192.0.2.23' +set load-balancing reverse-proxy backend bk-default server sr01 port '80' + +set load-balancing reverse-proxy global-parameters max-connections '4000' +set load-balancing reverse-proxy global-parameters tls-version-min '1.3' +``` + +### SSL Bridging + +The following configuration terminates incoming HTTPS traffic on the router, +then re-encrypts the traffic and sends to the backend server via HTTPS. +This is useful if encryption is required for both legs, but you do not want to +install publicly trusted certificates on each backend server. + +Backend service certificates are checked against the certificate authority +specified in the configuration, which could be an internal CA. + +The `https` service listens on port 443 with backend `bk-bridge-ssl` to +handle HTTPS traffic. It uses certificate named `cert` for SSL termination. + +The `bk-bridge-ssl` backend connects to sr01 server on port 443 via HTTPS +and checks backend server has a valid certificate trusted by CA `cacert` + +``` none +set load-balancing reverse-proxy service https backend 'bk-bridge-ssl' +set load-balancing reverse-proxy service https description 'listen on 443 port' +set load-balancing reverse-proxy service https mode 'http' +set load-balancing reverse-proxy service https port '443' +set load-balancing reverse-proxy service https ssl certificate 'cert' + +set load-balancing reverse-proxy backend bk-bridge-ssl description 'SSL backend' +set load-balancing reverse-proxy backend bk-bridge-ssl mode 'http' +set load-balancing reverse-proxy backend bk-bridge-ssl ssl ca-certificate 'cacert' +set load-balancing reverse-proxy backend bk-bridge-ssl server sr01 address '192.0.2.23' +set load-balancing reverse-proxy backend bk-bridge-ssl server sr01 port '443' +``` + +### Balancing with HTTP health checks + +This configuration enables HTTP health checks on backend servers. + +``` none +set load-balancing reverse-proxy service my-tcp-api backend 'bk-01' +set load-balancing reverse-proxy service my-tcp-api mode 'tcp' +set load-balancing reverse-proxy service my-tcp-api port '8888' + +set load-balancing reverse-proxy backend bk-01 balance 'round-robin' +set load-balancing reverse-proxy backend bk-01 mode 'tcp' + +set load-balancing reverse-proxy backend bk-01 http-check method 'get' +set load-balancing reverse-proxy backend bk-01 http-check uri '/health' +set load-balancing reverse-proxy backend bk-01 http-check expect 'status 200' + +set load-balancing reverse-proxy backend bk-01 server srv01 address '192.0.2.11' +set load-balancing reverse-proxy backend bk-01 server srv01 port '8881' +set load-balancing reverse-proxy backend bk-01 server srv01 check +set load-balancing reverse-proxy backend bk-01 server srv02 address '192.0.2.12' +set load-balancing reverse-proxy backend bk-01 server srv02 port '8882' +set load-balancing reverse-proxy backend bk-01 server srv02 check +``` diff --git a/docs/configuration/loadbalancing/md-wan.md b/docs/configuration/loadbalancing/md-wan.md new file mode 100644 index 00000000..f82c7e4b --- /dev/null +++ b/docs/configuration/loadbalancing/md-wan.md @@ -0,0 +1,320 @@ +lastproofread +2023-01-27 + +# WAN load balancing + +Outbound traffic can be balanced between two or more outbound interfaces. +If a path fails, traffic is balanced across the remaining healthy paths, +a recovered path is automatically added back to the routing table and used by +the load balancer. The load balancer automatically adds routes for each path to +the routing table and balances traffic across the configured interfaces, +determined by interface health and weight. + +In a minimal configuration, the following must be provided: + +> - an interface with a nexthop +> - one rule with a LAN (inbound-interface) and the WAN (interface). + +Let's assume we have two DHCP WAN interfaces and one LAN (eth2): + +``` none +set load-balancing wan interface-health eth0 nexthop 'dhcp' +set load-balancing wan interface-health eth1 nexthop 'dhcp' +set load-balancing wan rule 1 inbound-interface 'eth2' +set load-balancing wan rule 1 interface eth0 +set load-balancing wan rule 1 interface eth1 +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +WAN Load Balacing should not be used when dynamic routing protocol is +used/needed. This feature creates customized routing tables and firewall +rules, that makes it incompatible to use with routing protocols. + +</div> + +## Balancing Rules + +Interfaces, their weight and the type of traffic to be balanced are defined in +numbered balancing rule sets. The rule sets are executed in numerical order +against outgoing packets. In case of a match the packet is sent through an +interface specified in the matching rule. If a packet doesn't match any rule +it is sent by using the system routing table. Rule numbers can't be changed. + +Create a load balancing rule, it can be a number between 1 and 9999: + +``` none +vyos@vyos# set load-balancing wan rule 1 +Possible completions: +description Description for this rule +> destination Destination +exclude Exclude packets matching this rule from wan load balance +failover Enable failover for packets matching this rule from wan load balance +inbound-interface Inbound interface name (e.g., "eth0") [REQUIRED] ++> interface Interface name [REQUIRED] +> limit Enable packet limit for this rule +per-packet-balancing Option to match traffic per-packet instead of the default, per-flow +protocol Protocol to match +> source Source information +``` + +### Interface weight + +Let's expand the example from above and add weight to the interfaces. +The bandwidth from eth0 is larger than eth1. Per default, outbound traffic is +distributed randomly across available interfaces. Weights can be assigned to +interfaces to influence the balancing. + +``` none +set load-balancing wan rule 1 interface eth0 weight 2 +set load-balancing wan rule 1 interface eth1 weight 1 +``` + +66% of traffic is routed to eth0, eth1 gets 33% of traffic. + +### Rate limit + +A packet rate limit can be set for a rule to apply the rule to traffic above or +below a specified threshold. To configure the rate limiting use: + +``` none +set load-balancing wan rule <rule> limit <parameter> +``` + +- `burst`: Number of packets allowed to overshoot the limit within `period`. + Default 5. +- `period`: Time window for rate calculation. Possible values: + `second` (one second), `minute` (one minute), `hour` (one hour). + Default is `second`. +- `rate`: Number of packets. Default 5. +- `threshold`: `below` or `above` the specified rate limit. + +### Flow and packet-based balancing + +Outgoing traffic is balanced in a flow-based manner. +A connection tracking table is used to track flows by their source address, +destination address and port. Each flow is assigned to an interface according +to the defined balancing rules and subsequent packets are sent through the +same interface. This has the advantage that packets always arrive in order if +links with different speeds are in use. + +Packet-based balancing can lead to a better balance across interfaces when out +of order packets are no issue. Per-packet-based balancing can be set for a +balancing rule with: + +``` none +set load-balancing wan rule <rule> per-packet-balancing +``` + +### Exclude traffic + +To exclude traffic from load balancing, traffic matching an exclude rule is not +balanced but routed through the system routing table instead: + +``` none +set load-balancing wan rule <rule> exclude +``` + +## Health checks + +The health of interfaces and paths assigned to the load balancer is +periodically checked by sending ICMP packets (ping) to remote destinations, +a TTL test or the execution of a user defined script. If an interface fails the +health check it is removed from the load balancer's pool of interfaces. +To enable health checking for an interface: + +``` none +vyos@vyos# set load-balancing wan interface-health <interface> +Possible completions: +failure-count Failure count +nexthop Outbound interface nexthop address. Can be 'dhcp or ip address' [REQUIRED] +success-count Success count ++> test Rule number +``` + +Specify nexthop on the path to the destination, `ipv4-address` can be set to +`dhcp` + +``` none +set load-balancing wan interface-health <interface> nexthop <ipv4-address> +``` + +Set the number of health check failures before an interface is marked as +unavailable, range for number is 1 to 10, default 1. Or set the number of +successful health checks before an interface is added back to the interface +pool, range for number is 1 to 10, default 1. + +``` none +set load-balancing wan interface-health <interface> failure-count <number> +set load-balancing wan interface-health <interface> success-count <number> +``` + +Each health check is configured in its own test, tests are numbered and +processed in numeric order. For multi target health checking multiple tests +can be defined: + +``` none +vyos@vyos# set load-balancing wan interface-health eth1 test 0 +Possible completions: +resp-time Ping response time (seconds) +target Health target address +test-script Path to user defined script +ttl-limit Ttl limit (hop count) +type WLB test type +``` + +- `resp-time`: the maximum response time for ping in seconds. + Range 1...30, default 5 +- `target`: the target to be sent ICMP packets to, address can be an IPv4 + address or hostname +- `test-script`: A user defined script must return 0 to be considered + successful and non-zero to fail. Scripts are located in /config/scripts, + for different locations the full path needs to be provided +- `ttl-limit`: For the UDP TTL limit test the hop count limit must be + specified. The limit must be shorter than the path length, an ICMP time + expired message is needed to be returned for a successful test. default 1 +- `type`: Specify the type of test. type can be ping, ttl or a user defined + script + +## Source NAT rules + +Per default, interfaces used in a load balancing pool replace the source IP +of each outgoing packet with its own address to ensure that replies arrive on +the same interface. This works through automatically generated source NAT (SNAT) +rules, these rules are only applied to balanced traffic. In cases where this +behaviour is not desired, the automatic generation of SNAT rules can be +disabled: + +``` none +set load-balancing wan disable-source-nat +``` + +## Sticky Connections + +Inbound connections to a WAN interface can be improperly handled when the reply +is sent back to the client. + +<img src="/_static/images/sticky-connections.webp" class="align-center" style="width:80.0%" alt="image" /> + +Upon reception of an incoming packet, when a response is sent, it might be +desired to ensure that it leaves from the same interface as the inbound one. +This can be achieved by enabling sticky connections in the load balancing: + +``` none +set load-balancing wan sticky-connections inbound +``` + +## Failover + +In failover mode, one interface is set to be the primary interface and other +interfaces are secondary or spare. Instead of balancing traffic across all +healthy interfaces, only the primary interface is used and in case of failure, +a secondary interface selected from the pool of available interfaces takes over. +The primary interface is selected based on its weight and health, others become +secondary interfaces. Secondary interfaces to take over a failed primary +interface are chosen from the load balancer's interface pool, depending +on their weight and health. Interface roles can also be selected based on rule +order by including interfaces in balancing rules and ordering those rules +accordingly. To put the load balancer in failover mode, create a failover rule: + +``` none +set load-balancing wan rule <number> failover +``` + +Because existing sessions do not automatically fail over to a new path, +the session table can be flushed on each connection state change: + +``` none +set load-balancing wan flush-connections +``` + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +Flushing the session table will cause other connections to fall back from +flow-based to packet-based balancing until each flow is reestablished. + +</div> + +## Script execution + +A script can be run when an interface state change occurs. Scripts are run +from /config/scripts, for a different location specify the full path: + +``` none +set load-balancing wan hook script-name +``` + +Two environment variables are available: + +- `WLB_INTERFACE_NAME=[interfacename]`: Interface to be monitored +- `WLB_INTERFACE_STATE=[ACTIVE|FAILED]`: Interface state + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +Blocking call with no timeout. System will become unresponsive if script +does not return! + +</div> + +## Handling and monitoring + +Show WAN load balancer information including test types and targets. +A character at the start of each line depicts the state of the test + +- `+` successful +- `-` failed +- a blank indicates that no test has been carried out + +``` none +vyos@vyos:~$ show wan-load-balance +Interface: eth0 +Status: failed +Last Status Change: Tue Jun 11 20:12:19 2019 +-Test: ping Target: + Last Interface Success: 55s + Last Interface Failure: 0s + # Interface Failure(s): 5 + +Interface: eth1 +Status: active +Last Status Change: Tue Jun 11 20:06:42 2019 ++Test: ping Target: + Last Interface Success: 0s + Last Interface Failure: 6m26s + # Interface Failure(s): 0 +``` + +Show connection data of load balanced traffic: + +``` none +vyos@vyos:~$ show wan-load-balance connection +conntrack v1.4.2 (conntrack-tools): 3 flow entries have been shown. +Type State Src Dst Packets Bytes +tcp TIME_WAIT 10.1.1.13:38040 203.0.113.2:80 203.0.113.2 192.168.188.71 +udp 10.1.1.13:41891 198.51.100.3:53 198.51.100.3 192.168.188.71 +udp 10.1.1.13:55437 198.51.100.3:53 198.51.100.3 192.168.188.71 +``` + +### Restart + +``` none +restart wan-load-balance +``` diff --git a/docs/configuration/md-index.md b/docs/configuration/md-index.md new file mode 100644 index 00000000..8371199f --- /dev/null +++ b/docs/configuration/md-index.md @@ -0,0 +1,22 @@ +# Configuration Guide + +The following structure respresent the cli structure. + +<div class="toctree" maxdepth="1" includehidden=""> + +container/index +firewall/index +highavailability/index +interfaces/index +loadbalancing/index +nat/index +policy/index +pki/index +protocols/index +service/index +system/index +trafficpolicy/index +vpn/index +vrf/index + +</div> diff --git a/docs/configuration/nat/md-index.md b/docs/configuration/nat/md-index.md new file mode 100644 index 00000000..ef73db30 --- /dev/null +++ b/docs/configuration/nat/md-index.md @@ -0,0 +1,9 @@ +# NAT + +<div class="toctree" maxdepth="1" includehidden=""> + +nat44 +nat64 +nat66 + +</div> diff --git a/docs/configuration/nat/md-nat44.md b/docs/configuration/nat/md-nat44.md new file mode 100644 index 00000000..627f84c1 --- /dev/null +++ b/docs/configuration/nat/md-nat44.md @@ -0,0 +1,844 @@ +# NAT44 + +`NAT (Network Address Translation)` is a common method of +remapping one IP address space into another by modifying network address +information in the IP header of packets while they are in transit across +a traffic routing device. The technique was originally used as a +shortcut to avoid the need to readdress every host when a network was +moved. It has become a popular and essential tool in conserving global +address space in the face of IPv4 address exhaustion. One +Internet-routable IP address of a NAT gateway can be used for an entire +private network. + +IP masquerading is a technique that hides an entire IP address space, +usually consisting of private IP addresses, behind a single IP address +in another, usually public address space. The hidden addresses are +changed into a single (public) IP address as the source address of the +outgoing IP packets so they appear as originating not from the hidden +host but from the routing device itself. Because of the popularity of +this technique to conserve IPv4 address space, the term NAT has become +virtually synonymous with IP masquerading. + +As network address translation modifies the IP address information in +packets, NAT implementations may vary in their specific behavior in +various addressing cases and their effect on network traffic. The +specifics of NAT behavior are not commonly documented by vendors of +equipment containing NAT implementations. + +The computers on an internal network can use any of the addresses set +aside by the `IANA (Internet Assigned Numbers Authority)` for +private addressing (see `1918`). These reserved IP addresses are +not in use on the Internet, so an external machine will not directly +route to them. The following addresses are reserved for private use: + +- 10.0.0.0 to 10.255.255.255 (CIDR: 10.0.0.0/8) +- 172.16.0.0 to 172.31.255.255 (CIDR: 172.16.0.0/12) +- 192.168.0.0 to 192.168.255.255 (CIDR: 192.168.0.0/16) + +If an ISP deploys a `CGN (Carrier-grade NAT)`, and uses +`1918` address space to number customer gateways, the risk of +address collision, and therefore routing failures, arises when the +customer network already uses an `1918` address space. + +This prompted some ISPs to develop a policy within the `ARIN +(American Registry for Internet Numbers)` to allocate new private +address space for CGNs, but ARIN deferred to the IETF before +implementing the policy indicating that the matter was not a typical +allocation issue but a reservation of addresses for technical purposes +(per `2860`). + +IETF published `6598`, detailing a shared address space for use in +ISP CGN deployments that can handle the same network prefixes occurring +both on inbound and outbound interfaces. ARIN returned address space to +the `IANA (Internet Assigned Numbers Authority)` for this +allocation. + +The allocated address block is 100.64.0.0/10. + +Devices evaluating whether an IPv4 address is public must be updated to +recognize the new address space. Allocating more private IPv4 address +space for NAT devices might prolong the transition to IPv6. + +## Overview + +### Different NAT Types + +#### SNAT + +`SNAT (Source Network Address Translation)` is the most common +form of `NAT (Network Address Translation)` and is typically +referred to simply as NAT. To be more correct, what most people refer +to as `NAT (Network Address Translation)` is actually the process +of `PAT (Port Address Translation)`, or NAT overload. SNAT is +typically used by internal users/private hosts to access the Internet +- the source address is translated and thus kept private. + +#### DNAT + +`DNAT (Destination Network Address Translation)` changes the +destination address of packets passing through the router, while +`source-nat` changes the source address of packets. DNAT is +typically used when an external (public) host needs to initiate a +session with an internal (private) host. A customer needs to access a +private service behind the routers public IP. A connection is +established with the routers public IP address on a well known port and +thus all traffic for this port is rewritten to address the internal +(private) host. + +#### Bidirectional NAT + +This is a common scenario where both `source-nat` and +`destination-nat` are configured at the same time. It's commonly +used when internal (private) hosts need to establish a connection with +external resources and external systems need to access internal +(private) resources. + +### NAT, Routing, Firewall Interaction + +There is a very nice picture/explanation in the Vyatta documentation +which should be rewritten here. + +### NAT Ruleset + +`NAT (Network Address Translation)` is configured entirely on a +series of so called <span class="title-ref">rules</span>. Rules are numbered and evaluated by the +underlying OS in numerical order! The rule numbers can be changes by +utilizing the `rename` and `copy` commands. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Changes to the NAT system only affect newly established +connections. Already established connections are not affected. + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +When designing your NAT ruleset leave some space between +consecutive rules for later extension. Your ruleset could start with +numbers 10, 20, 30. You thus can later extend the ruleset and place +new rules between existing ones. + +</div> + +Rules will be created for both `source-nat` and +`destination-nat`. + +For `bidirectional-nat` a rule for both `source-nat` and +`destination-nat` needs to be created. + +### Traffic Filters + +Traffic Filters are used to control which packets will have the defined +NAT rules applied. Five different filters can be applied within a NAT +rule. + +- **outbound-interface** - applicable only to `source-nat`. It + configures the interface which is used for the outside traffic that + this translation rule applies to. Interface groups, inverted + selection and wildcard, are also supported. + + Examples: + + ``` none + set nat source rule 20 outbound-interface name eth0 + set nat source rule 30 outbound-interface name bond1* + set nat source rule 20 outbound-interface name !vtun2 + set nat source rule 20 outbound-interface group GROUP1 + set nat source rule 20 outbound-interface group !GROUP2 + ``` + +- **inbound-interface** - applicable only to `destination-nat`. It + configures the interface which is used for the inside traffic the + translation rule applies to. Interface groups, inverted + selection and wildcard, are also supported. + + Example: + + ``` none + set nat destination rule 20 inbound-interface name eth0 + set nat destination rule 30 inbound-interface name bond1* + set nat destination rule 20 inbound-interface name !vtun2 + set nat destination rule 20 inbound-interface group GROUP1 + set nat destination rule 20 inbound-interface group !GROUP2 + ``` + +- **protocol** - specify which types of protocols this translation rule + applies to. Only packets matching the specified protocol are NATed. + By default this applies to <span class="title-ref">all</span> protocols. + + Example: + + - Set SNAT rule 20 to only NAT TCP and UDP packets + - Set DNAT rule 20 to only NAT UDP packets + + ``` none + set nat source rule 20 protocol tcp_udp + set nat destination rule 20 protocol udp + ``` + +- **source** - specifies which packets the NAT translation rule applies + to based on the packets source IP address and/or source port. Only + matching packets are considered for NAT. + + Example: + + - Set SNAT rule 20 to only NAT packets arriving from the 192.0.2.0/24 + network + - Set SNAT rule 30 to only NAT packets arriving from the 203.0.113.0/24 + network with a source port of 80 and 443 + + ``` none + set nat source rule 20 source address 192.0.2.0/24 + set nat source rule 30 source address 203.0.113.0/24 + set nat source rule 30 source port 80,443 + ``` + +- **destination** - specify which packets the translation will be + applied to, only based on the destination address and/or port number + configured. + + <div class="note"> + + <div class="title"> + + Note + + </div> + + If no destination is specified the rule will match on any + destination address and port. + + </div> + + Example: + + - Configure SNAT rule (40) to only NAT packets with a destination + address of 192.0.2.1. + + ``` none + set nat source rule 40 destination address 192.0.2.1 + ``` + +### Address Conversion + +Every NAT rule has a translation command defined. The address defined +for the translation is the address used when the address information in +a packet is replaced. + +#### Source Address + +For `source-nat` rules the packets source address will be replaced +with the address specified in the translation command. A port +translation can also be specified and is part of the translation +address. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The translation address must be set to one of the available +addresses on the configured <span class="title-ref">outbound-interface</span> or it must be set to +<span class="title-ref">masquerade</span> which will use the primary IP address of the +<span class="title-ref">outbound-interface</span> as its translation address. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +When using NAT for a large number of host systems it +recommended that a minimum of 1 IP address is used to NAT every 256 +private host systems. This is due to the limit of 65,000 port numbers +available for unique translations and a reserving an average of +200-300 sessions per host system. + +</div> + +Example: + +- Define a discrete source IP address of 100.64.0.1 for SNAT rule 20 +- Use address <span class="title-ref">masquerade</span> (the interfaces primary address) on rule 30 +- For a large amount of private machines behind the NAT your address + pool might to be bigger. Use any address in the range 100.64.0.10 - + 100.64.0.20 on SNAT rule 40 when doing the translation + +``` none +set nat source rule 20 translation address 100.64.0.1 +set nat source rule 30 translation address 'masquerade' +set nat source rule 40 translation address 100.64.0.10-100.64.0.20 +``` + +#### Destination Address + +For `destination-nat` rules the packets destination address will be +replaced by the specified address in the <span class="title-ref">translation address</span> command. + +Example: + +- DNAT rule 10 replaces the destination address of an inbound packet + with 192.0.2.10 + +``` none +set nat destination rule 10 translation address 192.0.2.10 +``` + +Also, in `destination-nat`, redirection to localhost is supported. +The redirect statement is a special form of dnat which always translates +the destination address to the local host’s one. + +Example of redirection: + +``` none +set nat destination rule 10 translation redirect port 22 +``` + +### NAT Load Balance + +Advanced configuration can be used in order to apply source or destination NAT, +and within a single rule, be able to define multiple translated addresses, +so NAT balances the translations among them. + +NAT Load Balance uses an algorithm that generates a hash and based on it, then +it applies corresponding translation. This hash can be generated randomly, or +can use data from the ip header: source-address, destination-address, +source-port and/or destination-port. By default, it will generate the hash +randomly. + +When defining the translated address, called `backends`, a `weight` must +be configured. This lets the user define load balance distribution according +to their needs. Them sum of all the weights defined for the backends should +be equal to 100. In oder words, the weight defined for the backend is the +percentage of the connections that will receive such backend. + +<div class="cfgcmd"> + +set nat \[source | destination\] rule \<rule\> load-balance hash +\[source-address | destination-address | source-port | destination-port +| random\] + +</div> + +<div class="cfgcmd"> + +set nat \[source | destination\] rule \<rule\> load-balance backend +\<x.x.x.x\> weight \<1-100\> + +</div> + +## Configuration Examples + +To setup SNAT, we need to know: + +- The internal IP addresses we want to translate +- The outgoing interface to perform the translation on +- The external IP address to translate to + +In the example used for the Quick Start configuration above, we +demonstrate the following configuration: + +``` none +set nat source rule 100 outbound-interface name 'eth0' +set nat source rule 100 source address '192.168.0.0/24' +set nat source rule 100 translation address 'masquerade' +``` + +Which generates the following configuration: + +``` none +rule 100 { + outbound-interface { + name eth0 + } + source { + address 192.168.0.0/24 + } + translation { + address masquerade + } +} +``` + +In this example, we use **masquerade** as the translation address +instead of an IP address. The **masquerade** target is effectively an +alias to say "use whatever IP address is on the outgoing interface", +rather than a statically configured IP address. This is useful if you +use DHCP for your outgoing interface and do not know what the external +address will be. + +When using NAT for a large number of host systems it recommended that a +minimum of 1 IP address is used to NAT every 256 host systems. This is +due to the limit of 65,000 port numbers available for unique +translations and a reserving an average of 200-300 sessions per host +system. + +Example: For an ~8,000 host network a source NAT pool of 32 IP addresses +is recommended. + +A pool of addresses can be defined by using a hyphen between two IP +addresses: + +``` none +set nat source rule 100 translation address '203.0.113.32-203.0.113.63' +``` + +### Avoiding "leaky" NAT + +Linux netfilter will not NAT traffic marked as INVALID. This often +confuses people into thinking that Linux (or specifically VyOS) has a +broken NAT implementation because non-NATed traffic is seen leaving an +external interface. This is actually working as intended, and a packet +capture of the "leaky" traffic should reveal that the traffic is either +an additional TCP "RST", "FIN,ACK", or "RST,ACK" sent by client systems +after Linux netfilter considers the connection closed. The most common +is the additional TCP RST some host implementations send after +terminating a connection (which is implementation-specific). + +In other words, connection tracking has already observed the connection +be closed and has transition the flow to INVALID to prevent attacks from +attempting to reuse the connection. + +You can avoid the "leaky" behavior by using a firewall policy that drops +"invalid" state packets. + +Having control over the matching of INVALID state traffic, e.g. the +ability to selectively log, is an important troubleshooting tool for +observing broken protocol behavior. For this reason, VyOS does not +globally drop invalid state traffic, instead allowing the operator to +make the determination on how the traffic is handled. + +### Hairpin NAT/NAT Reflection + +A typical problem with using NAT and hosting public servers is the +ability for internal systems to reach an internal server using it's +external IP address. The solution to this is usually the use of +split-DNS to correctly point host systems to the internal address when +requests are made internally. Because many smaller networks lack DNS +infrastructure, a work-around is commonly deployed to facilitate the +traffic by NATing the request from internal hosts to the source address +of the internal interface on the firewall. + +This technique is commonly referred to as NAT Reflection or Hairpin NAT. + +Example: + +- Redirect Microsoft RDP traffic from the outside (WAN, external) world + via `destination-nat` in rule 100 to the internal, private host + 192.0.2.40. +- Redirect Microsoft RDP traffic from the internal (LAN, private) + network via `destination-nat` in rule 110 to the internal, + private host 192.0.2.40. We also need a `source-nat` rule 110 for + the reverse path of the traffic. The internal network 192.0.2.0/24 is + reachable via interface <span class="title-ref">eth0.10</span>. + +``` none +set nat destination rule 100 description 'Regular destination NAT from external' +set nat destination rule 100 destination port '3389' +set nat destination rule 100 inbound-interface name 'pppoe0' +set nat destination rule 100 protocol 'tcp' +set nat destination rule 100 translation address '192.0.2.40' + +set nat destination rule 110 description 'NAT Reflection: INSIDE' +set nat destination rule 110 destination port '3389' +set nat destination rule 110 inbound-interface name 'eth0.10' +set nat destination rule 110 protocol 'tcp' +set nat destination rule 110 translation address '192.0.2.40' + +set nat source rule 110 description 'NAT Reflection: INSIDE' +set nat source rule 110 destination address '192.0.2.0/24' +set nat source rule 110 outbound-interface name 'eth0.10' +set nat source rule 110 protocol 'tcp' +set nat source rule 110 source address '192.0.2.0/24' +set nat source rule 110 translation address 'masquerade' +``` + +Which results in a configuration of: + +``` none +vyos@vyos# show nat + destination { + rule 100 { + description "Regular destination NAT from external" + destination { + port 3389 + } + inbound-interface { + name pppoe0 + } + protocol tcp + translation { + address 192.0.2.40 + } + } + rule 110 { + description "NAT Reflection: INSIDE" + destination { + port 3389 + } + inbound-interface { + name eth0.10 + } + protocol tcp + translation { + address 192.0.2.40 + } + } + } + source { + rule 110 { + description "NAT Reflection: INSIDE" + destination { + address 192.0.2.0/24 + } + outbound-interface { + name eth0.10 + } + protocol tcp + source { + address 192.0.2.0/24 + } + translation { + address masquerade + } + } + } +``` + +### Destination NAT + +DNAT is typically referred to as a **Port Forward**. When using VyOS as +a NAT router and firewall, a common configuration task is to redirect +incoming traffic to a system behind the firewall. + +In this example, we will be using the example Quick Start configuration +above as a starting point. + +To setup a destination NAT rule we need to gather: + +- The interface traffic will be coming in on; +- The protocol and port we wish to forward; +- The IP address of the internal system we wish to forward traffic to. + +In our example, we will be forwarding web server traffic to an internal +web server on 192.168.0.100. HTTP traffic makes use of the TCP protocol +on port 80. For other common port numbers, see: +<https://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers> + +Our configuration commands would be: + +``` none +set nat destination rule 10 description 'Port Forward: HTTP to 192.168.0.100' +set nat destination rule 10 destination port '80' +set nat destination rule 10 inbound-interface name 'eth0' +set nat destination rule 10 protocol 'tcp' +set nat destination rule 10 translation address '192.168.0.100' +``` + +Which would generate the following NAT destination configuration: + +``` none +nat { + destination { + rule 10 { + description "Port Forward: HTTP to 192.168.0.100" + destination { + port 80 + } + inbound-interface { + name eth0 + } + protocol tcp + translation { + address 192.168.0.100 + } + } + } +} +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If forwarding traffic to a different port than it is arriving +on, you may also configure the translation port using +<span class="title-ref">set nat destination rule \[n\] translation port</span>. + +</div> + +This establishes our Port Forward rule, but if we created a firewall +policy it will likely block the traffic. + +It is important to note that when creating firewall rules that the DNAT +translation occurs **before** traffic traverses the firewall. In other +words, the destination address has already been translated to +192.168.0.100. + +So in our firewall policy, we want to allow traffic coming in on the +outside interface, destined for TCP port 80 and the IP address of +192.168.0.100. + +``` none +set firewall name OUTSIDE-IN rule 20 action 'accept' +set firewall name OUTSIDE-IN rule 20 destination address '192.168.0.100' +set firewall name OUTSIDE-IN rule 20 destination port '80' +set firewall name OUTSIDE-IN rule 20 protocol 'tcp' +set firewall name OUTSIDE-IN rule 20 state new 'enable' +``` + +This would generate the following configuration: + +``` none +rule 20 { + action accept + destination { + address 192.168.0.100 + port 80 + } + protocol tcp + state { + new enable + } +} +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you have configured the <span class="title-ref">INSIDE-OUT</span> policy, you will need to add +additional rules to permit inbound NAT traffic. + +</div> + +### 1-to-1 NAT + +Another term often used for DNAT is **1-to-1 NAT**. For a 1-to-1 NAT +configuration, both DNAT and SNAT are used to NAT all traffic from an +external IP address to an internal IP address and vice-versa. + +Typically, a 1-to-1 NAT rule omits the destination port (all ports) and +replaces the protocol with either **all** or **ip**. + +Then a corresponding SNAT rule is created to NAT outgoing traffic for +the internal IP to a reserved external IP. This dedicates an external IP +address to an internal IP address and is useful for protocols which +don't have the notion of ports, such as GRE. + +Here's an extract of a simple 1-to-1 NAT configuration with one internal +and one external interface: + +``` none +set interfaces ethernet eth0 address '192.168.1.1/24' +set interfaces ethernet eth0 description 'Inside interface' +set interfaces ethernet eth1 address '192.0.2.30/24' +set interfaces ethernet eth1 description 'Outside interface' +set nat destination rule 2000 description '1-to-1 NAT example' +set nat destination rule 2000 destination address '192.0.2.30' +set nat destination rule 2000 inbound-interface name 'eth1' +set nat destination rule 2000 translation address '192.168.1.10' +set nat source rule 2000 description '1-to-1 NAT example' +set nat source rule 2000 outbound-interface name 'eth1' +set nat source rule 2000 source address '192.168.1.10' +set nat source rule 2000 translation address '192.0.2.30' +``` + +Firewall rules are written as normal, using the internal IP address as +the source of outbound rules and the destination of inbound rules. + +### NAT before VPN + +Some application service providers (ASPs) operate a VPN gateway to +provide access to their internal resources, and require that a +connecting organisation translate all traffic to the service provider +network to a source address provided by the ASP. + +### Load Balance + +Here we provide two examples on how to apply NAT Load Balance. + +First scenario: apply destination NAT for all HTTP traffic comming through +interface eth0, and user 4 backends. First backend should received 30% of +the request, second backend should get 20%, third 15% and the fourth 35% +We will use source and destination address for hash generation. + +``` none +set nat destination rule 10 inbound-interface name eth0 +set nat destination rule 10 protocol tcp +set nat destination rule 10 destination port 80 +set nat destination rule 10 load-balance hash source-address +set nat destination rule 10 load-balance hash destination-address +set nat destination rule 10 load-balance backend 198.51.100.101 weight 30 +set nat destination rule 10 load-balance backend 198.51.100.102 weight 20 +set nat destination rule 10 load-balance backend 198.51.100.103 weight 15 +set nat destination rule 10 load-balance backend 198.51.100.104 weight 35 +``` + +Second scenario: apply source NAT for all outgoing connections from +LAN 10.0.0.0/8, using 3 public addresses and equal distribution. +We will generate the hash randomly. + +``` none +set nat source rule 10 outbound-interface name eth0 +set nat source rule 10 source address 10.0.0.0/8 +set nat source rule 10 load-balance hash random +set nat source rule 10 load-balance backend 192.0.2.251 weight 33 +set nat source rule 10 load-balance backend 192.0.2.252 weight 33 +set nat source rule 10 load-balance backend 192.0.2.253 weight 34 +``` + +#### Example Network + +Here's one example of a network environment for an ASP. +The ASP requests that all connections from this company should come from +172.29.41.89 - an address that is assigned by the ASP and not in use at +the customer site. + +<figure> +<img src="/_static/images/nat_before_vpn_topology.webp" alt="NAT before VPN Topology" /> +<figcaption aria-hidden="true">NAT before VPN Topology</figcaption> +</figure> + +#### Configuration + +The required configuration can be broken down into 4 major pieces: + +- A dummy interface for the provider-assigned IP; +- NAT (specifically, Source NAT); +- IPSec IKE and ESP Groups; +- IPSec VPN tunnels. + +##### Dummy interface + +The dummy interface allows us to have an equivalent of the Cisco IOS +Loopback interface - a router-internal interface we can use for IP +addresses the router must know about, but which are not actually +assigned to a real network. + +We only need a single step for this interface: + +``` none +set interfaces dummy dum0 address '172.29.41.89/32' +``` + +##### NAT Configuration + +``` none +set nat source rule 110 description 'Internal to ASP' +set nat source rule 110 destination address '172.27.1.0/24' +set nat source rule 110 source address '192.168.43.0/24' +set nat source rule 110 translation address '172.29.41.89' +set nat source rule 120 description 'Internal to ASP' +set nat source rule 120 destination address '10.125.0.0/16' +set nat source rule 120 source address '192.168.43.0/24' +set nat source rule 120 translation address '172.29.41.89' +``` + +##### IPSec IKE and ESP + +The ASP has documented their IPSec requirements: + +- IKE Phase: + - aes256 Encryption + - sha256 Hashes +- ESP Phase: + - aes256 Encryption + - sha256 Hashes + - DH Group 14 + +Additionally, we want to use VPNs only on our eth1 interface (the +external interface in the image above) + +``` none +set vpn ipsec ike-group my-ike key-exchange 'ikev1' +set vpn ipsec ike-group my-ike lifetime '7800' +set vpn ipsec ike-group my-ike proposal 1 dh-group '14' +set vpn ipsec ike-group my-ike proposal 1 encryption 'aes256' +set vpn ipsec ike-group my-ike proposal 1 hash 'sha256' + +set vpn ipsec esp-group my-esp lifetime '3600' +set vpn ipsec esp-group my-esp mode 'tunnel' +set vpn ipsec esp-group my-esp pfs 'disable' +set vpn ipsec esp-group my-esp proposal 1 encryption 'aes256' +set vpn ipsec esp-group my-esp proposal 1 hash 'sha256' + +set vpn ipsec interface 'eth1' +``` + +##### IPSec VPN Tunnels + +We'll use the IKE and ESP groups created above for this VPN. Because we +need access to 2 different subnets on the far side, we will need two +different tunnels. If you changed the names of the ESP group and IKE +group in the previous step, make sure you use the correct names here +too. + +``` none +set vpn ipsec authentication psk vyos id '203.0.113.46' +set vpn ipsec authentication psk vyos id '198.51.100.243' +set vpn ipsec authentication psk vyos secret 'MYSECRETPASSWORD' +set vpn ipsec site-to-site peer branch authentication local-id '203.0.113.46' +set vpn ipsec site-to-site peer branch authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer branch authentication remote-id '198.51.100.243' +set vpn ipsec site-to-site peer branch connection-type 'initiate' +set vpn ipsec site-to-site peer branch default-esp-group 'my-esp' +set vpn ipsec site-to-site peer branch ike-group 'my-ike' +set vpn ipsec site-to-site peer branch ikev2-reauth 'inherit' +set vpn ipsec site-to-site peer branch local-address '203.0.113.46' +set vpn ipsec site-to-site peer branch remote-address '198.51.100.243' +set vpn ipsec site-to-site peer branch tunnel 0 local prefix '172.29.41.89/32' +set vpn ipsec site-to-site peer branch tunnel 0 remote prefix '172.27.1.0/24' +set vpn ipsec site-to-site peer branch tunnel 1 local prefix '172.29.41.89/32' +set vpn ipsec site-to-site peer branch tunnel 1 remote prefix '10.125.0.0/16' +``` + +##### Testing and Validation + +If you've completed all the above steps you no doubt want to see if it's +all working. + +Start by checking for IPSec SAs (Security Associations) with: + +``` none +$ show vpn ipsec sa + +Peer ID / IP Local ID / IP +------------ ------------- +198.51.100.243 203.0.113.46 + + Tunnel State Bytes Out/In Encrypt Hash NAT-T A-Time L-Time Proto + ------ ----- ------------- ------- ---- ----- ------ ------ ----- + 0 up 0.0/0.0 aes256 sha256 no 1647 3600 all + 1 up 0.0/0.0 aes256 sha256 no 865 3600 all +``` + +That looks good - we defined 2 tunnels and they're both up and running. diff --git a/docs/configuration/nat/md-nat64.md b/docs/configuration/nat/md-nat64.md new file mode 100644 index 00000000..3cc9b34d --- /dev/null +++ b/docs/configuration/nat/md-nat64.md @@ -0,0 +1,68 @@ +# NAT64 + +`NAT64 (IPv6-to-IPv4 Prefix Translation)` is a critical component in +modern networking, facilitating communication between IPv6 and IPv4 networks. +This documentation outlines the setup, configuration, and usage of the NAT64 +feature in your project. Whether you are transitioning to IPv6 or need to +seamlessly connect IPv4 and IPv6 devices. +NAT64 is a stateful translation mechanism that translates IPv6 addresses to +IPv4 addresses and IPv4 addresses to IPv6 addresses. NAT64 is used to enable +IPv6-only clients to contact IPv4 servers using unicast UDP, TCP, or ICMP. + +## Overview + +### Different NAT Types + +#### SNAT64 + +`SNAT64 (IPv6-to-IPv4 Source Address Translation)` is a stateful +translation mechanism that translates IPv6 addresses to IPv4 addresses. + +`64:ff9b::/96` is the well-known prefix for IPv4-embedded IPv6 addresses. +The prefix is used to represent IPv4 addresses in an IPv6 address format. +The IPv4 address is encoded in the low-order 32 bits of the IPv6 address. +The high-order 32 bits are set to the well-known prefix 64:ff9b::/96. + +## Configuration Examples + +The following examples show how to configure NAT64 on a VyOS router. +The 192.0.2.10 address is used as the IPv4 address for the translation pool. + +NAT64 server configuration: + +``` none +set interfaces ethernet eth0 address '192.0.2.1/24' +set interfaces ethernet eth0 address '192.0.2.10/24' +set interfaces ethernet eth0 description 'WAN' +set interfaces ethernet eth1 address '2001:db8::1/64' +set interfaces ethernet eth1 description 'LAN' + +set service dns forwarding allow-from '2001:db8::/64' +set service dns forwarding dns64-prefix '64:ff9b::/96' +set service dns forwarding listen-address '2001:db8::1' + +set nat64 source rule 100 source prefix '64:ff9b::/96' +set nat64 source rule 100 translation pool 10 address '192.0.2.10' +set nat64 source rule 100 translation pool 10 port '1-65535' +``` + +NAT64 client configuration: + +``` none +set interfaces ethernet eth1 address '2001:db8::2/64' +set protocols static route6 64:ff9b::/96 next-hop 2001:db8::1 +set system name-server '2001:db8::1' +``` + +Test from the IPv6 only client: + +``` none +vyos@r1:~$ ping 64:ff9b::192.0.2.1 count 2 +PING 64:ff9b::192.0.2.1(64:ff9b::c000:201) 56 data bytes +64 bytes from 64:ff9b::c000:201: icmp_seq=1 ttl=63 time=0.351 ms +64 bytes from 64:ff9b::c000:201: icmp_seq=2 ttl=63 time=0.373 ms + +--- 64:ff9b::192.0.2.1 ping statistics --- +2 packets transmitted, 2 received, 0% packet loss, time 1023ms +rtt min/avg/max/mdev = 0.351/0.362/0.373/0.011 ms +``` diff --git a/docs/configuration/nat/md-nat66.md b/docs/configuration/nat/md-nat66.md new file mode 100644 index 00000000..619bbd49 --- /dev/null +++ b/docs/configuration/nat/md-nat66.md @@ -0,0 +1,221 @@ +# NAT66(NPTv6) + +`NPTv6 (IPv6-to-IPv6 Network Prefix Translation)` is an address +translation technology based on IPv6 networks, used to convert an IPv6 +address prefix in an IPv6 message into another IPv6 address prefix. +We call this address translation method NAT66. Devices that support the NAT66 +function are called NAT66 devices, which can provide NAT66 source +and destination address translation functions. + +## Overview + +### Different NAT Types + +#### SNAT66 + +`SNPTv6 (Source IPv6-to-IPv6 Network Prefix Translation)` The conversion +function is mainly used in the following scenarios: + +- A single internal network and external network. Use the NAT66 device to + connect a single internal network and public network, and the hosts in + the internal network use IPv6 address prefixes that only support + routing within the local range. When a host in the internal network + accesses the external network, the source IPv6 address prefix in + the message will be converted into a global unicast IPv6 address + prefix by the NAT66 device. +- Redundancy and load sharing. There are multiple NAT66 devices at the edge + of an IPv6 network to another IPv6 network. The path through the NAT66 + device to another IPv6 network forms an equivalent route, and traffic + can be load-shared on these NAT66 devices. In this case, you + can configure the same source address translation rules on these + NAT66 devices, so that any NAT66 device can handle IPv6 traffic between + different sites. +- Multi-homed. In a multi-homed network environment, the NAT66 device + connects to an internal network and simultaneously connects to + different external networks. Address translation can be configured + on each external network side interface of the NAT66 device to + convert the same internal network address into different external + network addresses, and realize the mapping of the same internal + address to multiple external addresses. + +#### DNAT66 + +The `DNPTv6 (Destination IPv6-to-IPv6 Network Prefix Translation)` +destination address translation function is used in scenarios where the +server in the internal network provides services to the external network, +such as providing Web services or FTP services to the external network. +By configuring the mapping relationship between the internal server +address and the external network address on the external network +side interface of the NAT66 device, external network users can +access the internal network server through the designated +external network address. + +### Prefix Conversion + +#### Source Prefix + +Every SNAT66 rule has a translation command defined. The prefix defined +for the translation is the prefix used when the address information in +a packet is replaced.、 + +The `source-nat66` rule replaces the source address of the packet +and calculates the converted address using the prefix specified in the rule. + +Example: + +- Convert the address prefix of a single <span class="title-ref">fc01::/64</span> network to <span class="title-ref">fc00::/64</span> +- Output from <span class="title-ref">eth0</span> network interface + +``` none +set nat66 source rule 1 outbound-interface 'eth0' +set nat66 source rule 1 source prefix 'fc01::/64' +set nat66 source rule 1 translation address 'fc00::/64' +``` + +#### Destination Prefix + +For the `destination-nat66` rule, the destination address of +the packet isreplaced by the address calculated from the specified +address or prefix in the <span class="title-ref">translation address</span> command + +Example: + +- Convert the address prefix of a single <span class="title-ref">fc00::/64</span> network + to <span class="title-ref">fc01::/64</span> +- Input from <span class="title-ref">eth0</span> network interface + +``` none +set nat66 destination rule 1 inbound-interface 'eth0' +set nat66 destination rule 1 destination address 'fc00::/64' +set nat66 destination rule 1 translation address 'fc01::/64' +``` + +## Configuration Examples + +Use the following topology to build a nat66 based isolated +network between internal and external networks (dynamic prefix is +not supported): + +<figure> +<img src="/_static/images/vyos_1_4_nat66_simple.webp" alt="VyOS NAT66 Simple Configure" /> +</figure> + +R1: + +``` none +set interfaces ethernet eth0 ipv6 address autoconf +set interfaces ethernet eth1 address 'fc01::1/64' +set nat66 destination rule 1 destination address 'fc00:470:f1cd:101::/64' +set nat66 destination rule 1 inbound-interface 'eth0' +set nat66 destination rule 1 translation address 'fc01::/64' +set nat66 source rule 1 outbound-interface 'eth0' +set nat66 source rule 1 source prefix 'fc01::/64' +set nat66 source rule 1 translation address 'fc00:470:f1cd:101::/64' +``` + +R2: + +``` none +set interfaces bridge br1 address 'fc01::2/64' +set interfaces bridge br1 member interface eth0 +set interfaces bridge br1 member interface eth1 +set protocols static route6 ::/0 next-hop fc01::1 +set service router-advert interface br1 prefix ::/0 +``` + +Use the following topology to translate internal user local addresses (`fc::/7`) +to DHCPv6-PD provided prefixes from an ISP connected to a VyOS HA pair. + +<figure> +<img src="/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.webp" alt="VyOS NAT66 DHCPv6 using a dummy interface" /> +</figure> + +Configure both routers (a and b) for DHCPv6-PD via dummy interface: + +``` none +set interfaces dummy dum1 description 'DHCPv6-PD NPT dummy' +set interfaces bonding bond0 vif 20 dhcpv6-options pd 0 interface dum1 address '0' +set interfaces bonding bond0 vif 20 dhcpv6-options pd 1 interface dum1 address '0' +set interfaces bonding bond0 vif 20 dhcpv6-options pd 2 interface dum1 address '0' +set interfaces bonding bond0 vif 20 dhcpv6-options pd 3 interface dum1 address '0' +set interfaces bonding bond0 vif 20 dhcpv6-options rapid-commit +commit +``` + +Get the DHCPv6-PD prefixes from both routers: + +``` none +trae@cr01a-vyos# run show interfaces dummy dum1 br +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +dum1 2001:db8:123:b008::/64 u/u DHCPv6-PD NPT dummy + 2001:db8:123:b00a::/64 + 2001:db8:123:b00b::/64 + 2001:db8:123:b009::/64 + +trae@cr01b-vyos# run show int dummy dum1 brief +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +dum1 2001:db8:123:b00d::/64 u/u DHCPv6-PD NPT dummy + 2001:db8:123:b00c::/64 + 2001:db8:123:b00e::/64 + 2001:db8:123:b00f::/64 +``` + +Configure the A-side router for NPTv6 using the prefixes above: + +``` none +set nat66 source rule 10 description 'NPT to VLAN 10' +set nat66 source rule 10 outbound-interface name 'bond0.20' +set nat66 source rule 10 source prefix 'fd52:d62e:8011:a::/64' +set nat66 source rule 10 translation address '2001:db8:123:b008::/64' +set nat66 source rule 20 description 'NPT to VLAN 70' +set nat66 source rule 20 outbound-interface name 'bond0.20' +set nat66 source rule 20 source prefix 'fd52:d62e:8011:46::/64' +set nat66 source rule 20 translation address '2001:db8:123:b009::/64' +set nat66 source rule 30 description 'NPT to VLAN 200' +set nat66 source rule 30 outbound-interface name 'bond0.20' +set nat66 source rule 30 source prefix 'fd52:d62e:8011:c8::/64' +set nat66 source rule 30 translation address '2001:db8:123:b00a::/64' +set nat66 source rule 40 description 'NPT to VLAN 240' +set nat66 source rule 40 outbound-interface name 'bond0.20' +set nat66 source rule 40 source prefix 'fd52:d62e:8011:f0::/64' +set nat66 source rule 40 translation address '2001:db8:123:b00b::/64' +commit +``` + +Configure the B-side router for NPTv6 using the prefixes above: + +``` none +set nat66 source rule 10 description 'NPT to VLAN 10' +set nat66 source rule 10 outbound-interface name 'bond0.20' +set nat66 source rule 10 source prefix 'fd52:d62e:8011:a::/64' +set nat66 source rule 10 translation address '2001:db8:123:b00c::/64' +set nat66 source rule 20 description 'NPT to VLAN 70' +set nat66 source rule 20 outbound-interface name 'bond0.20' +set nat66 source rule 20 source prefix 'fd52:d62e:8011:46::/64' +set nat66 source rule 20 translation address '2001:db8:123:b00d::/64' +set nat66 source rule 30 description 'NPT to VLAN 200' +set nat66 source rule 30 outbound-interface name 'bond0.20' +set nat66 source rule 30 source prefix 'fd52:d62e:8011:c8::/64' +set nat66 source rule 30 translation address '2001:db8:123:b00e::/64' +set nat66 source rule 40 description 'NPT to VLAN 240' +set nat66 source rule 40 outbound-interface name 'bond0.20' +set nat66 source rule 40 source prefix 'fd52:d62e:8011:f0::/64' +set nat66 source rule 40 translation address '2001:db8:123:b00f::/64' +commit +``` + +Verify that connections are hitting the rule on both sides: + +``` none +trae@cr01a-vyos# run show nat66 source statistics +Rule Packets Bytes Interface +------ --------- ------- ----------- +10 1 104 bond0.20 +20 1 104 bond0.20 +30 8093 669445 bond0.20 +40 2446 216912 bond0.20 +``` diff --git a/docs/configuration/pki/md-index.md b/docs/configuration/pki/md-index.md new file mode 100644 index 00000000..15efb7a2 --- /dev/null +++ b/docs/configuration/pki/md-index.md @@ -0,0 +1,662 @@ +lastproofread +2024-01-05 + +# PKI + +VyOS 1.4 changed the way in how encrytion keys or certificates are stored on the +system. In the pre VyOS 1.4 era, certificates got stored under /config and every +service referenced a file. That made copying a running configuration from system +A to system B a bit harder, as you had to copy the files and their permissions +by hand. + +`T3642` describes a new CLI subsystem that serves as a "certstore" to +all services requiring any kind of encryption key(s). In short, public and +private certificates are now stored in PKCS#8 format in the regular VyOS CLI. +Keys can now be added, edited, and deleted using the regular set/edit/delete +CLI commands. + +VyOS not only can now manage certificates issued by 3rd party Certificate +Authorities, it can also act as a CA on its own. You can create your own root +CA and sign keys with it by making use of some simple op-mode commands. + +Don't be afraid that you need to re-do your configuration. Key transformation is +handled, as always, by our migration scripts, so this will be a smooth transition +for you! + +## Key Generation + +### Certificate Authority (CA) + +VyOS now also has the ability to create CAs, keys, Diffie-Hellman and other +keypairs from an easy to access operational level command. + +<div class="opcmd"> + +generate pki ca + +Create a new `CA (Certificate Authority)` and output the CAs public and +private key on the console. + +</div> + +<div class="opcmd"> + +generate pki ca install \<name\> + +Create a new `CA (Certificate Authority)` and output the CAs public and +private key on the console. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +In addition to the command above, the output is in a format which can +be used to directly import the key into the VyOS CLI by simply copy-pasting +the output from op-mode into configuration mode. + +`name` is used for the VyOS CLI command to identify this key. This +key `name` is then used in the CLI configuration to reference the key +instance. + +</div> + +</div> + +<div class="opcmd"> + +generate pki ca sign \<ca-name\> + +Create a new subordinate `CA (Certificate Authority)` and sign it using +the private key referenced by <span class="title-ref">ca-name</span>. + +</div> + +<div class="opcmd"> + +generate pki ca sign \<ca-name\> install \<name\> + +Create a new subordinate `CA (Certificate Authority)` and sign it using +the private key referenced by <span class="title-ref">name</span>. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +In addition to the command above, the output is in a format which can +be used to directly import the key into the VyOS CLI by simply copy-pasting +the output from op-mode into configuration mode. + +`name` is used for the VyOS CLI command to identify this key. This +key `name` is then used in the CLI configuration to reference the key +instance. + +</div> + +</div> + +### Certificates + +<div class="opcmd"> + +generate pki certificate + +Create a new public/private keypair and output the certificate on the console. + +</div> + +<div class="opcmd"> + +generate pki certificate install \<name\> + +Create a new public/private keypair and output the certificate on the console. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +In addition to the command above, the output is in a format which can +be used to directly import the key into the VyOS CLI by simply copy-pasting +the output from op-mode into configuration mode. + +`name` is used for the VyOS CLI command to identify this key. This +key `name` is then used in the CLI configuration to reference the key +instance. + +</div> + +</div> + +<div class="opcmd"> + +generate pki certificate self-signed + +Create a new self-signed certificate. The public/private is then shown on the +console. + +</div> + +<div class="opcmd"> + +generate pki certificate self-signed install \<name\> + +Create a new self-signed certificate. The public/private is then shown on the +console. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +In addition to the command above, the output is in a format which can +be used to directly import the key into the VyOS CLI by simply copy-pasting +the output from op-mode into configuration mode. + +`name` is used for the VyOS CLI command to identify this key. This +key `name` is then used in the CLI configuration to reference the key +instance. + +</div> + +</div> + +<div class="opcmd"> + +generate pki certificate sign \<ca-name\> + +Create a new public/private keypair which is signed by the CA referenced by +<span class="title-ref">ca-name</span>. The signed certificate is then output to the console. + +</div> + +<div class="opcmd"> + +generate pki certificate sign \<ca-name\> install \<name\> + +Create a new public/private keypair which is signed by the CA referenced by +<span class="title-ref">ca-name</span>. The signed certificate is then output to the console. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +In addition to the command above, the output is in a format which can +be used to directly import the key into the VyOS CLI by simply copy-pasting +the output from op-mode into configuration mode. + +`name` is used for the VyOS CLI command to identify this key. This +key `name` is then used in the CLI configuration to reference the key +instance. + +</div> + +</div> + +### Diffie-Hellman parameters + +<div class="opcmd"> + +generate pki dh + +Generate a new set of `DH (Diffie-Hellman)` parameters. The key size +is requested by the CLI and defaults to 2048 bit. + +The generated parameters are then output to the console. + +</div> + +<div class="opcmd"> + +generate pki dh install \<name\> + +Generate a new set of `DH (Diffie-Hellman)` parameters. The key size +is requested by the CLI and defaults to 2048 bit. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +In addition to the command above, the output is in a format which can +be used to directly import the key into the VyOS CLI by simply copy-pasting +the output from op-mode into configuration mode. + +`name` is used for the VyOS CLI command to identify this key. This +key `name` is then used in the CLI configuration to reference the key +instance. + +</div> + +</div> + +### OpenVPN + +<div class="opcmd"> + +generate pki openvpn shared-secret + +Genearate a new OpenVPN shared secret. The generated secred is the output to +the console. + +</div> + +<div class="opcmd"> + +generate pki openvpn shared-secret install \<name\> + +Genearate a new OpenVPN shared secret. The generated secred is the output to +the console. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +In addition to the command above, the output is in a format which can +be used to directly import the key into the VyOS CLI by simply copy-pasting +the output from op-mode into configuration mode. + +`name` is used for the VyOS CLI command to identify this key. This +key `name` is then used in the CLI configuration to reference the key +instance. + +</div> + +</div> + +### WireGuard + +<div class="opcmd"> + +generate pki wireguard key-pair + +Generate a new WireGuard public/private key portion and output the result to +the console. + +</div> + +<div class="opcmd"> + +generate pki wireguard key-pair install \<interface\> + +Generate a new WireGuard public/private key portion and output the result to +the console. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +In addition to the command above, the output is in a format which can +be used to directly import the key into the VyOS CLI by simply copy-pasting +the output from op-mode into configuration mode. + +`interface` is used for the VyOS CLI command to identify the WireGuard +interface where this private key is to be used. + +</div> + +</div> + +<div class="opcmd"> + +generate pki wireguard pre-shared-key + +Generate a WireGuard pre-shared secret used for peers to communicate. + +</div> + +<div class="opcmd"> + +generate pki wireguard pre-shared-key install \<peer\> + +Generate a WireGuard pre-shared secret used for peers to communicate. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +In addition to the command above, the output is in a format which can +be used to directly import the key into the VyOS CLI by simply copy-pasting +the output from op-mode into configuration mode. + +`peer` is used for the VyOS CLI command to identify the WireGuard peer where +this secred is to be used. + +</div> + +</div> + +## Key usage (CLI) + +### CA (Certificate Authority) + +<div class="cfgcmd"> + +set pki ca \<name\> certificate + +Add the public CA certificate for the CA named <span class="title-ref">name</span> to the VyOS CLI. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +When loading the certificate you need to manually strip the +`-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` tags. +Also, the certificate/key needs to be presented in a single line without +line breaks (`\n`), this can be done using the following shell command: + +`$ tail -n +2 ca.pem | head -n -1 | tr -d '\n'` + +</div> + +</div> + +<div class="cfgcmd"> + +set pki ca \<name\> crl + +Certificate revocation list in PEM format. + +</div> + +<div class="cfgcmd"> + +set pki ca \<name\> description + +A human readable description what this CA is about. + +</div> + +<div class="cfgcmd"> + +set pki ca \<name\> private key + +Add the CAs private key to the VyOS CLI. This should never leave the system, +and is only required if you use VyOS as your certificate generator as +mentioned above. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +When loading the certificate you need to manually strip the +`-----BEGIN KEY-----` and `-----END KEY-----` tags. Also, the +certificate/key needs to be presented in a single line without line +breaks (`\n`), this can be done using the following shell command: + +`$ tail -n +2 ca.key | head -n -1 | tr -d '\n'` + +</div> + +</div> + +<div class="cfgcmd"> + +set pki ca \<name\> private password-protected + +Mark the CAs private key as password protected. User is asked for the password +when the key is referenced. + +</div> + +### Server Certificate + +After we have imported the CA certificate(s) we can now import and add +certificates used by services on this router. + +<div class="cfgcmd"> + +set pki certificate \<name\> certificate + +Add public key portion for the certificate named <span class="title-ref">name</span> to the VyOS CLI. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +When loading the certificate you need to manually strip the +`-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` tags. +Also, the certificate/key needs to be presented in a single line without +line breaks (`\n`), this can be done using the following shell command: + +`$ tail -n +2 cert.pem | head -n -1 | tr -d '\n'` + +</div> + +</div> + +<div class="cfgcmd"> + +set pki certificate \<name\> description + +A human readable description what this certificate is about. + +</div> + +<div class="cfgcmd"> + +set pki certificate \<name\> private key + +Add the private key portion of this certificate to the CLI. This should never +leave the system as it is used to decrypt the data. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +When loading the certificate you need to manually strip the +`-----BEGIN KEY-----` and `-----END KEY-----` tags. Also, the +certificate/key needs to be presented in a single line without line +breaks (`\n`), this can be done using the following shell command: + +`$ tail -n +2 cert.key | head -n -1 | tr -d '\n'` + +</div> + +</div> + +<div class="cfgcmd"> + +set pki certificate \<name\> private password-protected + +Mark the private key as password protected. User is asked for the password +when the key is referenced. + +</div> + +<div class="cfgcmd"> + +set pki certificate \<name\> revoke + +If CA is present, this certificate will be included in generated CRLs + +</div> + +#### ACME + +The VyOS PKI subsystem can also be used to automatically retrieve Certificates +using the `ACME (Automatic Certificate Management Environment)` protocol. +VyOS 1.4.1 does not store the intermediate certificates from ACME. Which makes +this functionality limited. See `T7299`. + +<div class="cfgcmd"> + +set pki certificate \<name\> acme domain-name \<name\> + +Domain names to apply, multiple domain-names can be specified. + +This is a mandatory option + +</div> + +<div class="cfgcmd"> + +set pki certificate \<name\> acme email \<address\> + +Email used for registration and recovery contact. + +This is a mandatory option + +</div> + +<div class="cfgcmd"> + +set pki certificate \<name\> acme listen-address \<address\> + +The address the server listens to during http-01 challenge + +</div> + +<div class="cfgcmd"> + +set pki certificate \<name\> acme rsa-key-size \<2048 | 3072 | 4096\> + +Size of the RSA key. + +This options defaults to 2048 + +</div> + +<div class="cfgcmd"> + +set pki certificate \<name\> acme url \<url\> + +ACME Directory Resource URI. + +This defaults to <https://acme-v02.api.letsencrypt.org/directory> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +During initial deployment we recommend using the staging API +of LetsEncrypt to prevent and blacklisting of your system. The API +endpoint is <https://acme-staging-v02.api.letsencrypt.org/directory> + +</div> + +</div> + +## Operation + +VyOS operational mode commands are not only available for generating keys but +also to display them. + +<div class="opcmd"> + +show pki ca + +Show a list of installed `CA (Certificate Authority)` certificates. + +``` none +vyos@vyos:~$ show pki ca +Certificate Authorities: +Name Subject Issuer CN Issued Expiry Private Key Parent +-------------- ------------------------------------------------------- ----------------- ------------------- ------------------- ------------- -------------- +DST_Root_CA_X3 CN=ISRG Root X1,O=Internet Security Research Group,C=US CN=DST Root CA X3 2021-01-20 19:14:03 2024-09-30 18:14:03 No N/A +R3 CN=R3,O=Let's Encrypt,C=US CN=ISRG Root X1 2020-09-04 00:00:00 2025-09-15 16:00:00 No DST_Root_CA_X3 +vyos_rw CN=VyOS RW CA,O=VyOS,L=Some-City,ST=Some-State,C=GB CN=VyOS RW CA 2021-07-05 13:46:03 2026-07-04 13:46:03 Yes N/A +``` + +</div> + +<div class="opcmd"> + +show pki ca \<name\> + +Show only information for specified Certificate Authority. + +</div> + +<div class="opcmd"> + +show pki certificate + +Show a list of installed certificates + +``` none +vyos@vyos:~$ show pki certificate +Certificates: +Name Type Subject CN Issuer CN Issued Expiry Revoked Private Key CA Present +--------- ------ --------------------- ------------- ------------------- ------------------- --------- ------------- ------------- +ac2 Server CN=ac2.vyos.net CN=R3 2021-07-05 07:29:59 2021-10-03 07:29:58 No Yes Yes (R3) +rw_server Server CN=VyOS RW CN=VyOS RW CA 2021-07-05 13:48:02 2022-07-05 13:48:02 No Yes Yes (vyos_rw) +``` + +</div> + +<div class="opcmd"> + +show pki certificate \<name\> + +Show only information for specified certificate. + +</div> + +<div class="opcmd"> + +show pki crl + +Show a list of installed `CRLs (Certificate Revocation List)`. + +</div> + +<div class="opcmd"> + +renew certbot + +Manually trigger certificate renewal. This will be done twice a day. + +</div> diff --git a/docs/configuration/policy/md-access-list.md b/docs/configuration/policy/md-access-list.md new file mode 100644 index 00000000..4a1468b0 --- /dev/null +++ b/docs/configuration/policy/md-access-list.md @@ -0,0 +1,96 @@ +# Access List Policy + +Filtering is used for both input and output of the routing information. Once +filtering is defined, it can be applied in any direction. VyOS makes filtering +possible using acls and prefix lists. + +Basic filtering can be done using access-list and access-list6. + +## Configuration + +### Access Lists + +<div class="cfgcmd"> + +set policy access-list \<acl_number\> + +This command creates the new access list policy, where \<acl_number\> must be +a number from 1 to 2699. + +</div> + +<div class="cfgcmd"> + +set policy access-list \<acl_number\> description \<text\> + +Set description for the access list. + +</div> + +<div class="cfgcmd"> + +set policy access-list \<acl_number\> rule \<1-65535\> action +\<permit|deny\> + +This command creates a new rule in the access list and defines an action. + +</div> + +<div class="cfgcmd"> + +set policy access-list \<acl_number\> rule \<1-65535\> +\<destination[|source\> \<any|](##SUBST##|source> <any|)host[|inverse-mask|](##SUBST##|inverse-mask|)network\> + +This command defines matching parameters for access list rule. Matching +criteria could be applied to destination or source parameters: + +- any: any IP address to match. +- host: single host IP address to match. +- inverse-match: network/netmask to match (requires network be defined). +- network: network/netmask to match (requires inverse-match be defined). + +</div> + +### IPv6 Access List + +Basic filtering could also be applied to IPv6 traffic. + +<div class="cfgcmd"> + +set policy access-list6 \<text\> + +This command creates the new IPv6 access list, identified by \<text\> + +</div> + +<div class="cfgcmd"> + +set policy access-list6 \<text\> description \<text\> + +Set description for the IPv6 access list. + +</div> + +<div class="cfgcmd"> + +set policy access-list6 \<text\> rule \<1-65535\> action \<permit|deny\> + +This command creates a new rule in the IPv6 access list and defines an +action. + +</div> + +<div class="cfgcmd"> + +set policy access-list6 \<text\> rule \<1-65535\> source +\<any[|exact-match|](##SUBST##|exact-match|)network\> + +This command defines matching parameters for IPv6 access list rule. Matching +criteria could be applied to source parameters: + +- any: any IPv6 address to match. +- exact-match: exact match of the network prefixes. +- network: network/netmask to match (requires inverse-match be defined) BUG, + NO invert-match option in access-list6 + +</div> diff --git a/docs/configuration/policy/md-as-path-list.md b/docs/configuration/policy/md-as-path-list.md new file mode 100644 index 00000000..5fdebe29 --- /dev/null +++ b/docs/configuration/policy/md-as-path-list.md @@ -0,0 +1,48 @@ +# BGP - AS Path Policy + +VyOS provides policies commands exclusively for BGP traffic filtering and +manipulation: **as-path-list** is one of them. + +## Configuration + +### policy as-path-list + +<div class="cfgcmd"> + +set policy as-path-list \<text\> + +Create as-path-policy identified by name \<text\>. + +</div> + +<div class="cfgcmd"> + +set policy as-path-list \<text\> description \<text\> + +Set description for as-path-list policy. + +</div> + +<div class="cfgcmd"> + +set policy as-path-list \<text\> rule \<1-65535\> action \<permit|deny\> + +Set action to take on entries matching this rule. + +</div> + +<div class="cfgcmd"> + +set policy as-path-list \<text\> rule \<1-65535\> description \<text\> + +Set description for rule. + +</div> + +<div class="cfgcmd"> + +set policy as-path-list \<text\> rule \<1-65535\> regex \<text\> + +Regular expression to match against an AS path. For example "64501 64502". + +</div> diff --git a/docs/configuration/policy/md-community-list.md b/docs/configuration/policy/md-community-list.md new file mode 100644 index 00000000..943d59ca --- /dev/null +++ b/docs/configuration/policy/md-community-list.md @@ -0,0 +1,50 @@ +# BGP - Community List + +VyOS provides policies commands exclusively for BGP traffic filtering and +manipulation: **community-list** is one of them. + +## Configuration + +### policy community-list + +<div class="cfgcmd"> + +set policy community-list \<text\> + +Creat community-list policy identified by name \<text\>. + +</div> + +<div class="cfgcmd"> + +set policy community-list \<text\> description \<text\> + +Set description for community-list policy. + +</div> + +<div class="cfgcmd"> + +set policy community-list \<text\> rule \<1-65535\> action +\<permit|deny\> + +Set action to take on entries matching this rule. + +</div> + +<div class="cfgcmd"> + +set policy community-list \<text\> rule \<1-65535\> description \<text\> + +Set description for rule. + +</div> + +<div class="cfgcmd"> + +set policy community-list \<text\> rule \<1-65535\> regex +\<aa:nn[|local-AS|](##SUBST##|local-AS|)no-advertise[|no-export|](##SUBST##|no-export|)internet|additive\> + +Regular expression to match against a community-list. + +</div> diff --git a/docs/configuration/policy/md-examples.md b/docs/configuration/policy/md-examples.md new file mode 100644 index 00000000..9b2717cb --- /dev/null +++ b/docs/configuration/policy/md-examples.md @@ -0,0 +1,201 @@ +# BGP Example + +**Policy definition:** + +``` none +# Create policy +set policy route-map setmet rule 2 action 'permit' +set policy route-map setmet rule 2 set as-path prepend '2 2 2' + +# Apply policy to BGP +set protocols bgp system-as 1 +set protocols bgp neighbor 203.0.113.2 address-family ipv4-unicast route-map import 'setmet' +set protocols bgp neighbor 203.0.113.2 address-family ipv4-unicast soft-reconfiguration 'inbound' +``` + +Using 'soft-reconfiguration' we get the policy update without bouncing the +neighbor. + +**Routes learned before routing policy applied:** + +``` none +vyos@vos1:~$ show ip bgp +BGP table version is 0, local router ID is 192.168.56.101 +Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, + r RIB-failure, S Stale, R Removed +Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path +*> 198.51.100.3/32 203.0.113.2 1 0 2 i < Path + +Total number of prefixes 1 +``` + +**Routes learned after routing policy applied:** + +``` none +vyos@vos1:~$ show ip bgp +BGP table version is 0, local router ID is 192.168.56.101 +Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, + r RIB-failure, S Stale, R Removed +Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path +*> 198.51.100.3/32 203.0.113.2 1 0 2 2 2 2 i + +Total number of prefixes 1 +vyos@vos1:~$ +``` + +You now see the longer AS path. + +# Transparent Proxy + +The following example will show how VyOS can be used to redirect web +traffic to an external transparent proxy: + +``` none +set policy route FILTER-WEB rule 1000 destination port 80 +set policy route FILTER-WEB rule 1000 protocol tcp +set policy route FILTER-WEB rule 1000 set table 100 +``` + +This creates a route policy called FILTER-WEB with one rule to set the +routing table for matching traffic (TCP port 80) to table ID 100 +instead of the default routing table. + +To create routing table 100 and add a new default gateway to be used by +traffic matching our route policy: + +``` none +set protocols static table 100 route 0.0.0.0/0 next-hop 10.255.0.2 +``` + +This can be confirmed using the `show ip route table 100` operational +command. + +Finally, to apply the policy route to ingress traffic on our LAN +interface, we use: + +``` none +set policy route FILTER-WEB interface eth1 +``` + +# Multiple Uplinks + +VyOS Policy-Based Routing (PBR) works by matching source IP address +ranges and forwarding the traffic using different routing tables. + +Routing tables that will be used in this example are: + +- `table 10` Routing table used for VLAN 10 (192.168.188.0/24) +- `table 11` Routing table used for VLAN 11 (192.168.189.0/24) +- `main` Routing table used by VyOS and other interfaces not + participating in PBR + +<figure> +<img src="/_static/images/pbr_example_1.webp" alt="PBR multiple uplinks" /> +<figcaption>Policy-Based Routing with multiple ISP uplinks +(source ./draw.io/pbr_example_1.drawio)</figcaption> +</figure> + +Add default routes for routing `table 10` and `table 11` + +``` none +set protocols static table 10 route 0.0.0.0/0 next-hop 192.0.2.1 +set protocols static table 11 route 0.0.0.0/0 next-hop 192.0.2.2 +``` + +Add policy route matching VLAN source addresses + +``` none +set policy route PBR rule 20 set table '10' +set policy route PBR rule 20 description 'Route VLAN10 traffic to table 10' +set policy route PBR rule 20 source address '192.168.188.0/24' + +set policy route PBR rule 30 set table '11' +set policy route PBR rule 30 description 'Route VLAN11 traffic to table 11' +set policy route PBR rule 30 source address '192.168.189.0/24' +``` + +Apply routing policy to **inbound** direction of out VLAN interfaces + +``` none +set policy route 'PBR' interface eth0.10 +set policy route 'PBR' interface eth0.11 +``` + +**OPTIONAL:** Exclude Inter-VLAN traffic (between VLAN10 and VLAN11) +from PBR + +``` none +set firewall group network-group VLANS-GR description 'VLANs networks' +set firewall group network-group VLANS-GR network '192.168.188.0/24' +set firewall group network-group VLANS-GR network '192.168.189.0/24' + +set policy route PBR rule 10 description 'VLAN10 <-> VLAN11 shortcut' +set policy route PBR rule 10 destination group network-group 'VLANS-GR' +set policy route PBR rule 10 set table 'main' +``` + +These commands allow the VLAN10 and VLAN11 hosts to communicate with +each other using the main routing table. + +## Local route + +The following example allows VyOS to use `PBR (Policy-Based Routing)` +for traffic, which originated from the router itself. That solution for multiple +ISP's and VyOS router will respond from the same interface that the packet was +received. Also, it used, if we want that one VPN tunnel to be through one +provider, and the second through another. + +- `203.0.113.254` IP addreess on VyOS eth1 from ISP1 +- `192.168.2.254` IP addreess on VyOS eth2 from ISP2 +- `table 10` Routing table used for ISP1 +- `table 11` Routing table used for ISP2 + +``` none +set policy local-route rule 101 set table '10' +set policy local-route rule 101 source address '203.0.113.254' +set policy local-route rule 102 set table '11' +set policy local-route rule 102 source address '192.0.2.254' +set protocols static table 10 route 0.0.0.0/0 next-hop '203.0.113.1' +set protocols static table 11 route 0.0.0.0/0 next-hop '192.0.2.2' +``` + +Add multiple source IP in one rule with same priority + +``` none +set policy local-route rule 101 set table '10' +set policy local-route rule 101 source address '203.0.113.254' +set policy local-route rule 101 source address '203.0.113.253' +set policy local-route rule 101 source address '198.51.100.0/24' +``` + +# Clamp MSS for a specific IP + +This example shows how to target an MSS clamp (in our example to 1360 bytes) +to a specific destination IP. + +``` none +set policy route IP-MSS-CLAMP rule 10 description 'Clamp TCP session MSS to 1360 for 198.51.100.30' +set policy route IP-MSS-CLAMP rule 10 destination address '198.51.100.30/32' +set policy route IP-MSS-CLAMP rule 10 protocol 'tcp' +set policy route IP-MSS-CLAMP rule 10 set tcp-mss '1360' +set policy route IP-MSS-CLAMP rule 10 tcp flags 'SYN' +``` + +To apply this policy to the correct interface, configure it on the +interface the inbound local host will send through to reach our +destined target host (in our example eth1). + +``` none +set policy route IP-MSS-CLAMP interface eth1 +``` + +You can view that the policy is being correctly (or incorrectly) utilised +with the following command: + +``` none +show policy route statistics +``` diff --git a/docs/configuration/policy/md-extcommunity-list.md b/docs/configuration/policy/md-extcommunity-list.md new file mode 100644 index 00000000..d05315dd --- /dev/null +++ b/docs/configuration/policy/md-extcommunity-list.md @@ -0,0 +1,55 @@ +# BGP - Extended Community List + +VyOS provides policies commands exclusively for BGP traffic filtering and +manipulation: **extcommunity-list** is one of them. + +## Configuration + +### policy extcommunity-list + +<div class="cfgcmd"> + +set policy extcommunity-list \<text\> + +Creat extcommunity-list policy identified by name \<text\>. + +</div> + +<div class="cfgcmd"> + +set policy extcommunity-list \<text\> description \<text\> + +Set description for extcommunity-list policy. + +</div> + +<div class="cfgcmd"> + +set policy extcommunity-list \<text\> rule \<1-65535\> action +\<permit|deny\> + +Set action to take on entries matching this rule. + +</div> + +<div class="cfgcmd"> + +set policy extcommunity-list \<text\> rule \<1-65535\> description +\<text\> + +Set description for rule. + +</div> + +<div class="cfgcmd"> + +set policy extcommunity-list \<text\> rule \<1-65535\> regex \<text\> + +Regular expression to match against an extended community list, where text +could be: + +- \<aa:nn:nn\>: Extended community list regular expression. +- \<rt aa:nn:nn\>: Route Target regular expression. +- \<soo aa:nn:nn\>: Site of Origin regular expression. + +</div> diff --git a/docs/configuration/policy/md-index.md b/docs/configuration/policy/md-index.md new file mode 100644 index 00000000..91e20aa7 --- /dev/null +++ b/docs/configuration/policy/md-index.md @@ -0,0 +1,46 @@ +:lastproofread:2021-07-12 + +# Policy + +Policies are used for filtering and traffic management. With policies, network +administrators could filter and treat traffic +according to their needs. + +There could be a wide range of routing policies. Some examples are listed +below: + +- Filter traffic based on source/destination address. +- Set some metric to routes learned from a particular neighbor. +- Set some attributes (like AS PATH or Community value) to advertised routes + to neighbors. +- Prefer a specific routing protocol routes over another routing protocol + running on the same router. + +Policies, in VyOS, are implemented using FRR filtering and route maps. Detailed +information of FRR could be found in <http://docs.frrouting.org/> + +## Policy Sections + +<div class="toctree" maxdepth="1" includehidden=""> + +access-list +prefix-list +route +route-map +local-route +as-path-list +community-list +extcommunity-list +large-community-list + +</div> + +## Examples + +Examples of policies usage: + +<div class="toctree" maxdepth="1" includehidden=""> + +examples + +</div> diff --git a/docs/configuration/policy/md-large-community-list.md b/docs/configuration/policy/md-large-community-list.md new file mode 100644 index 00000000..00888140 --- /dev/null +++ b/docs/configuration/policy/md-large-community-list.md @@ -0,0 +1,51 @@ +# BGP - Large Community List + +VyOS provides policies commands exclusively for BGP traffic filtering and +manipulation: **large-community-list** is one of them. + +## Configuration + +### policy large-community-list + +<div class="cfgcmd"> + +set policy large-community-list \<text\> + +Create large-community-list policy identified by name \<text\>. + +</div> + +<div class="cfgcmd"> + +set policy large-community-list \<text\> description \<text\> + +Set description for large-community-list policy. + +</div> + +<div class="cfgcmd"> + +set policy large-community-list \<text\> rule \<1-65535\> action +\<permit|deny\> + +Set action to take on entries matching this rule. + +</div> + +<div class="cfgcmd"> + +set policy large-community-list \<text\> rule \<1-65535\> description +\<text\> + +Set description for rule. + +</div> + +<div class="cfgcmd"> + +set policy large-community-list \<text\> rule \<1-65535\> regex +\<aa:nn:nn\> + +Regular expression to match against a large community list. + +</div> diff --git a/docs/configuration/policy/md-local-route.md b/docs/configuration/policy/md-local-route.md new file mode 100644 index 00000000..17afb7f8 --- /dev/null +++ b/docs/configuration/policy/md-local-route.md @@ -0,0 +1,73 @@ +# Local Route Policy + +Policies for local traffic are defined in this section. + +## Configuration + +### Local Route IPv4 + +<div class="cfgcmd"> + +set policy local-route rule \<1-32765\> set table \<1-200|main\> + +Set routing table to forward packet to. + +</div> + +<div class="cfgcmd"> + +set policy local-route rule \<1-32765\> source \<x.x.x.x|x.x.x.x/x\> + +Set source address or prefix to match. + +</div> + +<div class="cfgcmd"> + +set policy local-route rule \<1-32765\> destination \<x.x.x.x|x.x.x.x/x\> + +Set destination address or prefix to match. + +</div> + +<div class="cfgcmd"> + +set policy local-route rule \<1-32765\> inbound-interface \<interface\> + +Set inbound interface to match. + +</div> + +### Local Route IPv6 + +<div class="cfgcmd"> + +set policy local-route6 rule \<1-32765\> set table \<1-200|main\> + +Set routing table to forward packet to. + +</div> + +<div class="cfgcmd"> + +set policy local-route6 rule \<1-32765\> source \<h:h:h:h:h:h:h:h | h:h:h:h:h:h:h:h/x\> + +Set source address or prefix to match. + +</div> + +<div class="cfgcmd"> + +set policy local-route6 rule \<1-32765\> destination \<h:h:h:h:h:h:h:h | h:h:h:h:h:h:h:h/x\> + +Set destination address or prefix to match. + +</div> + +<div class="cfgcmd"> + +set policy local-route6 rule \<1-32765\> inbound-interface \<interface\> + +Set inbound interface to match. + +</div> diff --git a/docs/configuration/policy/md-prefix-list.md b/docs/configuration/policy/md-prefix-list.md new file mode 100644 index 00000000..d0490249 --- /dev/null +++ b/docs/configuration/policy/md-prefix-list.md @@ -0,0 +1,190 @@ +# Prefix List Policy + +Prefix lists provides the most powerful prefix based filtering mechanism. In +addition to access-list functionality, ip prefix-list has prefix length range +specification. + +If no ip prefix list is specified, it acts as permit. If ip prefix list is +defined, and no match is found, default deny is applied. + +Prefix filtering can be done using prefix-list and prefix-list6. + +## Configuration + +### Prefix Lists + +<div class="cfgcmd"> + +set policy prefix-list \<text\> + +This command creates the new prefix-list policy, identified by \<text\>. + +</div> + +<div class="cfgcmd"> + +set policy prefix-list \<text\> description \<text\> + +Set description for the prefix-list policy. + +</div> + +<div class="cfgcmd"> + +set policy prefix-list \<text\> rule \<1-65535\> action \<permit|deny\> + +This command creates a new rule in the prefix-list and defines an action. + +</div> + +<div class="cfgcmd"> + +set policy prefix-list \<text\> rule \<1-65535\> description \<text\> + +Set description for rule in the prefix-list. + +</div> + +<div class="cfgcmd"> + +set policy prefix-list \<text\> rule \<1-65535\> prefix \<x.x.x.x/x\> + +Prefix to match against. + +</div> + +<div class="cfgcmd"> + +set policy prefix-list \<text\> rule \<1-65535\> ge \<0-32\> + +Netmask greater than length. + +</div> + +<div class="cfgcmd"> + +set policy prefix-list \<text\> rule \<1-65535\> le \<0-32\> + +Netmask less than length + +</div> + +Example: Prefix Lists +============ + +This example creates an IPv4 prefix-list named PL4-EXAMPLE-NAME, defines 3 +rules each with 1 prefix, and matches le (less than/equal to) /32. + +<div class="cfgcmd"> + +set policy prefix-list PL4-EXAMPLE-NAME rule 10 action 'permit' + +</div> + +<div class="cfgcmd"> + +set policy prefix-list PL4-EXAMPLE-NAME rule 10 le '32' + +</div> + +<div class="cfgcmd"> + +set policy prefix-list PL4-EXAMPLE-NAME rule 10 prefix '192.0.2.0/24' + +</div> + +<div class="cfgcmd"> + +set policy prefix-list PL4-EXAMPLE-NAME rule 20 action 'permit' + +</div> + +<div class="cfgcmd"> + +set policy prefix-list PL4-EXAMPLE-NAME rule 20 le '32' + +</div> + +<div class="cfgcmd"> + +set policy prefix-list PL4-EXAMPLE-NAME rule 20 prefix '198.51.100.0/24' + +</div> + +<div class="cfgcmd"> + +set policy prefix-list PL4-EXAMPLE-NAME rule 30 action 'permit' + +</div> + +<div class="cfgcmd"> + +set policy prefix-list PL4-EXAMPLE-NAME rule 30 le '32' + +</div> + +<div class="cfgcmd"> + +set policy prefix-list PL4-EXAMPLE-NAME rule 30 prefix '203.0.113.0/24' + +</div> + +### IPv6 Prefix Lists + +<div class="cfgcmd"> + +set policy prefix-list6 \<text\> + +This command creates the new IPv6 prefix-list policy, identified by \<text\>. + +</div> + +<div class="cfgcmd"> + +set policy prefix-list6 \<text\> description \<text\> + +Set description for the IPv6 prefix-list policy. + +</div> + +<div class="cfgcmd"> + +set policy prefix-list6 \<text\> rule \<1-65535\> action \<permit|deny\> + +This command creates a new rule in the IPv6 prefix-list and defines an +action. + +</div> + +<div class="cfgcmd"> + +set policy prefix-list6 \<text\> rule \<1-65535\> description \<text\> + +Set description for rule in IPv6 prefix-list. + +</div> + +<div class="cfgcmd"> + +set policy prefix-list6 \<text\> rule \<1-65535\> prefix +\<h:h:h:h:h:h:h:h/x\> + +IPv6 prefix. + +</div> + +<div class="cfgcmd"> + +set policy prefix-list6 \<text\> rule \<1-65535\> ge \<0-128\> + +Netmask greater than length. + +</div> + +<div class="cfgcmd"> + +set policy prefix-list6 \<text\> rule \<1-65535\> le \<0-128\> + +Netmask less than length + +</div> diff --git a/docs/configuration/policy/md-route-map.md b/docs/configuration/policy/md-route-map.md new file mode 100644 index 00000000..4c356e5d --- /dev/null +++ b/docs/configuration/policy/md-route-map.md @@ -0,0 +1,651 @@ +# Route Map Policy + +Route map is a powerfull command, that gives network administrators a very +useful and flexible tool for traffic manipulation. + +## Configuration + +### Route Map + +<div class="cfgcmd"> + +set policy route-map \<text\> + +This command creates a new route-map policy, identified by \<text\>. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> description \<text\> + +Set description for the route-map policy. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> action \<permit|deny\> + +Set action for the route-map policy. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> call \<text\> + +Call another route-map policy on match. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> continue \<1-65535\> + +Jump to a different rule in this route-map on a match. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> description \<text\> + +Set description for the rule in the route-map policy. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match as-path \<text\> + +BGP as-path list to match. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match community +community-list \<text\> + +BGP community-list to match. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match community +exact-match + +Set BGP community-list to exactly match. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match extcommunity +\<text\> + +BGP extended community to match. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match interface \<text\> + +First hop interface of a route to match. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match ip address +access-list \<1-2699\> + +IP address of route to match, based on access-list. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match ip address +prefix-list \<text\> + +IP address of route to match, based on prefix-list. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match ip address +prefix-len \<0-32\> + +IP address of route to match, based on specified prefix-length. +Note that this can be used for kernel routes only. +Do not apply to the routes of dynamic routing protocols (e.g. BGP, +RIP, OSFP), as this can lead to unexpected results.. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match ip nexthop +access-list \<1-2699\> + +IP next-hop of route to match, based on access-list. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match ip nexthop +address \<x.x.x.x\> + +IP next-hop of route to match, based on ip address. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match ip nexthop +prefix-len \<0-32\> + +IP next-hop of route to match, based on prefix length. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match ip nexthop +prefix-list \<text\> + +IP next-hop of route to match, based on prefix-list. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match ip nexthop +type \<blackhole\> + +IP next-hop of route to match, based on type. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match ip route-source +access-list \<1-2699\> + +IP route source of route to match, based on access-list. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match ip route-source +prefix-list \<text\> + +IP route source of route to match, based on prefix-list. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match ipv6 address +access-list \<text\> + +IPv6 address of route to match, based on IPv6 access-list. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match ipv6 address +prefix-list \<text\> + +IPv6 address of route to match, based on IPv6 prefix-list. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match ipv6 address +prefix-len \<0-128\> + +IPv6 address of route to match, based on specified prefix-length. +Note that this can be used for kernel routes only. +Do not apply to the routes of dynamic routing protocols (e.g. BGP, +RIP, OSFP), as this can lead to unexpected results.. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match ipv6 nexthop +\<h:h:h:h:h:h:h:h\> + +Nexthop IPv6 address to match. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match large-community +large-community-list \<text\> + +Match BGP large communities. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match local-preference +\<0-4294967295\> + +Match local preference. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match metric \<1-65535\> + +Match route metric. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match origin +\<egp[|igp|](##SUBST##|igp|)incomplete\> + +Boarder Gateway Protocol (BGP) origin code to match. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match peer \<x.x.x.x\> + +Peer IP address to match. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match protocol \<protocol\> + +Source protocol to match. +- `babel` - Babel routing protocol (Babel) +- `bgp` - Border Gateway Protocol (BGP) +- `connected` - Connected routes (directly attached subnet or host) +- `isis` - Intermediate System to Intermediate System (IS-IS) +- `kernel` - Kernel routes +- `ospf` - Open Shortest Path First (OSPFv2) +- `ospfv3` - Open Shortest Path First (IPv6) (OSPFv3) +- `rip` - Routing Information Protocol (RIP) +- `ripng` - Routing Information Protocol next-generation (IPv6) (RIPng) +- `static` - Statically configured routes +- `table` - Non-main Kernel Routing Table +- `vnc` - Virtual Network Control (VNC) + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match rpki +\<invalid[|notfound|](##SUBST##|notfound|)valid\> + +Match RPKI validation result. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match source-vrf \<text\> + +Source VRF to match. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> match tag \<1-65535\> + +Route tag to match. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> on-match goto \<1-65535\> + +Exit policy on match: go to rule \<1-65535\> + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> on-match next + +Exit policy on match: go to next sequence number. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set aggregator \<as[|ip\> +\<1-4294967295|](##SUBST##|ip> +<1-4294967295|)x.x.x.x\> + +BGP aggregator attribute: AS number or IP address of an aggregation. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set as-path exclude +\<1-4294967295 | all\> + +Drop AS-NUMBER from the BGP AS path. + +If `all` is specified, remove all AS numbers from the AS_PATH of the BGP +path's NLRI. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set as-path prepend +\<1-4294967295\> + +Prepend the given string of AS numbers to the AS_PATH of the BGP path's NLRI. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set as-path +prepend-last-as \<n\> + +Prepend the existing last AS number (the leftmost ASN) to the AS_PATH. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set atomic-aggregate + +BGP atomic aggregate attribute. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set community +\<add|replace\> \<community\> + +Add or replace BGP community attribute in format `<0-65535:0-65535>` +or from well-known community list + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set community none + +Delete all BGP communities + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set community delete +\<text\> + +Delete BGP communities matching the community-list. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set large-community +\<add|replace\> \<GA:LDP1:LDP2\> + +Add or replace BGP large-community attribute in format +`<0-4294967295:0-4294967295:0-4294967295>` + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set large-community none + +Delete all BGP large-communities + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set large-community delete +\<text\> + +Delete BGP communities matching the large-community-list. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set extcommunity bandwidth +\<1-25600[|cumulative|](##SUBST##|cumulative|)num-multipaths\> + +Set extcommunity bandwidth + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set extcommunity bandwidth-non-transitive + +The link bandwidth extended community is encoded as non-transitive + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set extcommunity rt +\<text\> + +Set route target value in format `<0-65535:0-4294967295>` or `<IP:0-65535>`. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set extcommunity soo +\<text\> + +Set site of origin value in format `<0-65535:0-4294967295>` or `<IP:0-65535>`. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set extcommunity none + +Clear all BGP extcommunities. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set distance \<0-255\> + +Locally significant administrative distance. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set ip-next-hop +\<x.x.x.x\> + +Nexthop IP address. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set ip-next-hop +unchanged + +Set the next-hop as unchanged. Pass through the route-map without +changing its value + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set ip-next-hop +peer-address + +Set the BGP nexthop address to the address of the peer. For an incoming +route-map this means the ip address of our peer is used. For an +outgoing route-map this means the ip address of our self is used to +establish the peering with our neighbor. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set ipv6-next-hop +\<global|local\> \<h:h:h:h:h:h:h:h\> + +Nexthop IPv6 address. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set ipv6-next-hop +peer-address + +Set the BGP nexthop address to the address of the peer. For an incoming +route-map this means the ip address of our peer is used. For an +outgoing route-map this means the ip address of our self is used to +establish the peering with our neighbor. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set ipv6-next-hop +prefer-global + +For Incoming and Import Route-maps if we receive a v6 global and v6 LL +address for the route, then prefer to use the global address as the +nexthop. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set local-preference +\<0-4294967295\> + +Set BGP local preference attribute. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set metric +\<+/-metric[|0-4294967295|](##SUBST##|0-4294967295|)rtt[|+rtt|](##SUBST##|+rtt|)-rtt\> + +Set the route metric. When used with BGP, set the BGP attribute MED +to a specific value. Use `+/-` to add or subtract the specified value +to/from the existing/MED. Use `rtt` to set the MED to the round trip +time or `+rtt/-rtt` to add/subtract the round trip time to/from the MED. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set metric-type +\<type-1|type-2\> + +Set OSPF external metric-type. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set origin +\<igp[|egp|](##SUBST##|egp|)incomplete\> + +Set BGP origin code. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set originator-id +\<x.x.x.x\> + +Set BGP originator ID attribute. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set src +\<x.x.x.x|h:h:h:h:h:h:h:h\> + +Set source IP/IPv6 address for route. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set table \<1-200\> + +Set prefixes to table. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set tag \<1-65535\> + +Set tag value for routing protocol. + +</div> + +<div class="cfgcmd"> + +set policy route-map \<text\> rule \<1-65535\> set weight +\<0-4294967295\> + +Set BGP weight attribute + +</div> + +### List of well-known communities + +> - `local-as` - Well-known communities value NO_EXPORT_SUBCONFED 0xFFFFFF03 +> - `no-advertise` - Well-known communities value NO_ADVERTISE 0xFFFFFF02 +> - `no-export` - Well-known communities value NO_EXPORT 0xFFFFFF01 +> - `internet` - Well-known communities value 0 +> - `graceful-shutdown` - Well-known communities value GRACEFUL_SHUTDOWN 0xFFFF0000 +> - `accept-own` - Well-known communities value ACCEPT_OWN 0xFFFF0001 +> - `route-filter-translated-v4` - Well-known communities value ROUTE_FILTER_TRANSLATED_v4 0xFFFF0002 +> - `route-filter-v4` - Well-known communities value ROUTE_FILTER_v4 0xFFFF0003 +> - `route-filter-translated-v6` - Well-known communities value ROUTE_FILTER_TRANSLATED_v6 0xFFFF0004 +> - `route-filter-v6` - Well-known communities value ROUTE_FILTER_v6 0xFFFF0005 +> - `llgr-stale` - Well-known communities value LLGR_STALE 0xFFFF0006 +> - `no-llgr` - Well-known communities value NO_LLGR 0xFFFF0007 +> - `accept-own-nexthop` - Well-known communities value accept-own-nexthop 0xFFFF0008 +> - `blackhole` - Well-known communities value BLACKHOLE 0xFFFF029A +> - `no-peer` - Well-known communities value NOPEER 0xFFFFFF04 diff --git a/docs/configuration/policy/md-route.md b/docs/configuration/policy/md-route.md new file mode 100644 index 00000000..efd0eedf --- /dev/null +++ b/docs/configuration/policy/md-route.md @@ -0,0 +1,647 @@ +# Route and Route6 Policy + +IPv4 route and IPv6 route policies are defined in this section. These route +policies can then be associated to interfaces. + +## Rule-Sets + +A rule-set is a named collection of rules that can be applied to an interface. +Each rule is numbered, has an action to apply if the rule is matched, and the +ability to specify the criteria to match. Data packets go through the rules +from 1 - 999999, at the first match the action of the rule will be executed. + +<div class="cfgcmd"> + +set policy route \<name\> description \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> description \<text\> + +Provide a rule-set description. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> default-log + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> default-log + +Option to log packets hitting default-action. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> description \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> description \<text\> + +Provide a description for each rule. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> log \<enable|disable\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> log \<enable|disable\> + +Option to enable or disable log matching rule. + +</div> + +### Matching criteria + +There are a lot of matching criteria options available, both for +`policy route` and `policy route6`. These options are listed +in this section. + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> connection-mark \<1-2147483647\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> connection-mark \<1-2147483647\> + +Set match criteria based on connection mark. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> source address +\<match_criteria\> + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> destination address +\<match_criteria\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> source address +\<match_criteria\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> destination address +\<match_criteria\> + +Set match criteria based on source or destination ipv4|ipv6 address, where +\<match_criteria\> could be: + +</div> + +For ipv4: +- \<x.x.x.x\>: IP address to match. +- \<x.x.x.x/x\>: Subnet to match. +- \<x.x.x.x\>-\<x.x.x.x\>: IP range to match. +- !\<x.x.x.x\>: Match everything except the specified address. +- !\<x.x.x.x/x\>: Match everything except the specified subnet. +- !\<x.x.x.x\>-\<x.x.x.x\>: Match everything except the specified range. + +And for ipv6: +- \<h:h:h:h:h:h:h:h\>: IPv6 address to match. +- \<h:h:h:h:h:h:h:h/x\>: IPv6 prefix to match. +- \<h:h:h:h:h:h:h:h\>-\<h:h:h:h:h:h:h:h\>: IPv6 range to match. +- !\<h:h:h:h:h:h:h:h\>: Match everything except the specified address. +- !\<h:h:h:h:h:h:h:h/x\>: Match everything except the specified prefix. +- !\<h:h:h:h:h:h:h:h\>-\<h:h:h:h:h:h:h:h\>: Match everything except the + specified range. + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> source group +\<address-group[|domain-group|](##SUBST##|domain-group|)mac-group[|network-group|](##SUBST##|network-group|)port-group\> \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> destination group +\<address-group[|domain-group|](##SUBST##|domain-group|)mac-group[|network-group|](##SUBST##|network-group|)port-group\> \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> source group +\<address-group[|domain-group|](##SUBST##|domain-group|)mac-group[|network-group|](##SUBST##|network-group|)port-group\> \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> destination group +\<address-group[|domain-group|](##SUBST##|domain-group|)mac-group[|network-group|](##SUBST##|network-group|)port-group\> \<text\> + +Set match criteria based on source or destination groups, where \<text\> +would be the group name/identifier. Prepend character '!' for inverted +matching criteria. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> destination port \<match_criteria\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> destination port \<match_criteria\> + +Set match criteria based on destination port, where \<match_criteria\> could +be: + +- \<port name\>: Named port (any name in /etc/services, e.g., http). +- \<1-65535\>: Numbered port. +- \<start\>-\<end\>: Numbered port range (e.g., 1001-1005). + +Multiple destination ports can be specified as a comma-separated list. The +whole list can also be "negated" using '!'. For example: +'!22,telnet,http,123,1001-1005' + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> disable + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> disable + +Option to disable rule. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> dscp \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> dscp \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> dscp-exclude \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> dscp-exclude \<text\> + +Match based on dscp value criteria. Multiple values from 0 to 63 +and ranges are supported. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> fragment +\<match-grag|match-non-frag\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> fragment +\<match-grag|match-non-frag\> + +Set IP fragment match, where: + +- match-frag: Second and further fragments of fragmented packets. +- match-non-frag: Head fragments or unfragmented packets. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> icmp \<code | type\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> icmpv6 \<code | type\> + +Match based on icmp|icmpv6 code and type. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> icmp type-name \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> icmpv6 type-name \<text\> + +Match based on icmp|icmpv6 type-name criteria. Use tab for information +about what type-name criteria are supported. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> ipsec +\<match-ipsec|match-none\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> ipsec +\<match-ipsec|match-none\> + +Set IPSec inbound match criterias, where: + +- match-ipsec: match inbound IPsec packets. +- match-none: match inbound non-IPsec packets. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> limit burst \<0-4294967295\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> limit burst \<0-4294967295\> + +Set maximum number of packets to alow in excess of rate. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> limit rate \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> limit rate \<text\> + +Set maximum average matching rate. Format for rate: integer/time_unit, where +time_unit could be any one of second, minute, hour or day.For example +1/second implies rule to be matched at an average of once per second. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> protocol +\<text | 0-255 | tcp_udp | all \> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> protocol +\<text | 0-255 | tcp_udp | all \> + +Match a protocol criteria. A protocol number or a name which is defined in: +`/etc/protocols`. Special names are `all` for all protocols and +`tcp_udp` for tcp and udp based packets. The `!` negates the selected +protocol. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> packet-length \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> packet-length \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> packet-length-exclude \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> packet-length-exclude \<text\> + +Match based on packet length criteria. Multiple values from 1 to 65535 +and ranges are supported. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> packet-type \[broadcast | host +| multicast | other\] + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> packet-type \[broadcast | host +| multicast | other\] + +Match based on packet type criteria. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> recent count \<1-255\> + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> recent time \<1-4294967295\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> recent time \<1-4294967295\> + +Set parameters for matching recently seen sources. This match could be used +by seeting count (source address seen more than \<1-255\> times) and/or time +(source address seen in the last \<0-4294967295\> seconds). + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> state +\<established | invalid | new | related\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> state +\<established | invalid | new | related\> + +Set match criteria based on session state. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> tcp flags \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> tcp flags \<text\> + +Set match criteria based on tcp flags. Allowed values for TCP flags: SYN ACK +FIN RST URG PSH ALL. When specifying more than one flag, flags should be +comma-separated. For example : value of 'SYN,!ACK,!FIN,!RST' will only match +packets with the SYN flag set, and the ACK, FIN and RST flags unset. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> time monthdays \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> time monthdays \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> time startdate \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> time startdate \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> time starttime \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> time starttime \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> time stopdate \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> time stopdate \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> time stoptime \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> time stoptime \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> time weekdays \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> time weekdays \<text\> + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> time utc + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> time utc + +Time to match the defined rule. + +</div> + +<div class="cfgcmd"> + +set policy route rule \<n\> ttl \<eq | gt | lt\> \<0-255\> + +Match time to live parameter, where 'eq' stands for 'equal'; 'gt' stands for +'greater than', and 'lt' stands for 'less than'. + +</div> + +<div class="cfgcmd"> + +set policy route6 rule \<n\> hop-limit \<eq | gt | lt\> \<0-255\> + +Match hop-limit parameter, where 'eq' stands for 'equal'; 'gt' stands for +'greater than', and 'lt' stands for 'less than'. + +</div> + +### Actions + +When mathcing all patterns defined in a rule, then different actions can +be made. This includes droping the packet, modifying certain data, or +setting a different routing table. + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> action drop + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> action drop + +Set rule action to drop. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> set connection-mark +\<1-2147483647\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> set connection-mark +\<1-2147483647\> + +Set a specific connection mark. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> set dscp \<0-63\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> set dscp \<0-63\> + +Set packet modifications: Packet Differentiated Services Codepoint (DSCP) + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> set mark \<1-2147483647\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> set mark \<1-2147483647\> + +Set a specific packet mark. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> set table \<main | 1-200\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> set table \<main | 1-200\> + +Set the routing table to forward packet with. + +</div> + +<div class="cfgcmd"> + +set policy route \<name\> rule \<n\> set tcp-mss \<500-1460\> + +</div> + +<div class="cfgcmd"> + +set policy route6 \<name\> rule \<n\> set tcp-mss \<500-1460\> + +Set packet modifications: Explicitly set TCP Maximum segment size value. + +</div> diff --git a/docs/configuration/protocols/md-babel.md b/docs/configuration/protocols/md-babel.md new file mode 100644 index 00000000..8bca4a71 --- /dev/null +++ b/docs/configuration/protocols/md-babel.md @@ -0,0 +1,294 @@ +# Babel + +Babel is a modern routing protocol designed to be robust and efficient +both in ordinary wired networks and in wireless mesh networks. +By default, it uses hop-count on wired networks and a variant of ETX +on wireless links, It can be configured to take radio diversity into account +and to automatically compute a link's latency and include it in the metric. +It is defined in `8966`. + +Babel a dual stack protocol. +A single Babel instance is able to perform routing for both IPv4 and IPv6. + +## General Configuration + +VyOS does not have a special command to start the Babel process. +The Babel process starts when the first Babel enabled interface is configured. + +<div class="cfgcmd"> + +set protocols babel interface \<interface\> + +This command specifies a Babel enabled interface by interface name. Both +the sending and receiving of Babel packets will be enabled on the interface +specified in this command. + +</div> + +## Optional Configuration + +<div class="cfgcmd"> + +set protocols babel parameters diversity + +This command enables routing using radio frequency diversity. +This is highly recommended in networks with many wireless nodes. + +> <div class="note"> +> +> <div class="title"> +> +> Note +> +> </div> +> +> If you enable this, you will probably want to +> set diversity-factor and channel below. +> +> </div> + +</div> + +<div class="cfgcmd"> + +set protocols babel parameters diversity-factor \<1-256\> + +This command sets the multiplicative factor used for diversity routing, +in units of 1/256; lower values cause diversity to play a more important role +in route selection. +The default it 256, which means that diversity plays no role in route +selection; you will probably want to set that to 128 or less on nodes +with multiple independent radios. + +</div> + +<div class="cfgcmd"> + +set protocols babel parameters resend-delay \<milliseconds\> + +This command specifies the time in milliseconds after which an 'important' +request or update will be resent. The default is 2000 ms. + +</div> + +<div class="cfgcmd"> + +set protocols babel parameters smoothing-half-life \<seconds\> + +This command specifies the time constant, in seconds, of the smoothing +algorithm used for implementing hysteresis. +Larger values reduce route oscillation at the cost of very slightly increasing +convergence time. The value 0 disables hysteresis, and is suitable for wired +networks. The default is 4 s. + +</div> + +## Interfaces Configuration + +<div class="cfgcmd"> + +set protocols babel interface \<interface\> type \<auto[|wired|](##SUBST##|wired|)wireless\> + +This command sets the interface type: + +**auto** – automatically determines the interface type. +**wired** – enables optimisations for wired interfaces. +**wireless** – disables a number of optimisations that are only correct +on wired interfaces. Specifying wireless is always correct, +but may cause slower convergence and extra routing traffic. + +</div> + +<div class="cfgcmd"> + +set protocols babel interface \<interface\> split-horizon \<default[|disable|](##SUBST##|disable|)enable\> + +This command specifies whether to perform split-horizon on the interface. +Specifying no babel split-horizon is always correct, while babel split-horizon +is an optimisation that should only be used on symmetric +and transitive (wired) networks. + +**default** – enable split-horizon on wired interfaces, and disable +split-horizon on wireless interfaces. +**enable** – enable split-horizon on this interfaces. +**disable** – disable split-horizon on this interfaces. + +</div> + +<div class="cfgcmd"> + +set protocols babel interface \<interface\> hello-interval \<milliseconds\> + +This command specifies the time in milliseconds between two scheduled hellos. +On wired links, Babel notices a link failure within two hello intervals; +on wireless links, the link quality value is reestimated at every hello +interval. +The default is 4000 ms. + +</div> + +<div class="cfgcmd"> + +set protocols babel interface \<interface\> update-interval \<milliseconds\> + +This command specifies the time in milliseconds between two scheduled updates. +Since Babel makes extensive use of triggered updates, +this can be set to fairly high values on links with little packet loss. +The default is 20000 ms. + +</div> + +<div class="cfgcmd"> + +set protocols babel interface \<interface\> rxcost \<1-65534\> + +This command specifies the base receive cost for this interface. +For wireless interfaces, it specifies the multiplier used for computing +the ETX reception cost (default 256); +for wired interfaces, it specifies the cost that will be advertised to +neighbours. + +</div> + +<div class="cfgcmd"> + +set protocols babel interface \<interface\> rtt-decay \<1-256\> + +This command specifies the decay factor for the exponential moving average +of RTT samples, in units of 1/256. +Higher values discard old samples faster. The default is 42. + +</div> + +<div class="cfgcmd"> + +set protocols babel interface \<interface\> rtt-min \<milliseconds\> + +This command specifies the minimum RTT, in milliseconds, +starting from which we increase the cost to a neighbour. +The additional cost is linear in (rtt - rtt-min). The default is 10 ms. + +</div> + +<div class="cfgcmd"> + +set protocols babel interface \<interface\> rtt-max \<milliseconds\> + +This command specifies the maximum RTT, in milliseconds, above which +we don't increase the cost to a neighbour. The default is 120 ms. + +</div> + +<div class="cfgcmd"> + +set protocols babel interface \<interface\> max-rtt-penalty \<milliseconds\> + +This command specifies the maximum cost added to a neighbour because of RTT, +i.e. when the RTT is higher or equal than rtt-max. +The default is 150. +Setting it to 0 effectively disables the use of a RTT-based cost. + +</div> + +<div class="cfgcmd"> + +set protocols babel interface \<interface\> enable-timestamps + +This command enables sending timestamps with each Hello and IHU message +in order to compute RTT values. +It is recommended to enable timestamps on tunnel interfaces. + +</div> + +<div class="cfgcmd"> + +set protocols babel interface \<interface\> channel \<1-254[|interfering|](##SUBST##|interfering|)noninterfering\> + +This command set the channel number that diversity routing uses for this +interface (see diversity option above). + +**1-254** – interfaces with a channel number interfere with +interfering interfaces and interfaces with the same channel number. +**interfering** – interfering interfaces are assumed to interfere with all other channels except +noninterfering channels. +**noninterfering** – noninterfering interfaces are assumed to only interfere +with themselves. + +</div> + +## Redistribution Configuration + +<div class="cfgcmd"> + +set protocols babel redistribute \<ipv4|ipv6\> \<route source\> + +This command redistributes routing information from the given route source +to the Babel process. + +IPv4 route source: bgp, connected, eigrp, isis, kernel, nhrp, ospf, rip, static. + +IPv6 route source: bgp, connected, eigrp, isis, kernel, nhrp, ospfv3, ripng, static. + +</div> + +<div class="cfgcmd"> + +set protocols babel distribute-list \<ipv4[|ipv6\> access-list \<in|](##SUBST##|ipv6> access-list <in|)out\> \<number\> + +This command can be used to filter the Babel routes using access lists. +`in` and `out` this is the direction in which the access +lists are applied. + +</div> + +<div class="cfgcmd"> + +set protocols babel distribute-list \<ipv4[|ipv6\> interface \<interface\> access-list \<in|](##SUBST##|ipv6> interface <interface> access-list <in|)out\> \<number\> + +This command allows you apply access lists to a chosen interface to +filter the Babel routes. + +</div> + +<div class="cfgcmd"> + +set protocols babel distribute-list \<ipv4[|ipv6\> prefix-list \<in|](##SUBST##|ipv6> prefix-list <in|)out\> \<name\> + +This command can be used to filter the Babel routes using prefix lists. +`in` and `out` this is the direction in which the prefix +lists are applied. + +</div> + +<div class="cfgcmd"> + +set protocols babel distribute-list \<ipv4[|ipv6\> interface \<interface\> prefix-list \<in|](##SUBST##|ipv6> interface <interface> prefix-list <in|)out\> \<name\> + +This command allows you apply prefix lists to a chosen interface to +filter the Babel routes. + +</div> + +## Configuration Example + +Simple Babel configuration using 2 nodes and redistributing connected interfaces. + +**Node 1:** + +``` none +set interfaces loopback lo address 10.1.1.1/32 +set interfaces loopback lo address fd12:3456:dead:beef::1/128 +set protocols babel interface eth0 type wired +set protocols babel redistribute ipv4 connected +set protocols babel redistribute ipv6 connected +``` + +**Node 2:** + +``` none +set interfaces loopback lo address 10.2.2.2/32 +set interfaces loopback lo address fd12:3456:beef:dead::2/128 +set protocols babel interface eth0 type wired +set protocols babel redistribute ipv4 connected +set protocols babel redistribute ipv6 connected +``` diff --git a/docs/configuration/protocols/md-bfd.md b/docs/configuration/protocols/md-bfd.md new file mode 100644 index 00000000..58582008 --- /dev/null +++ b/docs/configuration/protocols/md-bfd.md @@ -0,0 +1,259 @@ +lastproofread +2023-01-27 + +# BFD + +`BFD (Bidirectional Forwarding Detection)` is described and extended by +the following RFCs: `5880`, `5881` and `5883`. + +In the age of very fast networks, a second of unreachability may equal millions of lost packets. +The idea behind BFD is to detect very quickly when a peer is down and take action extremely fast. + +BFD sends lots of small UDP packets very quickly to ensures that the peer is still alive. + +This allows avoiding the timers defined in BGP and OSPF protocol to expires. + +## Configure BFD + +<div class="cfgcmd"> + +set protocols bfd peer \<address\> + +Set BFD peer IPv4 address or IPv6 address + +</div> + +<div class="cfgcmd"> + +set protocols bfd peer \<address\> echo-mode + +Enables the echo transmission mode + +</div> + +<div class="cfgcmd"> + +set protocols bfd peer \<address\> multihop + +Allow this BFD peer to not be directly connected + +</div> + +<div class="cfgcmd"> + +set protocols bfd peer \<address\> source +\[address \<address\> | interface \<interface\>\] + +Bind listener to specific interface/address, mandatory for IPv6 + +</div> + +<div class="cfgcmd"> + +set protocols bfd peer \<address\> interval echo-interval \<10-60000\> + +The minimal echo receive transmission interval that this system is +capable of handling + +</div> + +<div class="cfgcmd"> + +set protocols bfd peer \<address\> interval multiplier \<2-255\> + +Remote transmission interval will be multiplied by this value + +</div> + +<div class="cfgcmd"> + +set protocols bfd peer \<address\> interval +\[receive | transmit\] \<10-60000\> + +Interval in milliseconds + +</div> + +<div class="cfgcmd"> + +set protocols bfd peer \<address\> shutdown + +Disable a BFD peer + +</div> + +<div class="cfgcmd"> + +set protocols bfd peer \<address\> minimum-ttl \<1-254\> + +For multi hop sessions only. Configure the minimum expected TTL for an +incoming BFD control packet. + +This feature serves the purpose of thightening the packet validation +requirements to avoid receiving BFD control packets from other sessions. + +</div> + +### Enable BFD in BGP + +<div class="cfgcmd"> + +set protocols bgp neighbor \<neighbor\> bfd + +Enable BFD on a single BGP neighbor + +</div> + +<div class="cfgcmd"> + +set protocols bgp peer-group \<neighbor\> bfd + +Enable BFD on a BGP peer group + +</div> + +### Enable BFD in OSPF + +<div class="cfgcmd"> + +set protocols ospf interface \<interface\> bfd + +Enable BFD for OSPF on an interface + +</div> + +<div class="cfgcmd"> + +set protocols ospfv3 interface \<interface\> bfd + +Enable BFD for OSPFv3 on an interface + +</div> + +### Enable BFD in ISIS + +<div class="cfgcmd"> + +set protocols isis \<name\> interface \<interface\> bfd + +Enable BFD for ISIS on an interface + +</div> + +## Operational Commands + +<div class="opcmd"> + +show bfd peers + +Show all BFD peers + +``` none +BFD Peers: + peer 198.51.100.33 vrf default interface eth4.100 + ID: 4182341893 + Remote ID: 12678929647 + Status: up + Uptime: 1 month(s), 16 hour(s), 29 minute(s), 38 second(s) + Diagnostics: ok + Remote diagnostics: ok + Local timers: + Receive interval: 300ms + Transmission interval: 300ms + Echo transmission interval: 50ms + Remote timers: + Receive interval: 300ms + Transmission interval: 300ms + Echo transmission interval: 0ms + + peer 198.51.100.55 vrf default interface eth4.101 + ID: 4618932327 + Remote ID: 3312345688 + Status: up + Uptime: 20 hour(s), 16 minute(s), 19 second(s) + Diagnostics: ok + Remote diagnostics: ok + Local timers: + Receive interval: 300ms + Transmission interval: 300ms + Echo transmission interval: 50ms + Remote timers: + Receive interval: 300ms + Transmission interval: 300ms + Echo transmission interval: 0ms +``` + +</div> + +## BFD Static Route Monitoring + +A monitored static route conditions the installation to the RIB on the BFD +session running state: when BFD session is up the route is installed to RIB, +but when the BFD session is down it is removed from the RIB. + +### Configuration + +<div class="cfgcmd"> + +set protocols static route \<subnet\> next-hop \<address\> +bfd profile \<profile\> + +Configure a static route for \<subnet\> using gateway \<address\> +and use the gateway address as BFD peer destination address. + +</div> + +<div class="cfgcmd"> + +set protocols static route \<subnet\> next-hop \<address\> +bfd multi-hop source \<address\> profile \<profile\> + +Configure a static route for \<subnet\> using gateway \<address\> +, use source address to indentify the peer when is multi-hop session +and the gateway address as BFD peer destination address. + +</div> + +<div class="cfgcmd"> + +set protocols static route6 \<subnet\> next-hop \<address\> +bfd profile \<profile\> + +Configure a static route for \<subnet\> using gateway \<address\> +and use the gateway address as BFD peer destination address. + +</div> + +<div class="cfgcmd"> + +set protocols static route6 \<subnet\> next-hop \<address\> +bfd multi-hop source \<address\> profile \<profile\> + +Configure a static route for \<subnet\> using gateway \<address\> +, use source address to indentify the peer when is multi-hop session +and the gateway address as BFD peer destination address. + +</div> + +## Operational Commands + +<div class="opcmd"> + +show bfd static routes + +Showing BFD monitored static routes + +``` none +Showing BFD monitored static routes: + + Next hops: + VRF default IPv4 Unicast: + 10.10.13.3/32 peer 192.168.2.3 (status: installed) + 172.16.10.3/32 peer 192.168.10.1 (status: uninstalled) + + VRF default IPv4 Multicast: + + VRF default IPv6 Unicast: +``` + +</div> diff --git a/docs/configuration/protocols/md-bgp.md b/docs/configuration/protocols/md-bgp.md new file mode 100644 index 00000000..b5a91b3f --- /dev/null +++ b/docs/configuration/protocols/md-bgp.md @@ -0,0 +1,1683 @@ +# BGP + +`BGP (Border Gateway Protocol)` is one of the Exterior Gateway Protocols +and the de facto standard interdomain routing protocol. The latest BGP version +is 4. BGP-4 is described in `1771` and updated by `4271`. `2858` +adds multiprotocol support to BGP. + +VyOS makes use of `FRR (Free Range Routing)` and we would like to thank +them for their effort! + +## Basic Concepts + +### Autonomous Systems + +From `1930`: + +> An AS is a connected group of one or more IP prefixes run by one or more +> network operators which has a SINGLE and CLEARLY DEFINED routing policy. + +Each `AS (Autonomous System)` has an identifying number associated with it +called an `ASN (Autonomous System Number)`. This is a two octet value +ranging in value from 1 to 65535. The AS numbers 64512 through 65535 are defined +as private AS numbers. Private AS numbers must not be advertised on the global +Internet. The 2-byte AS number range has been exhausted. 4-byte AS numbers are +specified in `6793`, and provide a pool of 4294967296 AS numbers. + +The `ASN (Autonomous System Number)` is one of the essential elements of +BGP. BGP is a distance vector routing protocol, and the AS-Path framework +provides distance vector metric and loop detection to BGP. + +<div class="cfgcmd"> + +set protocols bgp system-as \<asn\> + +Set local `ASN (Autonomous System Number)` that this router represents. +This is a a mandatory option! + +</div> + +### Address Families + +Multiprotocol extensions enable BGP to carry routing information for multiple +network layer protocols. BGP supports an Address Family Identifier (AFI) for +IPv4 and IPv6. + +### Route Selection + +The route selection process used by FRR's BGP implementation uses the following +decision criterion, starting at the top of the list and going towards the +bottom until one of the factors can be used. + +1. **Weight check** + + Prefer higher local weight routes to lower routes. + +2. **Local preference check** + + Prefer higher local preference routes to lower. + +3. **Local route check** + + Prefer local routes (statics, aggregates, redistributed) to received routes. + +4. **AS path length check** + + Prefer shortest hop-count AS_PATHs. + +5. **Origin check** + + Prefer the lowest origin type route. That is, prefer IGP origin routes to + EGP, to Incomplete routes. + +6. **MED check** + + Where routes with a MED were received from the same AS, prefer the route + with the lowest MED. + +7. **External check** + + Prefer the route received from an external, eBGP peer over routes received + from other types of peers. + +8. **IGP cost check** + + Prefer the route with the lower IGP cost. + +9. **Multi-path check** + + If multi-pathing is enabled, then check whether the routes not yet + distinguished in preference may be considered equal. If + `bgp bestpath as-path multipath-relax` is set, all such routes are + considered equal, otherwise routes received via iBGP with identical AS_PATHs + or routes received from eBGP neighbours in the same AS are considered equal. + +10. **Already-selected external check** + + Where both routes were received from eBGP peers, then prefer the route + which is already selected. Note that this check is not applied if + `bgp bestpath compare-routerid` is configured. This check can + prevent some cases of oscillation. + +11. **Router-ID check** + + Prefer the route with the lowest <span class="title-ref">router-ID</span>. If the route has an + <span class="title-ref">ORIGINATOR_ID</span> attribute, through iBGP reflection, then that router ID is + used, otherwise the <span class="title-ref">router-ID</span> of the peer the route was received from is + used. + +12. **Cluster-List length check** + + The route with the shortest cluster-list length is used. The cluster-list + reflects the iBGP reflection path the route has taken. + +13. **Peer address** + + Prefer the route received from the peer with the higher transport layer + address, as a last-resort tie-breaker. + +### Capability Negotiation + +When adding IPv6 routing information exchange feature to BGP. There were some +proposals. `IETF (Internet Engineering Task Force)` +`IDR (Inter Domain Routing)` adopted a proposal called Multiprotocol +Extension for BGP. The specification is described in `2283`. The protocol +does not define new protocols. It defines new attributes to existing BGP. When +it is used exchanging IPv6 routing information it is called BGP-4+. When it is +used for exchanging multicast routing information it is called MBGP. + +*bgpd* supports Multiprotocol Extension for BGP. So if a remote peer supports +the protocol, *bgpd* can exchange IPv6 and/or multicast routing information. + +Traditional BGP did not have the feature to detect a remote peer's +capabilities, e.g. whether it can handle prefix types other than IPv4 unicast +routes. This was a big problem using Multiprotocol Extension for BGP in an +operational network. `2842` adopted a feature called Capability +Negotiation. *bgpd* use this Capability Negotiation to detect the remote peer's +capabilities. If a peer is only configured as an IPv4 unicast neighbor, *bgpd* +does not send these Capability Negotiation packets (at least not unless other +optional BGP features require capability negotiation). + +By default, FRR will bring up peering with minimal common capability for the +both sides. For example, if the local router has unicast and multicast +capabilities and the remote router only has unicast capability the local router +will establish the connection with unicast only capability. When there are no +common capabilities, FRR sends Unsupported Capability error and then resets the +connection. + +## Configuration + +### BGP Router Configuration + +First of all you must configure BGP router with the `ASN (Autonomous +System Number)`. The AS number is an identifier for the autonomous system. +The BGP protocol uses the AS number for detecting whether the BGP connection +is internal or external. VyOS does not have a special command to start the BGP +process. The BGP process starts when the first neighbor is configured. + +<div class="cfgcmd"> + +set protocols bgp system-as \<asn\> + +Set local autonomous system number that this router represents. This is a +mandatory option! + +</div> + +#### Peers Configuration + +##### Defining Peers + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address|interface\> remote-as +\<nasn\> + +This command creates a new neighbor whose remote-as is \<nasn\>. The neighbor +address can be an IPv4 address or an IPv6 address or an interface to use +for the connection. The command is applicable for peer and peer group. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address|interface\> remote-as +internal + +Create a peer as you would when you specify an ASN, except that if the +peers ASN is different than mine as specified under the `protocols +bgp <asn>` command the connection will be denied. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address|interface\> remote-as +external + +Create a peer as you would when you specify an ASN, except that if the +peers ASN is the same as mine as specified under the `protocols +bgp <asn>` command the connection will be denied. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address|interface\> local-role +\<role\> \[strict\] + +BGP roles are defined in RFC `9234` and provide an easy way to +add route leak prevention, detection and mitigation. The local Role +value is negotiated with the new BGP Role capability which has a +built-in check of the corresponding value. In case of a mismatch the +new OPEN Roles Mismatch Notification \<2, 11\> would be sent. +The correct Role pairs are: + +Provider - Customer + +Peer - Peer + +RS-Server - RS-Client + +If `strict` is set the BGP session won’t become established +until the BGP neighbor sets local Role on its side. This +configuration parameter is defined in RFC `9234` and is used to +enforce the corresponding configuration at your counter-parts side. + +Routes that are sent from provider, rs-server, or the peer local-role +(or if received by customer, rs-client, or the peer local-role) will +be marked with a new Only to Customer (OTC) attribute. + +Routes with this attribute can only be sent to your neighbor if your +local-role is provider or rs-server. Routes with this attribute can +be received only if your local-role is customer or rs-client. + +In case of peer-peer relationship routes can be received only if OTC +value is equal to your neighbor AS number. + +All these rules with OTC will help to detect and mitigate route leaks +and happen automatically if local-role is set. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address|interface\> shutdown + +This command disable the peer or peer group. To reenable the peer use +the delete form of this command. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address|interface\> description +\<text\> + +Set description of the peer or peer group. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> update-source +\<address|](##SUBST##|interface> update-source +<address|)interface\> + +Specify the IPv4 source address to use for the BGP session to this neighbor, +may be specified as either an IPv4 address directly or as an interface name. + +</div> + +##### Capability Negotiation + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address|interface\> capability +dynamic + +This command would allow the dynamic update of capabilities over an +established BGP session. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address|interface\> capability +extended-nexthop + +Allow bgp to negotiate the extended-nexthop capability with it’s peer. +If you are peering over a IPv6 Link-Local address then this capability +is turned on automatically. If you are peering over a IPv6 Global Address +then turning on this command will allow BGP to install IPv4 routes with +IPv6 nexthops if you do not have IPv4 configured on interfaces. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address|interface\> +disable-capability-negotiation + +Suppress sending Capability Negotiation as OPEN message optional +parameter to the peer. This command only affects the peer is +configured other than IPv4 unicast configuration. + +When remote peer does not have capability negotiation feature, +remote peer will not send any capabilities at all. In that case, +bgp configures the peer with configured capabilities. + +You may prefer locally configured capabilities more than the negotiated +capabilities even though remote peer sends capabilities. If the peer is +configured by `override-capability`, VyOS ignores received +capabilities then override negotiated capabilities with configured values. + +Additionally you should keep in mind that this feature fundamentally +disables the ability to use widely deployed BGP features. BGP unnumbered, +hostname support, AS4, Addpath, Route Refresh, ORF, Dynamic Capabilities, +and graceful restart. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address|interface\> +override-capability + +This command allow override the result of Capability Negotiation with +local configuration. Ignore remote peer’s capability value. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address|interface\> +strict-capability-match + +This command forces strictly compare remote capabilities and local +capabilities. If capabilities are different, send Unsupported Capability +error then reset connection. + +You may want to disable sending Capability Negotiation OPEN message +optional parameter to the peer when remote peer does not implement +Capability Negotiation. Please use `disable-capability-negotiation` +command to disable the feature. + +</div> + +##### Peer Parameters + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|interface> address-family +<ipv4-unicast|)ipv6-unicast\> allowas-in number \<number\> + +This command accept incoming routes with AS path containing AS +number with the same value as the current system AS. This is +used when you want to use the same AS number in your sites, +but you can’t connect them directly. + +The number parameter (1-10) configures the amount of accepted +occurences of the system AS number in AS path. + +This command is only allowed for eBGP peers. It is not applicable +for peer groups. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|interface> address-family +<ipv4-unicast|)ipv6-unicast\> as-override + +This command override AS number of the originating router with +the local AS number. + +Usually this configuration is used in PEs (Provider Edge) to +replace the incoming customer AS number so the connected CE ( +Customer Edge) can use the same AS number as the other customer +sites. This allows customers of the provider network to use the +same AS number across their sites. + +This command is only allowed for eBGP peers. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|interface> address-family +<ipv4-unicast|)ipv6-unicast\> attribute-unchanged \<as-path[|med|](##SUBST##|med|)next-hop\> + +This command specifies attributes to be left unchanged for +advertisements sent to a peer or peer group. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|interface> address-family +<ipv4-unicast|)ipv6-unicast\> maximum-prefix \<number\> + +This command specifies a maximum number of prefixes we can receive +from a given peer. If this number is exceeded, the BGP session +will be destroyed. The number range is 1 to 4294967295. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|interface> address-family +<ipv4-unicast|)ipv6-unicast\> nexthop-self + +This command forces the BGP speaker to report itself as the +next hop for an advertised route it advertised to a neighbor. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|interface> address-family +<ipv4-unicast|)ipv6-unicast\> remove-private-as + +This command removes the private ASN of routes that are advertised +to the configured peer. It removes only private ASNs on routes +advertised to EBGP peers. + +If the AS-Path for the route has only private ASNs, the private +ASNs are removed. + +If the AS-Path for the route has a private ASN between public +ASNs, it is assumed that this is a design choice, and the +private ASN is not removed. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|interface> address-family +<ipv4-unicast|)ipv6-unicast\> soft-reconfiguration inbound + +Changes in BGP policies require the BGP session to be cleared. Clearing has a +large negative impact on network operations. Soft reconfiguration enables you +to generate inbound updates from a neighbor, change and activate BGP policies +without clearing the BGP session. + +This command specifies that route updates received from this neighbor will be +stored unmodified, regardless of the inbound policy. When inbound soft +reconfiguration is enabled, the stored updates are processed by the new +policy configuration to create new inbound updates. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Storage of route updates uses memory. If you enable soft +reconfiguration inbound for multiple neighbors, the amount of memory used +can become significant. + +</div> + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|interface> address-family +<ipv4-unicast|)ipv6-unicast\> weight \<number\> + +This command specifies a default weight value for the neighbor’s +routes. The number range is 1 to 65535. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address|interface\> +advertisement-interval \<seconds\> + +This command specifies the minimum route advertisement interval for +the peer. The interval value is 0 to 600 seconds, with the default +advertisement interval being 0. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address|interface\> +disable-connected-check + +This command allows peerings between directly connected eBGP peers +using loopback addresses without adjusting the default TTL of 1. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> +disable-send-community \<extended|](##SUBST##|interface> +disable-send-community <extended|)standard\> + +This command specifies that the community attribute should not be sent +in route updates to a peer. By default community attribute is sent. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address|interface\> ebgp-multihop +\<number\> + +This command allows sessions to be established with eBGP neighbors +when they are multiple hops away. When the neighbor is not directly +connected and this knob is not enabled, the session will not establish. +The number of hops range is 1 to 255. This command is mutually +exclusive with `ttl-security hops`. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address|interface\> local-as \<asn\> +\[no-prepend\] \[replace-as\] + +Specify an alternate AS for this BGP process when interacting with +the specified peer or peer group. With no modifiers, the specified +local-as is prepended to the received AS_PATH when receiving routing +updates from the peer, and prepended to the outgoing AS_PATH (after +the process local AS) when transmitting local routes to the peer. + +If the `no-prepend` attribute is specified, then the supplied +local-as is not prepended to the received AS_PATH. + +If the `replace-as` attribute is specified, then only the supplied +local-as is prepended to the AS_PATH when transmitting local-route +updates to this peer. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +This command is only allowed for eBGP peers. + +</div> + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address|interface\> passive + +Configures the BGP speaker so that it only accepts inbound connections +from, but does not initiate outbound connections to the peer or peer group. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address|interface\> password +\<text\> + +This command specifies a MD5 password to be used with the tcp socket that +is being used to connect to the remote peer. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address|interface\> ttl-security +hops \<number\> + +This command enforces Generalized TTL Security Mechanism (GTSM), +as specified in `5082`. With this command, only neighbors +that are specified number of hops away will be allowed to +become neighbors. The number of hops range is 1 to 254. This +command is mutually exclusive with `ebgp-multihop`. + +</div> + +##### Peer Groups + +Peer groups are used to help improve scaling by generating the same update +information to all members of a peer group. Note that this means that the +routes generated by a member of a peer group will be sent back to that +originating peer with the originator identifier attribute set to indicated +the originating peer. All peers not associated with a specific peer group +are treated as belonging to a default peer group, and will share updates. + +<div class="cfgcmd"> + +set protocols bgp peer-group \<name\> + +This command defines a new peer group. You can specify to the group the same +parameters that you can specify for specific neighbors. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you apply a parameter to an individual neighbor IP address, you +override the action defined for a peer group that includes that IP +address. + +</div> + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address|interface\> peer-group +\<name\> + +This command bind specific peer to peer group with a given name. + +</div> + +#### Network Advertisement Configuration + +<div class="cfgcmd"> + +set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> +network \<prefix\> + +This command is used for advertising IPv4 or IPv6 networks. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +By default, the BGP prefix is advertised even if it's not present +in the routing table. This behaviour differs from the implementation of +some vendors. + +</div> + +</div> + +<div class="cfgcmd"> + +set protocols bgp parameters network-import-check + +This configuration modifies the behavior of the network statement. If you +have this configured the underlying network must exist in the routing table. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|interface> address-family +<ipv4-unicast|)ipv6-unicast\> default-originate \[route-map \<name\>\] + +By default, VyOS does not advertise a default route (0.0.0.0/0) even if it is +in routing table. When you want to announce default routes to the peer, use +this command. Using optional argument `route-map` you can inject the +default route to given neighbor only if the conditions in the route map are +met. + +</div> + +#### Route Aggregation Configuration + +<div class="cfgcmd"> + +set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> +aggregate-address \<prefix\> + +This command specifies an aggregate address. The router will also +announce longer-prefixes inside of the aggregate address. + +</div> + +<div class="cfgcmd"> + +set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> +aggregate-address \<prefix\> as-set + +This command specifies an aggregate address with a mathematical set of +autonomous systems. This command summarizes the AS_PATH attributes of +all the individual routes. + +</div> + +<div class="cfgcmd"> + +set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> +aggregate-address \<prefix\> summary-only + +This command specifies an aggregate address and provides that +longer-prefixes inside of the aggregate address are suppressed +before sending BGP updates out to peers. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|interface> address-family +<ipv4-unicast|)ipv6-unicast\> unsuppress-map \<name\> + +This command applies route-map to selectively unsuppress prefixes +suppressed by summarisation. + +</div> + +#### Redistribution Configuration + +<div class="cfgcmd"> + +set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> +redistribute \<route source\> + +This command redistributes routing information from the given route source +to the BGP process. There are six modes available for route source: +connected, kernel, ospf, rip, static, table. + +</div> + +<div class="cfgcmd"> + +set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> +redistribute \<route source\> metric \<number\> + +This command specifies metric (MED) for redistributed routes. The +metric range is 0 to 4294967295. There are six modes available for +route source: connected, kernel, ospf, rip, static, table. + +</div> + +<div class="cfgcmd"> + +set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> +redistribute \<route source\> route-map \<name\> + +This command allows to use route map to filter redistributed routes. +There are six modes available for route source: connected, kernel, +ospf, rip, static, table. + +</div> + +#### General Configuration + +##### Common parameters + +<div class="cfgcmd"> + +set protocols bgp parameters allow-martian-nexthop + +When a peer receives a martian nexthop as part of the NLRI for a route +permit the nexthop to be used as such, instead of rejecting and resetting +the connection. + +</div> + +<div class="cfgcmd"> + +set protocols bgp parameters router-id \<id\> + +This command specifies the router-ID. If router ID is not specified it will +use the highest interface IP address. + +</div> + +<div class="cfgcmd"> + +set protocols bgp address-family \<ipv4-unicast[|ipv6-unicast\> +maximum-paths \<ebgp|](##SUBST##|ipv6-unicast> +maximum-paths <ebgp|)ibgp\> \<number\> + +This command defines the maximum number of parallel routes that +the BGP can support. In order for BGP to use the second path, the +following attributes have to match: Weight, Local Preference, AS +Path (both AS number and AS path length), Origin code, MED, IGP +metric. Also, the next hop address for each path must be different. + +</div> + +<div class="cfgcmd"> + +set protocols bgp parameters no-hard-administrative-reset + +Do not send Hard Reset CEASE Notification for "Administrative Reset" +events. When set and Graceful Restart Notification capability is exchanged +between the peers, Graceful Restart procedures apply, and routes will be retained. + +</div> + +<div class="cfgcmd"> + +set protocols bgp parameters log-neighbor-changes + +This command enable logging neighbor up/down changes and reset reason. + +</div> + +<div class="cfgcmd"> + +set protocols bgp parameters no-client-to-client-reflection + +This command disables route reflection between route reflector clients. +By default, the clients of a route reflector are not required to be +fully meshed and the routes from a client are reflected to other clients. +However, if the clients are fully meshed, route reflection is not required. +In this case, use the `no-client-to-client-reflection` command +to disable client-to-client reflection. + +</div> + +<div class="cfgcmd"> + +set protocols bgp parameters no-fast-external-failover + +Disable immediate session reset if peer's connected link goes down. + +</div> + +<div class="cfgcmd"> + +set protocols bgp parameters no-ipv6-auto-ra + +By default, FRR sends router advertisement packets when Extended Next Hop is +on or when a connection is established directly using the device name (Unnumbered BGP). +Setting this option prevents FRR from sending router advertisement packets, but could break Unnumbered BGP. + +</div> + +<div class="cfgcmd"> + +set protocols bgp listen range \<prefix\> peer-group \<name\> + +This command is useful if one desires to loosen the requirement for BGP +to have strictly defined neighbors. Specifically what is allowed is for +the local router to listen to a range of IPv4 or IPv6 addresses defined +by a prefix and to accept BGP open messages. When a TCP connection +(and subsequently a BGP open message) from within this range tries to +connect the local router then the local router will respond and connect +with the parameters that are defined within the peer group. One must define +a peer-group for each range that is listed. If no peer-group is defined +then an error will keep you from committing the configuration. + +</div> + +<div class="cfgcmd"> + +set protocols bgp listen limit \<number\> + +This command goes hand in hand with the listen range command to limit the +amount of BGP neighbors that are allowed to connect to the local router. +The limit range is 1 to 5000. + +</div> + +<div class="cfgcmd"> + +set protocols bgp parameters ebgp-requires-policy + +This command changes the eBGP behavior of FRR. By default FRR enables +`8212` functionality which affects how eBGP routes are advertised, +namely no routes are advertised across eBGP sessions without some +sort of egress route-map/policy in place. In VyOS however we have this +RFC functionality disabled by default so that we can preserve backwards +compatibility with older versions of VyOS. With this option one can +enable `8212` functionality to operate. + +</div> + +<div class="cfgcmd"> + +set protocols bgp parameters labeled-unicast \<explicit-null | +ipv4-explicit-null | ipv6-explicit-null\> + +By default, locally advertised prefixes use the implicit-null label to +encode in the outgoing NLRI. + +The following command uses the explicit-null label value for all the +BGP instances. + +</div> + +##### Administrative Distance + +<div class="cfgcmd"> + +set protocols bgp parameters distance global +\<external[|internal|](##SUBST##|internal|)local\> \<distance\> + +This command change distance value of BGP. The arguments are the distance +values for external routes, internal routes and local routes respectively. +The distance range is 1 to 255. + +</div> + +<div class="cfgcmd"> + +set protocols bgp parameters distance prefix \<subnet\> +distance \<distance\> + +This command sets the administrative distance for a particular route. The +distance range is 1 to 255. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Routes with a distance of 255 are effectively disabled and not +installed into the kernel. + +</div> + +</div> + +##### Timers + +<div class="cfgcmd"> + +set protocols bgp timers holdtime \<seconds\> + +This command specifies hold-time in seconds. The timer range is +4 to 65535. The default value is 180 second. If you set value to 0 +VyOS will not hold routes. + +</div> + +<div class="cfgcmd"> + +set protocols bgp timers keepalive \<seconds\> + +This command specifies keep-alive time in seconds. The timer +can range from 4 to 65535. The default value is 60 second. + +</div> + +##### Route Dampening + +When a route fails, a routing update is sent to withdraw the route from the +network's routing tables. When the route is re-enabled, the change in +availability is also advertised. A route that continually fails and returns +requires a great deal of network traffic to update the network about the +route's status. + +Route dampening wich described in `2439` enables you to identify routes +that repeatedly fail and return. If route dampening is enabled, an unstable +route accumulates penalties each time the route fails and returns. If the +accumulated penalties exceed a threshold, the route is no longer advertised. +This is route suppression. Routes that have been suppressed are re-entered +into the routing table only when the amount of their penalty falls below a +threshold. + +A penalty of 1000 is assessed each time the route fails. When the penalties +reach a predefined threshold (suppress-value), the router stops advertising +the route. + +Once a route is assessed a penalty, the penalty is decreased by half each time +a predefined amount of time elapses (half-life-time). When the accumulated +penalties fall below a predefined threshold (reuse-value), the route is +unsuppressed and added back into the BGP routing table. + +No route is suppressed indefinitely. Maximum-suppress-time defines the maximum +time a route can be suppressed before it is re-advertised. + +<div class="cfgcmd"> + +set protocols bgp parameters dampening +half-life \<minutes\> + +This command defines the amount of time in minutes after +which a penalty is reduced by half. The timer range is +10 to 45 minutes. + +</div> + +<div class="cfgcmd"> + +set protocols bgp parameters dampening +re-use \<seconds\> + +This command defines the accumulated penalty amount at which the +route is re-advertised. The penalty range is 1 to 20000. + +</div> + +<div class="cfgcmd"> + +set protocols bgp parameters dampening +start-suppress-time \<seconds\> + +This command defines the accumulated penalty amount at which the +route is suppressed. The penalty range is 1 to 20000. + +</div> + +<div class="cfgcmd"> + +set protocols bgp parameters dampening +max-suppress-time \<seconds\> + +This command defines the maximum time in minutes that a route is +suppressed. The timer range is 1 to 255 minutes. + +</div> + +#### Route Selection Configuration + +<div class="cfgcmd"> + +set protocols bgp parameters always-compare-med + +This command provides to compare the MED on routes, even when they were +received from different neighbouring ASes. Setting this option makes the +order of preference of routes more defined, and should eliminate MED +induced oscillations. + +</div> + +<div class="cfgcmd"> + +set protocols bgp parameters bestpath as-path confed + +This command specifies that the length of confederation path sets and +sequences should be taken into account during the BGP best path +decision process. + +</div> + +<div class="cfgcmd"> + +set protocols bgp parameters bestpath as-path multipath-relax + +This command specifies that BGP decision process should consider paths +of equal AS_PATH length candidates for multipath computation. Without +the knob, the entire AS_PATH must match for multipath computation. + +</div> + +<div class="cfgcmd"> + +set protocols bgp parameters bestpath as-path ignore + +Ignore AS_PATH length when selecting a route + +</div> + +<div class="cfgcmd"> + +set protocols bgp parameters bestpath compare-routerid + +Ensure that when comparing routes where both are equal on most metrics, +including local-pref, AS_PATH length, IGP cost, MED, that the tie is +broken based on router-ID. + +If this option is enabled, then the already-selected check, where +already selected eBGP routes are preferred, is skipped. + +If a route has an ORIGINATOR_ID attribute because it has been reflected, +that ORIGINATOR_ID will be used. Otherwise, the router-ID of the peer +the route was received from will be used. + +The advantage of this is that the route-selection (at this point) will +be more deterministic. The disadvantage is that a few or even one lowest-ID +router may attract all traffic to otherwise-equal paths because of this +check. It may increase the possibility of MED or IGP oscillation, unless +other measures were taken to avoid these. The exact behaviour will be +sensitive to the iBGP and reflection topology. + +</div> + +<div class="cfgcmd"> + +set protocols bgp parameters bestpath med confed + +This command specifies that BGP considers the MED when comparing routes +originated from different sub-ASs within the confederation to which this +BGP speaker belongs. The default state, where the MED attribute is not +considered. + +</div> + +<div class="cfgcmd"> + +set protocols bgp parameters bestpath med missing-as-worst + +This command specifies that a route with a MED is always considered to be +better than a route without a MED by causing the missing MED attribute to +have a value of infinity. The default state, where the missing MED +attribute is considered to have a value of zero. + +</div> + +<div class="cfgcmd"> + +set protocols bgp parameters default local-pref +\<local-pref value\> + +This command specifies the default local preference value. The local +preference range is 0 to 4294967295. + +</div> + +<div class="cfgcmd"> + +set protocols bgp parameters deterministic-med + +This command provides to compare different MED values that advertised by +neighbours in the same AS for routes selection. When this command is +enabled, routes from the same autonomous system are grouped together, and +the best entries of each group are compared. + +</div> + +<div class="cfgcmd"> + +set protocols bgp address-family ipv4-unicast network +\<prefix\> backdoor + +This command allows the router to prefer route to specified prefix learned +via IGP through backdoor link instead of a route to the same prefix learned +via EBGP. + +</div> + +#### Route Filtering Configuration + +In order to control and modify routing information that is exchanged between +peers you can use route-map, filter-list, prefix-list, distribute-list. + +For inbound updates the order of preference is: + +> - route-map +> - filter-list +> - prefix-list, distribute-list + +For outbound updates the order of preference is: + +> - prefix-list, distribute-list +> - filter-list +> - route-map +> +> <div class="note"> +> +> <div class="title"> +> +> Note +> +> </div> +> +> The attributes `prefix-list` and `distribute-list` +> are mutually exclusive, and only one command (distribute-list or +> prefix-list) can be applied to each inbound or outbound direction for a +> particular neighbor. +> +> </div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|interface> address-family +<ipv4-unicast|)ipv6-unicast\> distribute-list \<export|import\> \<number\> + +This command applies the access list filters named in \<number\> to the +specified BGP neighbor to restrict the routing information that BGP learns +and/or advertises. The arguments `export` and `import` +specify the direction in which the access list are applied. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|interface> address-family +<ipv4-unicast|)ipv6-unicast\> prefix-list \<export|import\> \<name\> + +This command applies the prfefix list filters named in \<name\> to the +specified BGP neighbor to restrict the routing information that BGP learns +and/or advertises. The arguments `export` and `import` +specify the direction in which the prefix list are applied. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|interface> address-family +<ipv4-unicast|)ipv6-unicast\> route-map \<export|import\> \<name\> + +This command applies the route map named in \<name\> to the specified BGP +neighbor to control and modify routing information that is exchanged +between peers. The arguments `export` and `import` +specify the direction in which the route map are applied. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|interface> address-family +<ipv4-unicast|)ipv6-unicast\> filter-list \<export|import\> \<name\> + +This command applies the AS path access list filters named in \<name\> to the +specified BGP neighbor to restrict the routing information that BGP learns +and/or advertises. The arguments `export` and `import` +specify the direction in which the AS path access list are applied. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address[|interface\> address-family +\<ipv4-unicast|](##SUBST##|interface> address-family +<ipv4-unicast|)ipv6-unicast\> capability orf \<receive|send\> + +This command enables the ORF capability (described in `5291`) on the +local router, and enables ORF capability advertisement to the specified BGP +peer. The `receive` keyword configures a router to advertise ORF +receive capabilities. The `send` keyword configures a router to +advertise ORF send capabilities. To advertise a filter from a sender, you +must create an IP prefix list for the specified BGP peer applied in inbound +derection. + +</div> + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address|interface\> solo + +This command prevents from sending back prefixes learned from the neighbor. + +</div> + +#### BGP Scaling Configuration + +BGP routers connected inside the same AS through BGP belong to an internal BGP +session, or IBGP. In order to prevent routing table loops, IBGP speaker does +not advertise IBGP-learned routes to other IBGP speaker (Split Horizon +mechanism). As such, IBGP requires a full mesh of all peers. For large +networks, this quickly becomes unscalable. + +There are two ways that help us to mitigate the BGPs full-mesh requirement in +a network: + +> - Using BGP route-reflectors +> - Using BGP confederation + +##### Route Reflector Configuration + +Introducing route reflectors removes the need for the full-mesh. When you +configure a route reflector you have to tell the router whether the other IBGP +router is a client or non-client. A client is an IBGP router that the route +reflector will “reflect” routes to, the non-client is just a regular IBGP +neighbor. Route reflectors mechanism is described in `4456` and updated +by `7606`. + +<div class="cfgcmd"> + +set protocols bgp neighbor \<address\> address-family +\<ipv4-unicast|ipv6-unicast\> route-reflector-client + +This command specifies the given neighbor as route reflector client. + +</div> + +<div class="cfgcmd"> + +set protocols bgp parameters cluster-id \<id\> + +This command specifies cluster ID which identifies a collection of route +reflectors and their clients, and is used by route reflectors to avoid +looping. By default cluster ID is set to the BGP router id value, but can be +set to an arbitrary 32-bit value. + +</div> + +##### Confederation Configuration + +A BGP confederation divides our AS into sub-ASes to reduce the number of +required IBGP peerings. Within a sub-AS we still require full-mesh IBGP but +between these sub-ASes we use something that looks like EBGP but behaves like +IBGP (called confederation BGP). Confederation mechanism is described in +`5065` + +<div class="cfgcmd"> + +set protocols bgp parameters confederation identifier +\<asn\> + +This command specifies a BGP confederation identifier. \<asn\> is the number +of the autonomous system that internally includes multiple sub-autonomous +systems (a confederation). + +</div> + +<div class="cfgcmd"> + +set protocols bgp parameters confederation peers \<nsubasn\> + +This command sets other confederations \<nsubasn\> as members of autonomous +system specified by `confederation identifier <asn>`. + +</div> + +## Operational Mode Commands + +### Show + +<div class="opcmd"> + +show bgp \<ip|ipv6\> + +This command displays all entries in BGP routing table. + +</div> + +``` none +BGP table version is 10, local router ID is 10.0.35.3, vrf id 0 +Default local pref 100, local AS 65000 +Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, + i internal, r RIB-failure, S Stale, R Removed +Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self +Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path +*> 198.51.100.0/24 10.0.34.4 0 0 65004 i +*> 203.0.113.0/24 10.0.35.5 0 0 65005 i + +Displayed 2 routes and 2 total paths +``` + +<div class="opcmd"> + +show bgp \<ip[|ipv6\> \<address|](##SUBST##|ipv6> <address|)prefix\> + +This command displays information about the particular entry in the BGP +routing table. + +</div> + +``` none +BGP routing table entry for 198.51.100.0/24 +Paths: (1 available, best #1, table default) + Advertised to non peer-group peers: + 10.0.13.1 10.0.23.2 10.0.34.4 10.0.35.5 + 65004 + 10.0.34.4 from 10.0.34.4 (10.0.34.4) + Origin IGP, metric 0, valid, external, best (First path received) + Last update: Wed Jan 6 12:18:53 2021 +``` + +<div class="opcmd"> + +show bgp cidr-only + +This command displays routes with classless interdomain routing (CIDR). + +</div> + +<div class="opcmd"> + +show bgp \<ipv4|ipv6\> community \<value\> + +This command displays routes that belong to specified BGP communities. +Valid value is a community number in the range from 1 to 4294967200, +or AA:NN (autonomous system-community number/2-byte number), no-export, +local-as, or no-advertise. + +</div> + +<div class="opcmd"> + +show bgp \<ipv4|ipv6\> community-list \<name\> + +This command displays routes that are permitted by the BGP +community list. + +</div> + +<div class="opcmd"> + +show bgp \<ipv4|ipv6\> dampening dampened-paths + +This command displays BGP dampened routes. + +</div> + +<div class="opcmd"> + +show bgp \<ipv4|ipv6\> dampening flap-statistics + +This command displays information about flapping BGP routes. + +</div> + +<div class="opcmd"> + +show bgp \<ipv4|ipv6\> filter-list \<name\> + +This command displays BGP routes allowed by the specified AS Path +access list. + +</div> + +<div class="opcmd"> + +show bgp \<ipv4|ipv6\> neighbors \<address\> advertised-routes + +This command displays BGP routes advertised to a neighbor. + +</div> + +<div class="opcmd"> + +show bgp \<ipv4|ipv6\> neighbors \<address\> received-routes + +This command displays BGP routes originating from the specified BGP +neighbor before inbound policy is applied. To use this command inbound +soft reconfiguration must be enabled. + +</div> + +<div class="opcmd"> + +show bgp \<ipv4|ipv6\> neighbors \<address\> routes + +This command displays BGP received-routes that are accepted after filtering. + +</div> + +<div class="opcmd"> + +show bgp \<ipv4|ipv6\> neighbors \<address\> dampened-routes + +This command displays dampened routes received from BGP neighbor. + +</div> + +<div class="opcmd"> + +show bgp \<ipv4|ipv6\> regexp \<text\> + +This command displays information about BGP routes whose AS path +matches the specified regular expression. + +</div> + +<div class="opcmd"> + +show bgp \<ipv4|ipv6\> summary + +This command displays the status of all BGP connections. + +</div> + +``` none +IPv4 Unicast Summary: +BGP router identifier 10.0.35.3, local AS number 65000 vrf-id 0 +BGP table version 11 +RIB entries 5, using 920 bytes of memory +Peers 4, using 82 KiB of memory + +Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd +10.0.13.1 4 65000 148 159 0 0 0 02:16:01 0 +10.0.23.2 4 65000 136 143 0 0 0 02:13:21 0 +10.0.34.4 4 65004 161 163 0 0 0 02:16:01 1 +10.0.35.5 4 65005 162 166 0 0 0 02:16:01 1 + +Total number of neighbors 4 +``` + +### Reset + +<div class="opcmd"> + +reset bgp \<ipv4[|ipv6\> \<address\> \[soft \[in|](##SUBST##|ipv6> <address> [soft [in|)out\]\] + +This command resets BGP connections to the specified neighbor IP address. +With argument `soft` this command initiates a soft reset. If +you do not specify the `in` or `out` options, both +inbound and outbound soft reconfiguration are triggered. + +</div> + +<div class="opcmd"> + +reset ip bgp all + +This command resets all BGP connections of given router. + +</div> + +<div class="opcmd"> + +reset bgp \<ipv4|ipv6\> external + +This command resets all external BGP peers of given router. + +</div> + +<div class="opcmd"> + +reset bgp \<ipv4[|ipv6\> peer-group \<name\> \[soft \[in|](##SUBST##|ipv6> peer-group <name> [soft [in|)out\]\] + +This command resets BGP connections to the specified peer group. +With argument `soft` this command initiates a soft reset. If +you do not specify the `in` or `out` options, both +inbound and outbound soft reconfiguration are triggered. + +</div> + +## Examples + +### IPv4 peering + +A simple eBGP configuration: + +**Node 1:** + +``` none +set protocols bgp system-as 65534 +set protocols bgp neighbor 192.168.0.2 ebgp-multihop '2' +set protocols bgp neighbor 192.168.0.2 remote-as '65535' +set protocols bgp neighbor 192.168.0.2 update-source '192.168.0.1' +set protocols bgp neighbor 192.168.0.2 address-family ipv4-unicast +set protocols bgp address-family ipv4-unicast network '172.16.0.0/16' +set protocols bgp parameters router-id '192.168.0.1' +``` + +**Node 2:** + +``` none +set protocols bgp system-as 65535 +set protocols bgp neighbor 192.168.0.1 ebgp-multihop '2' +set protocols bgp neighbor 192.168.0.1 remote-as '65534' +set protocols bgp neighbor 192.168.0.1 update-source '192.168.0.2' +set protocols bgp neighbor 192.168.0.2 address-family ipv4-unicast +set protocols bgp address-family ipv4-unicast network '172.17.0.0/16' +set protocols bgp parameters router-id '192.168.0.2' +``` + +Don't forget, the CIDR declared in the network statement MUST **exist in your +routing table (dynamic or static), the best way to make sure that is true is +creating a static route:** + +**Node 1:** + +``` none +set protocols static route 172.16.0.0/16 blackhole distance '254' +``` + +**Node 2:** + +``` none +set protocols static route 172.17.0.0/16 blackhole distance '254' +``` + +### IPv6 peering + +A simple BGP configuration via IPv6. + +**Node 1:** + +``` none +set protocols bgp system-as 65534 +set protocols bgp neighbor 2001:db8::2 ebgp-multihop '2' +set protocols bgp neighbor 2001:db8::2 remote-as '65535' +set protocols bgp neighbor 2001:db8::2 update-source '2001:db8::1' +set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast +set protocols bgp address-family ipv6-unicast network '2001:db8:1::/48' +set protocols bgp parameters router-id '10.1.1.1' +``` + +**Node 2:** + +``` none +set protocols bgp system-as 65535 +set protocols bgp neighbor 2001:db8::1 ebgp-multihop '2' +set protocols bgp neighbor 2001:db8::1 remote-as '65534' +set protocols bgp neighbor 2001:db8::1 update-source '2001:db8::2' +set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast +set protocols bgp address-family ipv6-unicast network '2001:db8:2::/48' +set protocols bgp parameters router-id '10.1.1.2' +``` + +Don't forget, the CIDR declared in the network statement **MUST exist in your +routing table (dynamic or static), the best way to make sure that is true is +creating a static route:** + +**Node 1:** + +``` none +set protocols static route6 2001:db8:1::/48 blackhole distance '254' +``` + +**Node 2:** + +``` none +set protocols static route6 2001:db8:2::/48 blackhole distance '254' +``` + +### Route Filtering + +Route filter can be applied using a route-map: + +**Node1:** + +``` none +set policy prefix-list AS65535-IN rule 10 action 'permit' +set policy prefix-list AS65535-IN rule 10 prefix '172.16.0.0/16' +set policy prefix-list AS65535-OUT rule 10 action 'deny' +set policy prefix-list AS65535-OUT rule 10 prefix '172.16.0.0/16' +set policy prefix-list6 AS65535-IN rule 10 action 'permit' +set policy prefix-list6 AS65535-IN rule 10 prefix '2001:db8:2::/48' +set policy prefix-list6 AS65535-OUT rule 10 action 'deny' +set policy prefix-list6 AS65535-OUT rule 10 prefix '2001:db8:2::/48' + +set policy route-map AS65535-IN rule 10 action 'permit' +set policy route-map AS65535-IN rule 10 match ip address prefix-list 'AS65535-IN' +set policy route-map AS65535-IN rule 10 match ipv6 address prefix-list 'AS65535-IN' +set policy route-map AS65535-IN rule 20 action 'deny' +set policy route-map AS65535-OUT rule 10 action 'deny' +set policy route-map AS65535-OUT rule 10 match ip address prefix-list 'AS65535-OUT' +set policy route-map AS65535-OUT rule 10 match ipv6 address prefix-list 'AS65535-OUT' +set policy route-map AS65535-OUT rule 20 action 'permit' + +set protocols bgp system-as 65534 +set protocols bgp neighbor 2001:db8::2 address-family ipv4-unicast route-map export 'AS65535-OUT' +set protocols bgp neighbor 2001:db8::2 address-family ipv4-unicast route-map import 'AS65535-IN' +set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast route-map export 'AS65535-OUT' +set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast route-map import 'AS65535-IN' +``` + +**Node2:** + +``` none +set policy prefix-list AS65534-IN rule 10 action 'permit' +set policy prefix-list AS65534-IN rule 10 prefix '172.17.0.0/16' +set policy prefix-list AS65534-OUT rule 10 action 'deny' +set policy prefix-list AS65534-OUT rule 10 prefix '172.17.0.0/16' +set policy prefix-list6 AS65534-IN rule 10 action 'permit' +set policy prefix-list6 AS65534-IN rule 10 prefix '2001:db8:1::/48' +set policy prefix-list6 AS65534-OUT rule 10 action 'deny' +set policy prefix-list6 AS65534-OUT rule 10 prefix '2001:db8:1::/48' + +set policy route-map AS65534-IN rule 10 action 'permit' +set policy route-map AS65534-IN rule 10 match ip address prefix-list 'AS65534-IN' +set policy route-map AS65534-IN rule 10 match ipv6 address prefix-list 'AS65534-IN' +set policy route-map AS65534-IN rule 20 action 'deny' +set policy route-map AS65534-OUT rule 10 action 'deny' +set policy route-map AS65534-OUT rule 10 match ip address prefix-list 'AS65534-OUT' +set policy route-map AS65534-OUT rule 10 match ipv6 address prefix-list 'AS65534-OUT' +set policy route-map AS65534-OUT rule 20 action 'permit' + +set protocols bgp system-as 65535 +set protocols bgp neighbor 2001:db8::1 address-family ipv4-unicast route-map export 'AS65534-OUT' +set protocols bgp neighbor 2001:db8::1 address-family ipv4-unicast route-map import 'AS65534-IN' +set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast route-map export 'AS65534-OUT' +set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast route-map import 'AS65534-IN' +``` + +We could expand on this and also deny link local and multicast in the rule 20 +action deny. diff --git a/docs/configuration/protocols/md-failover.md b/docs/configuration/protocols/md-failover.md new file mode 100644 index 00000000..06ce402d --- /dev/null +++ b/docs/configuration/protocols/md-failover.md @@ -0,0 +1,131 @@ +# Failover + +Failover routes are manually configured routes, but they only install +to the routing table if the health-check target is alive. +If the target is not alive the route is removed from the routing table +until the target becomes available. + +## Failover Routes + +<div class="cfgcmd"> + +set protocols failover route \<subnet\> next-hop \<address\> check +target \<target-address\> + +Configure next-hop <span class="title-ref">\<address\></span> and <span class="title-ref">\<target-address\></span> for an IPv4 static +route. Specify the target +IPv4 address for health checking. + +</div> + +<div class="cfgcmd"> + +set protocols failover route \<subnet\> next-hop \<address\> check +timeout \<timeout\> + +Timeout in seconds between health target checks. + +Range is 1 to 300, default is 10. + +</div> + +<div class="cfgcmd"> + +set protocols failover route \<subnet\> next-hop \<address\> check +type \<protocol\> + +Defines protocols for checking ARP, ICMP, TCP + +Default is `icmp`. + +</div> + +<div class="cfgcmd"> + +set protocols failover route \<subnet\> next-hop \<address\> check +policy \<policy\> + +Policy for checking targets + +</div> + +- `all-available` all checking target addresses must be available to pass + this check + +- `any-available` any of the checking target addresses must be available + to pass this check + + > Default is `any-available`. + +<div class="cfgcmd"> + +set protocols failover route \<subnet\> next-hop \<address\> +interface \<interface\> + +Next-hop interface for the route + +</div> + +<div class="cfgcmd"> + +set protocols failover route \<subnet\> next-hop \<address\> +metric \<metric\> + +Route metric + +Default 1. + +</div> + +## Example + +**One gateway:** + +``` none +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check target '192.0.2.1' +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check timeout '5' +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check type 'icmp' +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 interface 'eth0' +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 metric '10' +``` + +Show the route + +``` none +vyos@vyos:~$ show ip route 203.0.113.1 + Routing entry for 203.0.113.1/32 + Known via "kernel", distance 0, metric 10, best + Last update 00:00:39 ago + * 192.0.2.1, via eth0 +``` + +**Two gateways and different metrics:** + +``` none +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check target '192.0.2.1' +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check timeout '5' +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check type 'icmp' +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 interface 'eth0' +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 metric '10' + +set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check target '198.51.100.99' +set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check timeout '5' +set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check type 'icmp' +set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 interface 'eth2' +set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 metric '20' +``` + +Show the route + +``` none +vyos@vyos:~$ show ip route 203.0.113.1 +Routing entry for 203.0.113.1/32 + Known via "kernel", distance 0, metric 10, best + Last update 00:08:06 ago + * 192.0.2.1, via eth0 + +Routing entry for 203.0.113.1/32 + Known via "kernel", distance 0, metric 20 + Last update 00:08:14 ago + * 198.51.100.1, via eth2 +``` diff --git a/docs/configuration/protocols/md-igmp-proxy.md b/docs/configuration/protocols/md-igmp-proxy.md new file mode 100644 index 00000000..f35f1747 --- /dev/null +++ b/docs/configuration/protocols/md-igmp-proxy.md @@ -0,0 +1,88 @@ +lastproofread +2023-11-13 + +# IGMP Proxy + +`IGMP (Internet Group Management Protocol)` proxy sends IGMP host messages +on behalf of a connected client. The configuration must define one, and only one +upstream interface, and one or more downstream interfaces. + +## Configuration + +<div class="cfgcmd"> + +set protocols igmp-proxy interface \<interface\> role +\<upstream | downstream\> + +- **upstream:** The upstream network interface is the outgoing interface + which is responsible for communicating to available multicast data sources. + There can only be one upstream interface. +- **downstream:** Downstream network interfaces are the distribution + interfaces to the destination networks, where multicast clients can join + groups and receive multicast data. One or more downstream interfaces must + be configured. + +</div> + +<div class="cfgcmd"> + +set protocols igmp-proxy interface \<interface\> alt-subnet \<network\> + +Defines alternate sources for multicasting and IGMP data. The network address +must be on the following format 'a.b.c.d/n'. By default, the router will +accept data from sources on the same network as configured on an interface. +If the multicast source lies on a remote network, one must define from where +traffic should be accepted. + +This is especially useful for the upstream interface, since the source for +multicast traffic is often from a remote location. + +This option can be supplied multiple times. + +</div> + +<div class="cfgcmd"> + +set protocols igmp-proxy disable-quickleave + +Disables quickleave mode. In this mode the daemon will not send a Leave IGMP +message upstream as soon as it receives a Leave message for any downstream +interface. The daemon will not ask for Membership reports on the downstream +interfaces, and if a report is received the group is not joined again the +upstream. + +If it's vital that the daemon should act exactly like a real multicast client +on the upstream interface, this function should be enabled. + +Enabling this function increases the risk of bandwidth saturation. + +</div> + +<div class="cfgcmd"> + +set protocols igmp-proxy disable + +Disable this service. + +</div> + +### Example + +Interface <span class="title-ref">eth1</span> LAN is behind NAT. In order to subscribe <span class="title-ref">10.0.0.0/23</span> subnet +multicast which is in <span class="title-ref">eth0</span> WAN we need to configure igmp-proxy. + +``` none +set protocols igmp-proxy interface eth0 role upstream +set protocols igmp-proxy interface eth0 alt-subnet 10.0.0.0/23 +set protocols igmp-proxy interface eth1 role downstream +``` + +## Operation + +<div class="opcmd"> + +restart igmp-proxy + +Restart the IGMP proxy process. + +</div> diff --git a/docs/configuration/protocols/md-index.md b/docs/configuration/protocols/md-index.md new file mode 100644 index 00000000..60e20bc9 --- /dev/null +++ b/docs/configuration/protocols/md-index.md @@ -0,0 +1,20 @@ +# Protocols + +<div class="toctree" maxdepth="1" includehidden=""> + +babel +bfd +bgp +failover +igmp-proxy +isis +mpls +segment-routing +ospf +pim +pim6 +rip +rpki +static + +</div> diff --git a/docs/configuration/protocols/md-isis.md b/docs/configuration/protocols/md-isis.md new file mode 100644 index 00000000..8081860a --- /dev/null +++ b/docs/configuration/protocols/md-isis.md @@ -0,0 +1,662 @@ +# IS-IS + +`IS-IS (Intermediate System to Intermediate System)` is a link-state +interior gateway protocol (IGP) which is described in ISO10589, +`1195`, `5308`. IS-IS runs the Dijkstra shortest-path first (SPF) +algorithm to create a database of the network’s topology, and +from that database to determine the best (that is, lowest cost) path to a +destination. The intermediate systems (the name for routers) exchange topology +information with their directly conencted neighbors. IS-IS runs directly on +the data link layer (Layer 2). IS-IS addresses are called +`NETs (Network Entity Titles)` and can be 8 to 20 bytes long, but are +generally 10 bytes long. The tree database that is created with IS-IS is +similar to the one that is created with OSPF in that the paths chosen should +be similar. Comparisons to OSPF are inevitable and often are reasonable ones +to make in regards to the way a network will respond with either IGP. + +## General + +### Configuration + +#### Mandatory Settings + +For IS-IS top operate correctly, one must do the equivalent of a Router ID in +CLNS. This Router ID is called the `NET (Network Entity Title)`. This +must be unique for each and every router that is operating in IS-IS. It also +must not be duplicated otherwise the same issues that occur within OSPF will +occur within IS-IS when it comes to said duplication. + +<div class="cfgcmd"> + +set protocols isis net \<network-entity-title\> + +This commad sets network entity title (NET) provided in ISO format. + +Here is an example `NET (Network Entity Title)` value: + +``` none +49.0001.1921.6800.1002.00 +``` + +The CLNS address consists of the following parts: + +- `AFI (Address family authority identifier)` - `49` The AFI value + 49 is what IS-IS uses for private addressing. +- Area identifier: `0001` IS-IS area number (numberical area `1`) +- System identifier: `1921.6800.1002` - for system idetifiers we recommend + to use IP address or MAC address of the router itself. The way to construct + this is to keep all of the zeroes of the router IP address, and then change + the periods from being every three numbers to every four numbers. The + address that is listed here is `192.168.1.2`, which if expanded will turn + into `192.168.001.002`. Then all one has to do is move the dots to have + four numbers instead of three. This gives us `1921.6800.1002`. +- `NET (Network Entity Title)` selector: `00` Must always be 00. This + setting indicates "this system" or "local system." + +</div> + +<div class="cfgcmd"> + +set protocols isis interface \<interface\> + +This command enables IS-IS on this interface, and allows for +adjacency to occur. Note that the name of IS-IS instance must be +the same as the one used to configure the IS-IS process. + +</div> + +#### IS-IS Global Configuration + +<div class="cfgcmd"> + +set protocols isis dynamic-hostname + +This command enables support for dynamic hostname TLV. Dynamic hostname +mapping determined as described in `2763`, Dynamic Hostname +Exchange Mechanism for IS-IS. + +</div> + +<div class="cfgcmd"> + +set protocols isis level \<level-1[|level-1-2|](##SUBST##|level-1-2|)level-2\> + +This command defines the IS-IS router behavior: + +- **level-1** - Act as a station (Level 1) router only. +- **level-1-2** - Act as a station (Level 1) router and area (Level 2) router. +- **level-2-only** - Act as an area (Level 2) router only. + +</div> + +<div class="cfgcmd"> + +set protocols isis lsp-mtu \<size\> + +This command configures the maximum size of generated +`LSPs (Link State PDUs)`, in bytes. The size range is 128 to 4352. + +</div> + +<div class="cfgcmd"> + +set protocols isis metric-style \<narrow[|transition|](##SUBST##|transition|)wide\> + +This command sets old-style (ISO 10589) or new style packet formats: + +- **narrow** - Use old style of TLVs with narrow metric. +- **transition** - Send and accept both styles of TLVs during transition. +- **wide** - Use new style of TLVs to carry wider metric. + +</div> + +<div class="cfgcmd"> + +set protocols isis purge-originator + +This command enables `6232` purge originator identification. Enable +purge originator identification (POI) by adding the type, length and value +(TLV) with the Intermediate System (IS) identification to the LSPs that do +not contain POI information. If an IS generates a purge, VyOS adds this TLV +with the system ID of the IS to the purge. + +</div> + +<div class="cfgcmd"> + +set protocols isis set-attached-bit + +This command sets ATT bit to 1 in Level1 LSPs. It is described in `3787`. + +</div> + +<div class="cfgcmd"> + +set protocols isis set-overload-bit + +This command sets overload bit to avoid any transit traffic through this +router. It is described in `3787`. + +</div> + +<div class="cfgcmd"> + +set protocols isis name default-information originate \<ipv4|ipv6\> +level-1 + +This command will generate a default-route in L1 database. + +</div> + +<div class="cfgcmd"> + +set protocols isis name default-information originate \<ipv4|ipv6\> +level-2 + +This command will generate a default-route in L2 database. + +</div> + +<div class="cfgcmd"> + +set protocols isis ldp-sync + +This command will enable IGP-LDP synchronization globally for ISIS. This +requires for LDP to be functional. This is described in `5443`. By +default all interfaces operational in IS-IS are enabled for synchronization. +Loopbacks are exempt. + +</div> + +<div class="cfgcmd"> + +set protocols isis ldp-sync holddown \<seconds\> + +This command will change the hold down value globally for IGP-LDP +synchronization during convergence/interface flap events. + +</div> + +#### Interface Configuration + +<div class="cfgcmd"> + +set protocols isis interface \<interface\> circuit-type +\<level-1[|level-1-2|](##SUBST##|level-1-2|)level-2-only\> + +This command specifies circuit type for interface: + +- **level-1** - Level-1 only adjacencies are formed. +- **level-1-2** - Level-1-2 adjacencies are formed +- **level-2-only** - Level-2 only adjacencies are formed + +</div> + +<div class="cfgcmd"> + +set protocols isis interface \<interface\> hello-interval +\<seconds\> + +This command sets hello interval in seconds on a given interface. +The range is 1 to 600. + +</div> + +<div class="cfgcmd"> + +set protocols isis interface \<interface\> hello-multiplier +\<seconds\> + +This command sets multiplier for hello holding time on a given +interface. The range is 2 to 100. + +</div> + +<div class="cfgcmd"> + +set protocols isis interface \<interface\> hello-padding + +This command configures padding on hello packets to accommodate asymmetrical +maximum transfer units (MTUs) from different hosts as described in +`3719`. This helps to prevent a premature adjacency Up state when one +routing devices MTU does not meet the requirements to establish the adjacency. + +</div> + +<div class="cfgcmd"> + +set protocols isis interface \<interface\> metric \<metric\> + +This command set default metric for circuit. + +The metric range is 1 to 16777215 (Max value depend if metric support narrow +or wide value). + +</div> + +<div class="cfgcmd"> + +set protocols isis interface \<interface\> network +point-to-point + +This command specifies network type to Point-to-Point. The default +network type is broadcast. + +</div> + +<div class="cfgcmd"> + +set protocols isis interface \<interface\> passive + +This command configures the passive mode for this interface. + +</div> + +<div class="cfgcmd"> + +set protocols isis interface \<interface\> password +plaintext-password \<text\> + +This command configures the authentication password for the interface. + +</div> + +<div class="cfgcmd"> + +set protocols isis interface \<interface\> priority \<number\> + +This command sets priority for the interface for +`DIS (Designated Intermediate System)` election. The priority +range is 0 to 127. + +</div> + +<div class="cfgcmd"> + +set protocols isis interface \<interface\> psnp-interval +\<number\> + +This command sets PSNP interval in seconds. The interval range is 0 +to 127. + +</div> + +<div class="cfgcmd"> + +set protocols isis interface \<interface\> +no-three-way-handshake + +This command disables Three-Way Handshake for P2P adjacencies which +described in `5303`. Three-Way Handshake is enabled by default. + +</div> + +<div class="cfgcmd"> + +set protocols isis interface \<interface\> ldp-sync disable + +This command disables IGP-LDP sync for this specific interface. + +</div> + +<div class="cfgcmd"> + +set protocols isis interface \<interface\> ldp-sync holddown +\<seconds\> + +This command will change the hold down value for IGP-LDP synchronization +during convergence/interface flap events, but for this interface only. + +</div> + +#### Route Redistribution + +<div class="cfgcmd"> + +set protocols isis redistribute ipv4 \<route source\> level-1 + +This command redistributes routing information from the given route source +into the ISIS database as Level-1. There are six modes available for route +source: bgp, connected, kernel, ospf, rip, static. + +</div> + +<div class="cfgcmd"> + +set protocols isis redistribute ipv4 \<route source\> level-2 + +This command redistributes routing information from the given route source +into the ISIS database as Level-2. There are six modes available for route +source: bgp, connected, kernel, ospf, rip, static. + +</div> + +<div class="cfgcmd"> + +set protocols isis redistribute ipv4 \<route source\> +\<level-1|level-2\> metric \<number\> + +This command specifies metric for redistributed routes from the given route +source. There are six modes available for route source: bgp, connected, +kernel, ospf, rip, static. The metric range is 1 to 16777215. + +</div> + +<div class="cfgcmd"> + +set protocols isis redistribute ipv4 \<route source\> +\<level-1|level-2\> route-map \<name\> + +This command allows to use route map to filter redistributed routes from +the given route source. There are six modes available for route source: +bgp, connected, kernel, ospf, rip, static. + +</div> + +#### Timers + +<div class="cfgcmd"> + +set protocols isis lsp-gen-interval \<seconds\> + +This command sets minimum interval in seconds between regenerating same +LSP. The interval range is 1 to 120. + +</div> + +<div class="cfgcmd"> + +set protocols isis lsp-refresh-interval \<seconds\> + +This command sets LSP refresh interval in seconds. IS-IS generates LSPs +when the state of a link changes. However, to ensure that routing +databases on all routers remain converged, LSPs in stable networks are +generated on a regular basis even though there has been no change to +the state of the links. The interval range is 1 to 65235. The default +value is 900 seconds. + +</div> + +<div class="cfgcmd"> + +set protocols isis max-lsp-lifetime \<seconds\> + +This command sets LSP maximum LSP lifetime in seconds. The interval range +is 350 to 65535. LSPs remain in a database for 1200 seconds by default. +If they are not refreshed by that time, they are deleted. You can change +the LSP refresh interval or the LSP lifetime. The LSP refresh interval +should be less than the LSP lifetime or else LSPs will time out before +they are refreshed. + +</div> + +<div class="cfgcmd"> + +set protocols isis spf-interval \<seconds\> + +This command sets minimum interval between consecutive SPF calculations in +seconds.The interval range is 1 to 120. + +</div> + +<div class="cfgcmd"> + +set protocols isis spf-delay-ietf holddown \<milliseconds\> + +</div> + +<div class="cfgcmd"> + +set protocols isis spf-delay-ietf init-delay +\<milliseconds\> + +</div> + +<div class="cfgcmd"> + +set protocols isis spf-delay-ietf long-delay +\<milliseconds\> + +</div> + +<div class="cfgcmd"> + +set protocols isis spf-delay-ietf short-delay +\<milliseconds\> + +</div> + +<div class="cfgcmd"> + +set protocols isis spf-delay-ietf time-to-learn +\<milliseconds\> + +This commands specifies the Finite State Machine (FSM) intended to +control the timing of the execution of SPF calculations in response +to IGP events. The process described in `8405`. + +</div> + +## Examples + +### Enable IS-IS + +**Node 1:** + +``` none +set interfaces loopback lo address '192.168.255.255/32' +set interfaces ethernet eth1 address '192.0.2.1/24' + +set protocols isis interface eth1 +set protocols isis interface lo +set protocols isis net '49.0001.1921.6825.5255.00' +``` + +**Node 2:** + +``` none +set interfaces ethernet eth1 address '192.0.2.2/24' + +set interfaces loopback lo address '192.168.255.254/32' +set interfaces ethernet eth1 address '192.0.2.2/24' + +set protocols isis interface eth1 +set protocols isis interface lo +set protocols isis net '49.0001.1921.6825.5254.00' +``` + +This gives us the following neighborships, Level 1 and Level 2: + +``` none +Node-1@vyos:~$ show isis neighbor +Area VyOS: + System Id Interface L State Holdtime SNPA + vyos eth1 1 Up 28 0c87.6c09.0001 + vyos eth1 2 Up 28 0c87.6c09.0001 + +Node-2@vyos:~$ show isis neighbor +Area VyOS: + System Id Interface L State Holdtime SNPA + vyos eth1 1 Up 29 0c33.0280.0001 + vyos eth1 2 Up 28 0c33.0280.0001 +``` + +Here's the IP routes that are populated. Just the loopback: + +``` none +Node-1@vyos:~$ show ip route isis +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +I 192.0.2.0/24 [115/20] via 192.0.2.2, eth1 inactive, weight 1, 00:02:22 +I>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1, weight 1, 00:02:22 + +Node-2@vyos:~$ show ip route isis +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +I 192.0.2.0/24 [115/20] via 192.0.2.1, eth1 inactive, weight 1, 00:02:21 +I>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1, weight 1, 00:02:21 +``` + +### Enable IS-IS and redistribute routes not natively in IS-IS + +**Node 1:** + +``` none +set interfaces dummy dum0 address '203.0.113.1/24' +set interfaces ethernet eth1 address '192.0.2.1/24' + +set policy prefix-list EXPORT-ISIS rule 10 action 'permit' +set policy prefix-list EXPORT-ISIS rule 10 prefix '203.0.113.0/24' +set policy route-map EXPORT-ISIS rule 10 action 'permit' +set policy route-map EXPORT-ISIS rule 10 match ip address prefix-list 'EXPORT-ISIS' + +set protocols isis interface eth1 +set protocols isis net '49.0001.1921.6800.1002.00' +set protocols isis redistribute ipv4 connected level-2 route-map 'EXPORT-ISIS' +``` + +**Node 2:** + +``` none +set interfaces ethernet eth1 address '192.0.2.2/24' + +set protocols isis interface eth1 +set protocols isis net '49.0001.1921.6800.2002.00' +``` + +Routes on Node 2: + +``` none +Node-2@r2:~$ show ip route isis +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued route, r - rejected route + +I 203.0.113.0/24 [115/10] via 192.0.2.1, eth1, 00:03:42 +``` + +### Enable IS-IS and IGP-LDP synchronization + +**Node 1:** + +``` none +set interfaces loopback lo address 192.168.255.255/32 +set interfaces ethernet eth0 address 192.0.2.1/24 + +set protocols isis interface eth0 +set protocols isis interface lo passive +set protocols isis ldp-sync +set protocols isis net 49.0001.1921.6825.5255.00 + +set protocols mpls interface eth0 +set protocols mpls ldp discovery transport-ipv4-address 192.168.255.255 +set protocols mpls ldp interface lo +set protocols mpls ldp interface eth0 +set protocols mpls ldp parameters transport-prefer-ipv4 +set protocols mpls ldp router-id 192.168.255.255 +``` + +This gives us IGP-LDP synchronization for all non-loopback interfaces with +a holddown timer of zero seconds: + +``` none +Node-1@vyos:~$ show isis mpls ldp-sync +eth0 + LDP-IGP Synchronization enabled: yes + holddown timer in seconds: 0 + State: Sync achieved +``` + +### Enable IS-IS with Segment Routing (Experimental) + +**Node 1:** + +``` none +set interfaces loopback lo address '192.168.255.255/32' +set interfaces ethernet eth1 address '192.0.2.1/24' + +set protocols isis interface eth1 +set protocols isis interface lo +set protocols isis net '49.0001.1921.6825.5255.00' +set protocols isis segment-routing global-block high-label-value '599' +set protocols isis segment-routing global-block low-label-value '550' +set protocols isis segment-routing prefix 192.168.255.255/32 index value '1' +set protocols isis segment-routing prefix 192.168.255.255/32 index explicit-null +set protocols mpls interface 'eth1' +``` + +**Node 2:** + +``` none +set interfaces loopback lo address '192.168.255.254/32' +set interfaces ethernet eth1 address '192.0.2.2/24' + +set protocols isis interface eth1 +set protocols isis interface lo +set protocols isis net '49.0001.1921.6825.5254.00' +set protocols isis segment-routing global-block high-label-value '599' +set protocols isis segment-routing global-block low-label-value '550' +set protocols isis segment-routing prefix 192.168.255.254/32 index value '2' +set protocols isis segment-routing prefix 192.168.255.254/32 index explicit-null +set protocols mpls interface 'eth1' +``` + +This gives us MPLS segment routing enabled and labels for far end loopbacks: + +``` none +Node-1@vyos:~$ show mpls table + Inbound Label Type Nexthop Outbound Label + ---------------------------------------------------------------------- + 552 SR (IS-IS) 192.0.2.2 IPv4 Explicit Null <-- Node-2 loopback learned on Node-1 + 15000 SR (IS-IS) 192.0.2.2 implicit-null + 15001 SR (IS-IS) fe80::e87:6cff:fe09:1 implicit-null + 15002 SR (IS-IS) 192.0.2.2 implicit-null + 15003 SR (IS-IS) fe80::e87:6cff:fe09:1 implicit-null + +Node-2@vyos:~$ show mpls table + Inbound Label Type Nexthop Outbound Label + --------------------------------------------------------------------- + 551 SR (IS-IS) 192.0.2.1 IPv4 Explicit Null <-- Node-1 loopback learned on Node-2 + 15000 SR (IS-IS) 192.0.2.1 implicit-null + 15001 SR (IS-IS) fe80::e33:2ff:fe80:1 implicit-null + 15002 SR (IS-IS) 192.0.2.1 implicit-null + 15003 SR (IS-IS) fe80::e33:2ff:fe80:1 implicit-null +``` + +Here is the routing tables showing the MPLS segment routing label operations: + +``` none +Node-1@vyos:~$ show ip route isis +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +I 192.0.2.0/24 [115/20] via 192.0.2.2, eth1 inactive, weight 1, 00:07:48 +I>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1, label IPv4 Explicit Null, weight 1, 00:03:39 + +Node-2@vyos:~$ show ip route isis +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +I 192.0.2.0/24 [115/20] via 192.0.2.1, eth1 inactive, weight 1, 00:07:46 +I>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1, label IPv4 Explicit Null, weight 1, 00:03:43 +``` diff --git a/docs/configuration/protocols/md-mpls.md b/docs/configuration/protocols/md-mpls.md new file mode 100644 index 00000000..8b729d8c --- /dev/null +++ b/docs/configuration/protocols/md-mpls.md @@ -0,0 +1,419 @@ +# MPLS + +`MPLS (Multi-Protocol Label Switching)` is a packet forwarding paradigm +which differs from regular IP forwarding. Instead of IP addresses being used to +make the decision on finding the exit interface, a router will instead use an +exact match on a 32 bit/4 byte header called the MPLS label. This label is +inserted between the ethernet (layer 2) header and the IP (layer 3) header. +One can statically or dynamically assign label allocations, but we will focus +on dynamic allocation of labels using some sort of label distribution protocol +(such as the aptly named Label Distribution Protocol / LDP, Resource Reservation +Protocol / RSVP, or Segment Routing through OSPF/ISIS). These protocols allow +for the creation of a unidirectional/unicast path called a labeled switched +path (initialized as LSP) throughout the network that operates very much like +a tunnel through the network. An easy way of thinking about how an MPLS LSP +actually forwards traffic throughout a network is to think of a GRE tunnel. +They are not the same in how they operate, but they are the same in how they +handle the tunneled packet. It would be good to think of MPLS as a tunneling +technology that can be used to transport many different types of packets, to +aid in traffic engineering by allowing one to specify paths throughout the +network (using RSVP or SR), and to generally allow for easier intra/inter +network transport of data packets. + +For more information on how MPLS label switching works, please go visit +[Wikipedia (MPLS)](https://en.wikipedia.org/wiki/Multiprotocol_Label_Switching). + +<div class="note"> + +<div class="title"> + +Note + +</div> + +MPLS support in VyOS is not finished yet, and therefore its +functionality is limited. Currently there is no support for MPLS enabled VPN +services such as L2VPNs and mVPNs. RSVP support is also not present as the +underlying routing stack (FRR) does not implement it. Currently VyOS +implements LDP as described in RFC 5036; other LDP standard are the +following ones: RFC 6720, RFC 6667, RFC 5919, RFC 5561, RFC 7552, RFC 4447. +Because MPLS is already available (FRR also supports RFC 3031). + +</div> + +## Label Distribution Protocol + +The `MPLS (Multi-Protocol Label Switching)` architecture does not assume +a single protocol to create MPLS paths. VyOS supports the Label Distribution +Protocol (LDP) as implemented by FRR, based on `5036`. + +`LDP (Label Distribution Protocol)` is a TCP based MPLS signaling protocol +that distributes labels creating MPLS label switched paths in a dynamic manner. +LDP is not a routing protocol, as it relies on other routing protocols for +forwarding decisions. LDP cannot bootstrap itself, and therefore relies on said +routing protocols for communication with other routers that use LDP. + +In order to allow for LDP on the local router to exchange label advertisements +with other routers, a TCP session will be established between automatically +discovered and statically assigned routers. LDP will try to establish a TCP +session to the **transport address** of other routers. Therefore for LDP to +function properly please make sure the transport address is shown in the +routing table and reachable to traffic at all times. + +It is highly recommended to use the same address for both the LDP router-id and +the discovery transport address, but for VyOS MPLS LDP to work both parameters +must be explicitly set in the configuration. + +Another thing to keep in mind with LDP is that much like BGP, it is a protocol +that runs on top of TCP. It however does not have an ability to do something +like a refresh capability like BGPs route refresh capability. Therefore one +might have to reset the neighbor for a capability change or a configuration +change to work. + +## Configuration Options + +<div class="cfgcmd"> + +set protocols mpls interface \<interface\> + +Use this command to enable MPLS processing on the interface you define. + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp interface \<interface\> + +Use this command to enable LDP on the interface you define. + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp router-id \<address\> + +Use this command to configure the IP address used as the LDP router-id of the +local device. + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp discovery transport-ipv4-address \<address\> + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp discovery transport-ipv6-address \<address\> + +Use this command to set the IPv4 or IPv6 transport-address used by LDP. + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp neighbor \<address\> password \<password\> + +Use this command to configure authentication for LDP peers. Set the +IP address of the LDP peer and a password that should be shared in +order to become neighbors. + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp neighbor \<address\> session-holdtime \<seconds\> + +Use this command to configure a specific session hold time for LDP peers. +Set the IP address of the LDP peer and a session hold time that should be +configured for it. You may have to reset the neighbor for this to work. + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp neighbor \<address\> ttl-security +\<disable | hop count\> + +Use this command to enable, disable, or specify hop count for TTL security +for LDP peers. By default the value is set to 255 (or max TTL). + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp discovery hello-ipv4-interval \<seconds\> + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp discovery hello-ipv4-holdtime \<seconds\> + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp discovery hello-ipv6-interval \<seconds\> + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp discovery hello-ipv6-holdtime \<seconds\> + +Use these commands if you would like to set the discovery hello and hold time +parameters. + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp discovery session-ipv4-holdtime \<seconds\> + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp discovery session-ipv6-holdtime \<seconds\> + +Use this command if you would like to set the TCP session hold time intervals. + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp import ipv4 import-filter filter-access-list +\<access list number\> + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp import ipv6 import-filter filter-access-list6 +\<access list number\> + +Use these commands to control the importing of forwarding equivalence classes +(FECs) for LDP from neighbors. This would be useful for example on only +accepting the labeled routes that are needed and not ones that are not +needed, such as accepting loopback interfaces and rejecting all others. + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp export ipv4 export-filter filter-access-list +\<access list number\> + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp export ipv6 export-filter filter-access-list6 +\<access list number\> + +Use these commands to control the exporting of forwarding equivalence classes +(FECs) for LDP to neighbors. This would be useful for example on only +announcing the labeled routes that are needed and not ones that are not +needed, such as announcing loopback interfaces and no others. + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp export ipv4 explicit-null + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp export ipv6 explicit-null + +Use this command if you would like for the router to advertise FECs with a +label of 0 for explicit null operations. + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp allocation ipv4 access-list +\<access list number\> + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp allocation ipv6 access-list6 +\<access list number\> + +Use this command if you would like to control the local FEC allocations for +LDP. A good example would be for your local router to not allocate a label for +everything. Just a label for what it's useful. A good example would be just a +loopback label. + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp parameters cisco-interop-tlv + +Use this command to use a Cisco non-compliant format to send and interpret +the Dual-Stack capability TLV for IPv6 LDP communications. This is related to +`7552`. + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp parameters ordered-control + +Use this command to use ordered label distribution control mode. FRR +by default uses independent label distribution control mode for label +distribution. This is related to `5036`. + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp parameters transport-prefer-ipv4 + +Use this command to prefer IPv4 for TCP peer transport connection for LDP +when both an IPv4 and IPv6 LDP address are configured on the same interface. + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp targeted-neighbor ipv4 enable + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp targeted-neighbor ipv6 enable + +Use this command to enable targeted LDP sessions to the local router. The +router will then respond to any sessions that are trying to connect to it that +are not a link local type of TCP connection. + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp targeted-neighbor ipv4 address \<address\> + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp targeted-neighbor ipv6 address \<address\> + +Use this command to enable the local router to try and connect with a targeted +LDP session to another router. + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp targeted-neighbor ipv4 hello-holdtime +\<seconds\> + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp targeted-neighbor ipv4 hello-interval +\<seconds\> + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp targeted-neighbor ipv6 hello-holdtime +\<seconds\> + +</div> + +<div class="cfgcmd"> + +set protocols mpls ldp targeted-neighbor ipv6 hello-interval +\<seconds\> + +Use these commands if you would like to set the discovery hello and hold time +parameters for the targeted LDP neighbors. + +</div> + +### Sample configuration to setup LDP on VyOS + +``` none +set protocols ospf area 0 network '192.168.255.252/32' <--- Routing for loopback +set protocols ospf area 0 network '192.168.0.5/32' <--- Routing for an interface connecting to the network +set protocols ospf parameters router-id '192.168.255.252' <--- Router ID setting for OSPF +set protocols mpls interface 'eth1' <--- Enable MPLS for an interface connecting to network +set protocols mpls ldp discovery transport-ipv4-address '192.168.255.252' <--- Transport address for LDP for TCP sessions to connect to +set protocols mpls ldp interface 'eth1' <--- Enable LDP for an interface connecting to network +set protocols mpls ldp interface 'lo' <--- Enable LDP on loopback for future services connectivity +set protocols mpls ldp router-id '192.168.255.252' <--- Router ID setting for LDP +set interfaces ethernet eth1 address '192.168.0.5/31' <--- Interface IP for connecting to network +set interfaces loopback lo address '192.168.255.252/32' <--- Interface loopback IP for router ID and other uses +``` + +## Operational Mode Commands + +When LDP is working, you will be able to see label information in the outcome +of `show ip route`. Besides that information, there are also specific *show* +commands for LDP: + +### Show + +<div class="opcmd"> + +show mpls ldp binding + +Use this command to see the Label Information Base. + +</div> + +<div class="opcmd"> + +show mpls ldp discovery + +Use this command to see discovery hello information + +</div> + +<div class="opcmd"> + +show mpls ldp interface + +Use this command to see LDP interface information + +</div> + +<div class="opcmd"> + +show mpls ldp neighbor + +Use this command to see LDP neighbor information + +</div> + +<div class="opcmd"> + +show mpls ldp neighbor detail + +Use this command to see detailed LDP neighbor information + +</div> + +### Reset + +<div class="opcmd"> + +reset mpls ldp neighbor \<IPv4 or IPv6 address\> + +Use this command to reset an LDP neighbor/TCP session that is established + +</div> diff --git a/docs/configuration/protocols/md-ospf.md b/docs/configuration/protocols/md-ospf.md new file mode 100644 index 00000000..a70bd840 --- /dev/null +++ b/docs/configuration/protocols/md-ospf.md @@ -0,0 +1,1772 @@ +# OSPF + +`OSPF (Open Shortest Path First)` is a routing protocol for Internet +Protocol (IP) networks. It uses a link state routing (LSR) algorithm and falls +into the group of interior gateway protocols (IGPs), operating within a single +autonomous system (AS). It is defined as OSPF Version 2 in `2328` (1998) +for IPv4. Updates for IPv6 are specified as OSPF Version 3 in `5340` +(2008). OSPF supports the `CIDR (Classless Inter-Domain Routing)` +addressing model. + +OSPF is a widely used IGP in large enterprise networks. + +## OSPFv2 (IPv4) + +### Configuration + +#### General + +VyOS does not have a special command to start the OSPF process. The OSPF process +starts when the first ospf enabled interface is configured. + +<div class="cfgcmd"> + +set protocols ospf area \<number\> network \<A.B.C.D/M\> + +This command specifies the OSPF enabled interface(s). If the interface has +an address from defined range then the command enables OSPF on this +interface so router can provide network information to the other ospf +routers via this interface. + +This command is also used to enable the OSPF process. The area number can be +specified in decimal notation in the range from 0 to 4294967295. Or it +can be specified in dotted decimal notation similar to ip address. + +Prefix length in interface must be equal or bigger (i.e. smaller network) +than prefix length in network statement. For example statement above doesn't +enable ospf on interface with address 192.168.1.1/23, but it does on +interface with address 192.168.1.129/25. + +In some cases it may be more convenient to enable OSPF on a per +interface/subnet +basis `set protocols ospf interface <interface> area <x.x.x.x | x>` + +</div> + +<div class="cfgcmd"> + +set protocols ospf auto-cost reference-bandwidth \<number\> + +This command sets the reference bandwidth for cost calculations, where +bandwidth can be in range from 1 to 4294967, specified in Mbits/s. The +default is 100Mbit/s (i.e. a link of bandwidth 100Mbit/s or higher will +have a cost of 1. Cost of lower bandwidth links will be scaled with +reference to this cost). + +</div> + +<div class="cfgcmd"> + +set protocols ospf parameters router-id \<rid\> + +This command sets the router-ID of the OSPF process. The router-ID may be an +IP address of the router, but need not be – it can be any arbitrary 32bit +number. However it MUST be unique within the entire OSPF domain to the OSPF +speaker – bad things will happen if multiple OSPF speakers are configured +with the same router-ID! + +</div> + +#### Optional + +<div class="cfgcmd"> + +set protocols ospf default-information originate \[always\] +\[metric \<number\>\] \[metric-type \<1|2\>\] \[route-map \<name\>\] + +Originate an AS-External (type-5) LSA describing a default route into all +external-routing capable areas, of the specified metric and metric type. +If the `always` keyword is given then the default is always +advertised, even when there is no default present in the routing table. +The argument `route-map` specifies to advertise the default route +if the route map is satisfied. + +</div> + +<div class="cfgcmd"> + +set protocols ospf distance global \<distance\> + +This command change distance value of OSPF globally. +The distance range is 1 to 255. + +</div> + +<div class="cfgcmd"> + +set protocols ospf distance ospf \<external[|inter-area|](##SUBST##|inter-area|)intra-area\> +\<distance\> + +This command change distance value of OSPF. The arguments are the distance +values for external routes, inter-area routes and intra-area routes +respectively. The distance range is 1 to 255. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Routes with a distance of 255 are effectively disabled and not +installed into the kernel. + +</div> + +</div> + +<div class="cfgcmd"> + +set protocols ospf log-adjacency-changes \[detail\] + +This command allows to log changes in adjacency. With the optional +`detail` argument, all changes in adjacency status are shown. +Without `detail`, only changes to full or regressions are shown. + +</div> + +<div class="cfgcmd"> + +set protocols ospf max-metric router-lsa +\<administrative[|on-shutdown \<seconds\>|](##SUBST##|on-shutdown <seconds>|)on-startup \<seconds\>\> + +This enables `3137` support, where the OSPF process describes its +transit links in its router-LSA as having infinite distance so that other +routers will avoid calculating transit paths through the router while +still being able to reach networks through the router. + +This support may be enabled administratively (and indefinitely) with the +`administrative` command. It may also be enabled conditionally. +Conditional enabling of max-metric router-lsas can be for a period of +seconds after startup with the `on-startup <seconds>` command +and/or for a period of seconds prior to shutdown with the +`on-shutdown <seconds>` command. The time range is 5 to 86400. + +</div> + +<div class="cfgcmd"> + +set protocols ospf parameters abr-type +\<cisco[|ibm|](##SUBST##|ibm|)shortcut|standard\> + +This command selects ABR model. OSPF router supports four ABR models: + +**cisco** – a router will be considered as ABR if it has several configured +links to the networks in different areas one of which is a backbone area. +Moreover, the link to the backbone area should be active (working). +**ibm** – identical to "cisco" model but in this case a backbone area link +may not be active. +**standard** – router has several active links to different areas. +**shortcut** – identical to "standard" but in this model a router is +allowed to use a connected areas topology without involving a backbone +area for inter-area connections. + +Detailed information about "cisco" and "ibm" models differences can be +found in `3509`. A "shortcut" model allows ABR to create routes +between areas based on the topology of the areas connected to this router +but not using a backbone area in case if non-backbone route will be +cheaper. For more information about "shortcut" model, +see <span class="title-ref">ospf-shortcut-abr-02.txt</span> + +</div> + +<div class="cfgcmd"> + +set protocols ospf parameters rfc1583-compatibility + +`2328`, the successor to `1583`, suggests according to section +G.2 (changes) in section 16.4.1 a change to the path preference algorithm +that prevents possible routing loops that were possible in the old version +of OSPFv2. More specifically it demands that inter-area paths and +intra-area backbone path are now of equal preference but still both +preferred to external paths. + +This command should NOT be set normally. + +</div> + +<div class="cfgcmd"> + +set protocols ospf interface \<interface\> passive \[disable\] + +This command specifies interface as passive. Passive interface advertises +its address, but does not run the OSPF protocol (adjacencies are not formed +and hello packets are not generated). + +The optional <span class="title-ref">disable</span> option allows to exclude interface from passive state. +This command is used if the command `passive-interface default` was +configured. + +</div> + +<div class="cfgcmd"> + +set protocols ospf passive-interface default + +This command specifies all interfaces as passive by default. Because this +command changes the configuration logic to a default passive; therefore, +interfaces where router adjacencies are expected need to be configured +by setting the `passive disable` flag for the specific interface. + +</div> + +<div class="cfgcmd"> + +set protocols ospf maximum-paths \<1-64\> + +Use this command to control the maximum number of equal cost paths to reach +a specific destination. The upper limit may differ if you change the value +of MULTIPATH_NUM during compilation. The default is MULTIPATH_NUM (64). + +</div> + +<div class="cfgcmd"> + +set protocols ospf refresh timers \<seconds\> + +The router automatically updates link-state information with its neighbors. +Only an obsolete information is updated which age has exceeded a specific +threshold. This parameter changes a threshold value, which by default is +1800 seconds (half an hour). The value is applied to the whole OSPF router. +The timer range is 10 to 1800. + +</div> + +<div class="cfgcmd"> + +set protocols ospf timers throttle spf +\<delay[|initial-holdtime|](##SUBST##|initial-holdtime|)max-holdtime\> \<seconds\> + +This command sets the initial delay, the initial-holdtime and the +maximum-holdtime between when SPF is calculated and the event which +triggered the calculation. The times are specified in milliseconds and must +be in the range of 0 to 600000 milliseconds. `delay` sets the +initial SPF schedule delay in milliseconds. The default value is 200 ms. +`initial-holdtime` sets the minimum hold time between two +consecutive SPF calculations. The default value is 1000 ms. +`max-holdtime` sets the maximum wait time between two +consecutive SPF calculations. The default value is 10000 ms. + +</div> + +<div class="cfgcmd"> + +set protocols ospf ldp-sync + +This command will enable IGP-LDP synchronization globally for OSPF. This +requires for LDP to be functional. This is described in `5443`. By +default all interfaces operational in OSPF are enabled for synchronization. +Loopbacks are exempt. + +</div> + +<div class="cfgcmd"> + +set protocols ospf ldp-sync holddown \<seconds\> + +This command will change the hold down value globally for IGP-LDP +synchronization during convergence/interface flap events. + +</div> + +<div class="cfgcmd"> + +set protocols ospf capability opaque + +ospfd supports Opaque LSA `2370` as partial support for MPLS Traffic +Engineering LSAs. The opaque-lsa capability must be enabled in the +configuration. + +An alternate command could be "mpls-te on" (Traffic Engineering) + +<div class="note"> + +<div class="title"> + +Note + +</div> + +FRR offers only partial support for some of the routing +protocol extensions that are used with MPLS-TE; it does not +support a complete RSVP-TE solution. + +</div> + +</div> + +#### Area Configuration + +<div class="cfgcmd"> + +set protocols ospf area \<number\> area-type stub + +This command specifies the area to be a Stub Area. That is, an area where +no router originates routes external to OSPF and hence an area where all +external routes are via the ABR(s). Hence, ABRs for such an area do not +need to pass AS-External LSAs (type-5) or ASBR-Summary LSAs (type-4) into +the area. They need only pass Network-Summary (type-3) LSAs into such an +area, along with a default-route summary. + +</div> + +<div class="cfgcmd"> + +set protocols ospf area \<number\> area-type stub no-summary + +This command specifies the area to be a Totally Stub Area. In addition to +stub area limitations this area type prevents an ABR from injecting +Network-Summary (type-3) LSAs into the specified stub area. Only default +summary route is allowed. + +</div> + +<div class="cfgcmd"> + +set protocols ospf area \<number\> area-type stub default-cost +\<number\> + +This command sets the cost of default-summary LSAs announced to stubby +areas. The cost range is 0 to 16777215. + +</div> + +<div class="cfgcmd"> + +set protocols ospf area \<number\> area-type nssa + +This command specifies the area to be a Not So Stubby Area. External +routing information is imported into an NSSA in Type-7 LSAs. Type-7 LSAs +are similar to Type-5 AS-external LSAs, except that they can only be +flooded into the NSSA. In order to further propagate the NSSA external +information, the Type-7 LSA must be translated to a Type-5 AS-external-LSA +by the NSSA ABR. + +</div> + +<div class="cfgcmd"> + +set protocols ospf area \<number\> area-type nssa no-summary + +This command specifies the area to be a NSSA Totally Stub Area. ABRs for +such an area do not need to pass Network-Summary (type-3) LSAs (except the +default summary route), ASBR-Summary LSAs (type-4) and AS-External LSAs +(type-5) into the area. But Type-7 LSAs that convert to Type-5 at the NSSA +ABR are allowed. + +</div> + +<div class="cfgcmd"> + +set protocols ospf area \<number\> area-type nssa default-cost +\<number\> + +This command sets the default cost of LSAs announced to NSSA areas. +The cost range is 0 to 16777215. + +</div> + +<div class="cfgcmd"> + +set protocols ospf area \<number\> area-type nssa translate +\<always[|candidate|](##SUBST##|candidate|)never\> + +Specifies whether this NSSA border router will unconditionally translate +Type-7 LSAs into Type-5 LSAs. When role is Always, Type-7 LSAs are +translated into Type-5 LSAs regardless of the translator state of other +NSSA border routers. When role is Candidate, this router participates in +the translator election to determine if it will perform the translations +duties. When role is Never, this router will never translate Type-7 LSAs +into Type-5 LSAs. + +</div> + +<div class="cfgcmd"> + +set protocols ospf area \<number\> authentication plaintext-password + +This command specifies that simple password authentication should be used +for the given area. The password must also be configured on a per-interface +basis. + +</div> + +<div class="cfgcmd"> + +set protocols ospf area \<number\> authentication md5 + +This command specify that OSPF packets must be authenticated with MD5 HMACs +within the given area. Keying material must also be configured on a +per-interface basis. + +</div> + +<div class="cfgcmd"> + +set protocols ospf area \<number\> range \<A.B.C.D/M\> \[cost \<number\>\] + +This command summarizes intra area paths from specified area into one +summary-LSA (Type-3) announced to other areas. This command can be used +only in ABR and ONLY router-LSAs (Type-1) and network-LSAs (Type-2) +(i.e. LSAs with scope area) can be summarized. AS-external-LSAs (Type-5) +can’t be summarized - their scope is AS. The optional argument +`cost` specifies the aggregated link metric. The metric range is 0 +to 16777215. + +</div> + +<div class="cfgcmd"> + +set protocols ospf area \<number\> range \<A.B.C.D/M\> not-advertise + +This command instead of summarizing intra area paths filter them - i.e. +intra area paths from this range are not advertised into other areas. +This command makes sense in ABR only. + +</div> + +<div class="cfgcmd"> + +set protocols ospf area \<number\> export-list \<acl_number\> + +Filter Type-3 summary-LSAs announced to other areas originated from +intra- area paths from specified area. +This command makes sense in ABR only. + +</div> + +<div class="cfgcmd"> + +set protocols ospf area \<number\> import-list \<acl_number\> + +Same as export-list, but it applies to paths announced into specified +area as Type-3 summary-LSAs. +This command makes sense in ABR only. + +</div> + +<div class="cfgcmd"> + +set protocols ospf area \<number\> range \<A.B.C.D/M\> substitute +\<E.F.G.H/M\> + +One Type-3 summary-LSA with routing info \<E.F.G.H/M\> is announced into +backbone area if defined area contains at least one intra-area network +(i.e. described with router-LSA or network-LSA) from range \<A.B.C.D/M\>. +This command makes sense in ABR only. + +</div> + +<div class="cfgcmd"> + +set protocols ospf area \<number\> shortcut \<default[|disable|](##SUBST##|disable|)enable\> + +This parameter allows to "shortcut" routes (non-backbone) for inter-area +routes. There are three modes available for routes shortcutting: + +**default** – this area will be used for shortcutting only if ABR does not +have a link to the backbone area or this link was lost. +**enable** – the area will be used for shortcutting every time the route +that goes through it is cheaper. +**disable** – this area is never used by ABR for routes shortcutting. + +</div> + +<div class="cfgcmd"> + +set protocols ospf area \<number\> virtual-link \<A.B.C.D\> + +Provides a backbone area coherence by virtual link establishment. + +In general, OSPF protocol requires a backbone area (area 0) to be coherent +and fully connected. I.e. any backbone area router must have a route to any +other backbone area router. Moreover, every ABR must have a link to +backbone area. However, it is not always possible to have a physical link +to a backbone area. In this case between two ABR (one of them has a link to +the backbone area) in the area (not stub area) a virtual link is organized. + +\<number\> – area identifier through which a virtual link goes. +\<A.B.C.D\> – ABR router-id with which a virtual link is established. Virtual +link must be configured on both routers. + +Formally, a virtual link looks like a point-to-point network connecting two +ABR from one area one of which physically connected to a backbone area. +This pseudo-network is considered to belong to a backbone area. + +</div> + +#### Interface Configuration + +<div class="cfgcmd"> + +set protocols ospf interface \<interface\> area \<x.x.x.x | x\> + +Enable ospf on an interface and set associated area. + +If you have a lot of interfaces, and/or a lot of subnets, then enabling +OSPF via this command may result in a slight performance improvement. + +</div> + +<div class="cfgcmd"> + +set protocols ospf interface \<interface\> authentication +plaintext-password \<text\> + +This command sets OSPF authentication key to a simple password. After +setting, all OSPF packets are authenticated. Key has length up to 8 chars. + +Simple text password authentication is insecure and deprecated in favour of +MD5 HMAC authentication. + +</div> + +<div class="cfgcmd"> + +set protocols ospf interface \<interface\> authentication md5 +key-id \<id\> md5-key \<text\> + +This command specifys that MD5 HMAC authentication must be used on this +interface. It sets OSPF authentication key to a cryptographic password. +Key-id identifies secret key used to create the message digest. This ID +is part of the protocol and must be consistent across routers on a link. +The key can be long up to 16 chars (larger strings will be truncated), +and is associated with the given key-id. + +</div> + +<div class="cfgcmd"> + +set protocols ospf interface \<interface\> bandwidth \<number\> + +This command sets the interface bandwidth for cost calculations, where +bandwidth can be in range from 1 to 100000, specified in Mbits/s. + +</div> + +<div class="cfgcmd"> + +set protocols ospf interface \<interface\> cost \<number\> + +This command sets link cost for the specified interface. The cost value is +set to router-LSA’s metric field and used for SPF calculation. The cost +range is 1 to 65535. + +</div> + +<div class="cfgcmd"> + +set protocols ospf interface \<interface\> dead-interval \<number\> + +Set number of seconds for router Dead Interval timer value used for Wait +Timer and Inactivity Timer. This value must be the same for all routers +attached to a common network. The default value is 40 seconds. The +interval range is 1 to 65535. + +</div> + +<div class="cfgcmd"> + +set protocols ospf interface \<interface\> hello-multiplier \<number\> + +The hello-multiplier specifies how many Hellos to send per second, from 1 +(every second) to 10 (every 100ms). Thus one can have 1s convergence time +for OSPF. If this form is specified, then the hello-interval advertised in +Hello packets is set to 0 and the hello-interval on received Hello packets +is not checked, thus the hello-multiplier need NOT be the same across +multiple routers on a common link. + +</div> + +<div class="cfgcmd"> + +set protocols ospf interface \<interface\> hello-interval \<number\> + +Set number of seconds for Hello Interval timer value. Setting this value, +Hello packet will be sent every timer value seconds on the specified +interface. This value must be the same for all routers attached to a +common network. The default value is 10 seconds. The interval range is 1 +to 65535. + +</div> + +<div class="cfgcmd"> + +set protocols ospf interface \<interface\> bfd + +This command enables `BFD (Bidirectional Forwarding Detection)` on +this OSPF link interface. + +</div> + +<div class="cfgcmd"> + +set protocols ospf interface \<interface\> mtu-ignore + +This command disables check of the MTU value in the OSPF DBD packets. Thus, +use of this command allows the OSPF adjacency to reach the FULL state even +though there is an interface MTU mismatch between two OSPF routers. + +</div> + +<div class="cfgcmd"> + +set protocols ospf interface \<interface\> network \<type\> + +This command allows to specify the distribution type for the network +connected to this interface: + +**broadcast** – broadcast IP addresses distribution. +**non-broadcast** – address distribution in NBMA networks topology. +**point-to-multipoint** – address distribution in point-to-multipoint +networks. +**point-to-point** – address distribution in point-to-point networks. + +</div> + +<div class="cfgcmd"> + +set protocols ospf interface \<interface\> priority \<number\> + +This command sets Router Priority integer value. The router with the +highest priority will be more eligible to become Designated Router. +Setting the value to 0, makes the router ineligible to become +Designated Router. The default value is 1. The interval range is 0 to 255. + +</div> + +<div class="cfgcmd"> + +set protocols ospf interface \<interface\> retransmit-interval +\<number\> + +This command sets number of seconds for RxmtInterval timer value. This +value is used when retransmitting Database Description and Link State +Request packets if acknowledge was not received. The default value is 5 +seconds. The interval range is 3 to 65535. + +</div> + +<div class="cfgcmd"> + +set protocols ospf interface \<interface\> transmit-delay \<number\> + +This command sets number of seconds for InfTransDelay value. It allows to +set and adjust for each interface the delay interval before starting the +synchronizing process of the router's database with all neighbors. The +default value is 1 seconds. The interval range is 3 to 65535. + +</div> + +<div class="cfgcmd"> + +set protocols ospf interface \<interface\> ldp-sync disable + +This command disables IGP-LDP sync for this specific interface. + +</div> + +<div class="cfgcmd"> + +set protocols ospf interface \<interface\> ldp-sync holddown +\<seconds\> + +This command will change the hold down value for IGP-LDP synchronization +during convergence/interface flap events, but for this interface only. + +</div> + +#### External Route Summarisation + +This feature summarises originated external LSAs (Type-5 and Type-7). Summary +Route will be originated on-behalf of all matched external LSAs. + +<div class="cfgcmd"> + +set protocols ospf aggregation timer \<seconds\> + +Configure aggregation delay timer interval. + +Summarisation starts only after this delay timer expiry. + +</div> + +<div class="cfgcmd"> + +set protocols ospf summary-address x.x.x.x/y \[tag (1-4294967295)\] + +This command enable/disables summarisation for the configured address range. + +Tag is the optional parameter. If tag configured Summary route will be +originated with the configured tag. + +</div> + +<div class="cfgcmd"> + +set protocols ospf summary-address x.x.x.x/y no-advertise + +This command to ensure not advertise the summary lsa for the matched +external LSAs. + +</div> + +#### Graceful Restart + +<div class="cfgcmd"> + +set protocols ospf graceful-restart \[grace-period (1-1800)\] + +Configure Graceful Restart `3623` restarting support. When enabled, +the default grace period is 120 seconds. + +To perform a graceful shutdown, the FRR `graceful-restart prepare ip ospf` EXEC-level command needs to be issued before restarting the +ospfd daemon. + +</div> + +<div class="cfgcmd"> + +set protocols ospf graceful-restart helper enable \[router-id A.B.C.D\] + +Configure Graceful Restart `3623` helper support. By default, helper support +is disabled for all neighbours. This config enables/disables helper support +on this router for all neighbours. + +To enable/disable helper support for a specific neighbour, the router-id +(A.B.C.D) has to be specified. + +</div> + +<div class="cfgcmd"> + +set protocols ospf graceful-restart helper no-strict-lsa-checking + +By default <span class="title-ref">strict-lsa-checking</span> is configured then the helper will abort +the Graceful Restart when a LSA change occurs which affects the restarting +router. + +This command disables it. + +</div> + +<div class="cfgcmd"> + +set protocols ospf graceful-restart helper supported-grace-time + +Supports as HELPER for configured grace period. + +</div> + +<div class="cfgcmd"> + +set protocols ospf graceful-restart helper planned-only + +It helps to support as HELPER only for planned restarts. + +By default, it supports both planned and unplanned outages. + +</div> + +#### Manual Neighbor Configuration + +OSPF routing devices normally discover their neighbors dynamically by +listening to the broadcast or multicast hello packets on the network. +Because an NBMA network does not support broadcast (or multicast), the +device cannot discover its neighbors dynamically, so you must configure all +the neighbors statically. + +<div class="cfgcmd"> + +set protocols ospf neighbor \<A.B.C.D\> + +This command specifies the IP address of the neighboring device. + +</div> + +<div class="cfgcmd"> + +set protocols ospf neighbor \<A.B.C.D\> poll-interval \<seconds\> + +This command specifies the length of time, in seconds, before the routing +device sends hello packets out of the interface before it establishes +adjacency with a neighbor. The range is 1 to 65535 seconds. The default +value is 60 seconds. + +</div> + +<div class="cfgcmd"> + +set protocols ospf neighbor \<A.B.C.D\> priority \<number\> + +This command specifies the router priority value of the nonbroadcast +neighbor associated with the IP address specified. The default is 0. +This keyword does not apply to point-to-multipoint interfaces. + +</div> + +#### Redistribution Configuration + +<div class="cfgcmd"> + +set protocols ospf redistribute \<route source\> + +This command redistributes routing information from the given route source +to the OSPF process. There are five modes available for route source: bgp, +connected, kernel, rip, static. + +</div> + +<div class="cfgcmd"> + +set protocols ospf default-metric \<number\> + +This command specifies the default metric value of redistributed routes. +The metric range is 0 to 16777214. + +</div> + +<div class="cfgcmd"> + +set protocols ospf redistribute \<route source\> metric \<number\> + +This command specifies metric for redistributed routes from the given +route source. There are five modes available for route source: bgp, +connected, kernel, rip, static. The metric range is 1 to 16777214. + +</div> + +<div class="cfgcmd"> + +set protocols ospf redistribute \<route source\> metric-type \<1|2\> + +This command specifies metric type for redistributed routes. Difference +between two metric types that metric type 1 is a metric which is +"commensurable" with inner OSPF links. When calculating a metric to the +external destination, the full path metric is calculated as a metric sum +path of a router which had advertised this link plus the link metric. +Thus, a route with the least summary metric will be selected. If external +link is advertised with metric type 2 the path is selected which lies +through the router which advertised this link with the least metric +despite of the fact that internal path to this router is longer (with more +cost). However, if two routers advertised an external link and with metric +type 2 the preference is given to the path which lies through the router +with a shorter internal path. If two different routers advertised two +links to the same external destimation but with different metric type, +metric type 1 is preferred. If type of a metric left undefined the router +will consider these external links to have a default metric type 2. + +</div> + +<div class="cfgcmd"> + +set protocols ospf redistribute \<route source\> route-map \<name\> + +This command allows to use route map to filter redistributed routes from +the given route source. There are five modes available for route source: +bgp, connected, kernel, rip, static. + +</div> + +#### Operational Mode Commands + +<div class="opcmd"> + +show ip ospf neighbor + +This command displays the neighbors status. + +</div> + +``` none +Neighbor ID Pri State Dead Time Address Interface RXmtL RqstL DBsmL +10.0.13.1 1 Full/DR 38.365s 10.0.13.1 eth0:10.0.13.3 0 0 0 +10.0.23.2 1 Full/Backup 39.175s 10.0.23.2 eth1:10.0.23.3 0 0 0 +``` + +<div class="opcmd"> + +show ip ospf neighbor detail + +This command displays the neighbors information in a detailed form, not +just a summary table. + +</div> + +``` none +Neighbor 10.0.13.1, interface address 10.0.13.1 + In the area 0.0.0.0 via interface eth0 + Neighbor priority is 1, State is Full, 5 state changes + Most recent state change statistics: + Progressive change 11m55s ago + DR is 10.0.13.1, BDR is 10.0.13.3 + Options 2 *|-|-|-|-|-|E|- + Dead timer due in 34.854s + Database Summary List 0 + Link State Request List 0 + Link State Retransmission List 0 + Thread Inactivity Timer on + Thread Database Description Retransmision off + Thread Link State Request Retransmission on + Thread Link State Update Retransmission on + +Neighbor 10.0.23.2, interface address 10.0.23.2 + In the area 0.0.0.1 via interface eth1 + Neighbor priority is 1, State is Full, 4 state changes + Most recent state change statistics: + Progressive change 41.193s ago + DR is 10.0.23.3, BDR is 10.0.23.2 + Options 2 *|-|-|-|-|-|E|- + Dead timer due in 35.661s + Database Summary List 0 + Link State Request List 0 + Link State Retransmission List 0 + Thread Inactivity Timer on + Thread Database Description Retransmision off + Thread Link State Request Retransmission on + Thread Link State Update Retransmission on +``` + +<div class="opcmd"> + +show ip ospf neighbor \<A.B.C.D\> + +This command displays the neighbors information in a detailed form for a +neighbor whose IP address is specified. + +</div> + +<div class="opcmd"> + +show ip ospf neighbor \<interface\> + +This command displays the neighbors status for a neighbor on the specified +interface. + +</div> + +<div class="opcmd"> + +show ip ospf interface \[\<interface\>\] + +This command displays state and configuration of OSPF the specified +interface, or all interfaces if no interface is given. + +</div> + +``` none +eth0 is up + ifindex 2, MTU 1500 bytes, BW 4294967295 Mbit <UP,BROADCAST,RUNNING,MULTICAST> + Internet Address 10.0.13.3/24, Broadcast 10.0.13.255, Area 0.0.0.0 + MTU mismatch detection: enabled + Router ID 10.0.23.3, Network Type BROADCAST, Cost: 1 + Transmit Delay is 1 sec, State Backup, Priority 1 + Backup Designated Router (ID) 10.0.23.3, Interface Address 10.0.13.3 + Multicast group memberships: OSPFAllRouters OSPFDesignatedRouters + Timer intervals configured, Hello 10s, Dead 40s, Wait 40s, Retransmit 5 + Hello due in 4.470s + Neighbor Count is 1, Adjacent neighbor count is 1 +eth1 is up + ifindex 3, MTU 1500 bytes, BW 4294967295 Mbit <UP,BROADCAST,RUNNING,MULTICAST> + Internet Address 10.0.23.3/24, Broadcast 10.0.23.255, Area 0.0.0.1 + MTU mismatch detection: enabled + Router ID 10.0.23.3, Network Type BROADCAST, Cost: 1 + Transmit Delay is 1 sec, State DR, Priority 1 + Backup Designated Router (ID) 10.0.23.2, Interface Address 10.0.23.2 + Saved Network-LSA sequence number 0x80000002 + Multicast group memberships: OSPFAllRouters OSPFDesignatedRouters + Timer intervals configured, Hello 10s, Dead 40s, Wait 40s, Retransmit 5 + Hello due in 4.563s + Neighbor Count is 1, Adjacent neighbor count is 1 +``` + +<div class="opcmd"> + +show ip ospf route \[detail\] + +This command displays the OSPF routing table, as determined by the most +recent SPF calculation. With the optional `detail` argument, +each route item's advertiser router and network attribute will be shown. + +</div> + +``` none +============ OSPF network routing table ============ +N IA 10.0.12.0/24 [3] area: 0.0.0.0 + via 10.0.13.3, eth0 +N 10.0.13.0/24 [1] area: 0.0.0.0 + directly attached to eth0 +N IA 10.0.23.0/24 [2] area: 0.0.0.0 + via 10.0.13.3, eth0 +N 10.0.34.0/24 [2] area: 0.0.0.0 + via 10.0.13.3, eth0 + +============ OSPF router routing table ============= +R 10.0.23.3 [1] area: 0.0.0.0, ABR + via 10.0.13.3, eth0 +R 10.0.34.4 [2] area: 0.0.0.0, ASBR + via 10.0.13.3, eth0 + +============ OSPF external routing table =========== +N E2 172.16.0.0/24 [2/20] tag: 0 + via 10.0.13.3, eth0 +``` + +The table consists of following data: + +**OSPF network routing table** – includes a list of acquired routes for all +accessible networks (or aggregated area ranges) of OSPF system. "IA" flag +means that route destination is in the area to which the router is not +connected, i.e. it’s an inter-area path. In square brackets a summary metric +for all links through which a path lies to this network is specified. "via" +prefix defines a router-gateway, i.e. the first router on the way to the +destination (next hop). +**OSPF router routing table** – includes a list of acquired routes to all +accessible ABRs and ASBRs. +**OSPF external routing table** – includes a list of acquired routes that are +external to the OSPF process. "E" flag points to the external link metric type +(E1 – metric type 1, E2 – metric type 2). External link metric is printed in +the "\<metric of the router which advertised the link\>/\<link metric\>" format. + +<div class="opcmd"> + +show ip ospf border-routers + +This command displays a table of paths to area boundary and autonomous +system boundary routers. + +</div> + +<div class="opcmd"> + +show ip ospf database + +This command displays a summary table with a database contents (LSA). + +</div> + +``` none +OSPF Router with ID (10.0.13.1) + + Router Link States (Area 0.0.0.0) + +Link ID ADV Router Age Seq# CkSum Link count +10.0.13.1 10.0.13.1 984 0x80000005 0xd915 1 +10.0.23.3 10.0.23.3 1186 0x80000008 0xfe62 2 +10.0.34.4 10.0.34.4 1063 0x80000004 0x4e3f 1 + + Net Link States (Area 0.0.0.0) + +Link ID ADV Router Age Seq# CkSum +10.0.13.1 10.0.13.1 994 0x80000003 0x30bb +10.0.34.4 10.0.34.4 1188 0x80000001 0x9411 + + Summary Link States (Area 0.0.0.0) + +Link ID ADV Router Age Seq# CkSum Route +10.0.12.0 10.0.23.3 1608 0x80000001 0x6ab6 10.0.12.0/24 +10.0.23.0 10.0.23.3 981 0x80000003 0xe232 10.0.23.0/24 + + AS External Link States + +Link ID ADV Router Age Seq# CkSum Route +172.16.0.0 10.0.34.4 1063 0x80000001 0xc40d E2 172.16.0.0/24 [0x0] +``` + +<div class="opcmd"> + +show ip ospf database \<type\> \[A.B.C.D\] +\[adv-router \<A.B.C.D\>|self-originate\] + +This command displays a database contents for a specific link advertisement +type. + +The type can be the following: +asbr-summary, external, network, nssa-external, opaque-area, opaque-as, +opaque-link, router, summary. + +\[A.B.C.D\] – link-state-id. With this specified the command displays portion +of the network environment that is being described by the advertisement. +The value entered depends on the advertisement’s LS type. It must be +entered in the form of an IP address. + +`adv-router <A.B.C.D>` – router id, which link advertisements need +to be reviewed. + +`self-originate` displays only self-originated LSAs from the local +router. + +</div> + +``` none +OSPF Router with ID (10.0.13.1) + + Router Link States (Area 0.0.0.0) + +LS age: 1213 +Options: 0x2 : *|-|-|-|-|-|E|- +LS Flags: 0x3 +Flags: 0x0 +LS Type: router-LSA +Link State ID: 10.0.13.1 +Advertising Router: 10.0.13.1 +LS Seq Number: 80000009 +Checksum: 0xd119 +Length: 36 + +Number of Links: 1 + +Link connected to: a Transit Network +(Link ID) Designated Router address: 10.0.13.1 +(Link Data) Router Interface address: 10.0.13.1 +Number of TOS metrics: 0 +TOS 0 Metric: 1 +``` + +<div class="opcmd"> + +show ip ospf database max-age + +This command displays LSAs in MaxAge list. + +</div> + +#### Examples + +##### Enable OSPF + +**Node 1** + +``` none +set interfaces loopback lo address 10.1.1.1/32 +set interfaces ethernet eth0 address 192.168.0.1/24 +set protocols ospf area 0 network 192.168.0.0/24 +set protocols ospf area 0 network 10.1.1.1/32 +set protocols ospf parameters router-id 10.1.1.1 +``` + +**Node 2** + +``` none +set interfaces loopback lo address 10.1.1.2/32 +set interfaces ethernet eth0 address 192.168.0.2/24 +set protocols ospf area 0 network 192.168.0.0/24 +set protocols ospf area 0 network 10.1.1.2/32 +set protocols ospf parameters router-id 10.1.1.2 +``` + +Here's the neighbors up: + +``` none +Node-1@vyos:~$ show ip ospf neighbor + +Neighbor ID Pri State Up Time Dead Time Address Interface RXmtL RqstL DBsmL +10.1.1.2 1 Full/DR 3m43s 36.094s 192.168.0.2 eth0:192.168.0.1 0 0 0 + + + +Node-2@vyos:~$ show ip ospf neighbor + +Neighbor ID Pri State Up Time Dead Time Address Interface RXmtL RqstL DBsmL +10.1.1.1 1 Full/Backup 3m47s 31.736s 192.168.0.1 eth0:192.168.0.2 0 0 0 +``` + +Here's the routes: + +``` none +Node-1@vyos:~$ show ip route ospf +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +O 10.1.1.1/32 [110/0] is directly connected, lo, weight 1, 00:00:14 +O>* 10.1.1.2/32 [110/1] via 192.168.0.2, eth0, weight 1, 00:00:07 +O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:32 + +Node-2@vyos:~$ show ip route ospf +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +O>* 10.1.1.1/32 [110/1] via 192.168.0.1, eth0, weight 1, 00:00:11 +O 10.1.1.2/32 [110/0] is directly connected, lo, weight 1, 00:00:04 +O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:18 +``` + +##### Enable OSPF with route redistribution of the loopback and default originate: + +**Node 1** + +``` none +set interfaces loopback lo address 10.1.1.1/32 +set protocols ospf area 0 network 192.168.0.0/24 +set protocols ospf default-information originate always +set protocols ospf default-information originate metric 10 +set protocols ospf default-information originate metric-type 2 +set protocols ospf log-adjacency-changes +set protocols ospf parameters router-id 10.1.1.1 +set protocols ospf redistribute connected metric-type 2 +set protocols ospf redistribute connected route-map CONNECT + +set policy route-map CONNECT rule 10 action permit +set policy route-map CONNECT rule 10 match interface lo +``` + +**Node 2** + +``` none +set interfaces loopback lo address 10.2.2.2/32 +set protocols ospf area 0 network 192.168.0.0/24 +set protocols ospf log-adjacency-changes +set protocols ospf parameters router-id 10.2.2.2 +set protocols ospf redistribute connected metric-type 2 +set protocols ospf redistribute connected route-map CONNECT + +set policy route-map CONNECT rule 10 action permit +set policy route-map CONNECT rule 10 match interface lo +``` + +##### Enable OSPF and IGP-LDP synchronization: + +**Node 1:** + +``` none +set interfaces loopback lo address 10.1.1.1/32 +set interfaces ethernet eth0 address 192.168.0.1/24 + +set protocols ospf area 0 network '192.168.0.0/24' +set protocols ospf area 0 network '10.1.1.1/32' +set protocols ospf parameters router-id '10.1.1.1' +set protocols ospf ldp-sync + +set protocols mpls interface eth0 +set protocols mpls ldp discovery transport-ipv4-address 10.1.1.1 +set protocols mpls ldp interface lo +set protocols mpls ldp interface eth0 +set protocols mpls ldp parameters transport-prefer-ipv4 +set protocols mpls ldp router-id 10.1.1.1 +``` + +This gives us IGP-LDP synchronization for all non-loopback interfaces with +a holddown timer of zero seconds: + +``` none +Node-1@vyos:~$ show ip ospf mpls ldp-sync + eth0 + LDP-IGP Synchronization enabled: yes + Holddown timer in seconds: 0 + State: Sync achieved +``` + +##### Enable OSPF with Segment Routing (Experimental): + +**Node 1** + +``` none +set interfaces loopback lo address 10.1.1.1/32 +set interfaces ethernet eth0 address 192.168.0.1/24 + +set protocols ospf area 0 network '192.168.0.0/24' +set protocols ospf area 0 network '10.1.1.1/32' +set protocols ospf parameters opaque-lsa +set protocols ospf parameters router-id '10.1.1.1' +set protocols ospf segment-routing global-block high-label-value '1100' +set protocols ospf segment-routing global-block low-label-value '1000' +set protocols ospf segment-routing prefix 10.1.1.1/32 index explicit-null +set protocols ospf segment-routing prefix 10.1.1.1/32 index value '1' +``` + +**Node 2** + +``` none +set interfaces loopback lo address 10.1.1.2/32 +set interfaces ethernet eth0 address 192.168.0.2/24 + +set protocols ospf area 0 network '192.168.0.0/24' +set protocols ospf area 0 network '10.1.1.2/32' +set protocols ospf parameters opaque-lsa +set protocols ospf parameters router-id '10.1.1.2' +set protocols ospf segment-routing global-block high-label-value '1100' +set protocols ospf segment-routing global-block low-label-value '1000' +set protocols ospf segment-routing prefix 10.1.1.2/32 index explicit-null +set protocols ospf segment-routing prefix 10.1.1.2/32 index value '2' +``` + +This gives us MPLS segment routing enabled and labels for far end loopbacks: + +``` none +Node-1@vyos:~$ show mpls table + Inbound Label Type Nexthop Outbound Label + ----------------------------------------------------------- + 1002 SR (OSPF) 192.168.0.2 IPv4 Explicit Null <-- Node-2 loopback learned on Node-1 + 15000 SR (OSPF) 192.168.0.2 implicit-null + 15001 SR (OSPF) 192.168.0.2 implicit-null + +Node-2@vyos:~$ show mpls table + Inbound Label Type Nexthop Outbound Label + ----------------------------------------------------------- + 1001 SR (OSPF) 192.168.0.1 IPv4 Explicit Null <-- Node-1 loopback learned on Node-2 + 15000 SR (OSPF) 192.168.0.1 implicit-null + 15001 SR (OSPF) 192.168.0.1 implicit-null +``` + +Here is the routing tables showing the MPLS segment routing label operations: + +``` none +Node-1@vyos:~$ show ip route ospf +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +O 10.1.1.1/32 [110/0] is directly connected, lo, weight 1, 00:03:43 +O>* 10.1.1.2/32 [110/1] via 192.168.0.2, eth0, label IPv4 Explicit Null, weight 1, 00:03:32 +O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:43 + +Node-2@vyos:~$ show ip route ospf +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +O>* 10.1.1.1/32 [110/1] via 192.168.0.1, eth0, label IPv4 Explicit Null, weight 1, 00:03:36 +O 10.1.1.2/32 [110/0] is directly connected, lo, weight 1, 00:03:51 +O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:51 +``` + +## OSPFv3 (IPv6) + +### Configuration + +#### General + +VyOS does not have a special command to start the OSPFv3 process. The OSPFv3 +process starts when the first ospf enabled interface is configured. + +<div class="cfgcmd"> + +set protocols ospfv3 interface \<interface\> area \<number\> + +This command specifies the OSPFv3 enabled interface. This command is also +used to enable the OSPF process. The area number can be specified in +decimal notation in the range from 0 to 4294967295. Or it can be specified +in dotted decimal notation similar to ip address. + +</div> + +<div class="cfgcmd"> + +set protocols ospfv3 parameters router-id \<rid\> + +This command sets the router-ID of the OSPFv3 process. The router-ID may be +an IP address of the router, but need not be – it can be any arbitrary +32bit number. However it MUST be unique within the entire OSPFv3 domain to +the OSPFv3 speaker – bad things will happen if multiple OSPFv3 speakers are +configured with the same router-ID! + +</div> + +#### Optional + +<div class="cfgcmd"> + +set protocols ospfv3 distance global \<distance\> + +This command change distance value of OSPFv3 globally. +The distance range is 1 to 255. + +</div> + +<div class="cfgcmd"> + +set protocols ospfv3 distance ospfv3 +\<external[|inter-area|](##SUBST##|inter-area|)intra-area\> \<distance\> + +This command change distance value of OSPFv3. The arguments are the +distance values for external routes, inter-area routes and intra-area +routes respectively. The distance range is 1 to 255. + +</div> + +#### Area Configuration + +<div class="cfgcmd"> + +set protocols ospfv3 area \<number\> range \<prefix\> + +This command summarizes intra area paths from specified area into one +Type-3 Inter-Area Prefix LSA announced to other areas. This command can be +used only in ABR. + +</div> + +<div class="cfgcmd"> + +set protocols ospfv3 area \<number\> range \<prefix\> not-advertise + +This command instead of summarizing intra area paths filter them - i.e. +intra area paths from this range are not advertised into other areas. This +command makes sense in ABR only. + +</div> + +#### Interface Configuration + +<div class="cfgcmd"> + +set protocols ospfv3 interface \<interface\> ipv6 cost \<number\> + +This command sets link cost for the specified interface. The cost value is +set to router-LSA’s metric field and used for SPF calculation. The cost +range is 1 to 65535. + +</div> + +<div class="cfgcmd"> + +set protocols ospfv3 interface \<interface\> dead-interval \<number\> + +Set number of seconds for router Dead Interval timer value used for Wait +Timer and Inactivity Timer. This value must be the same for all routers +attached to a common network. The default value is 40 seconds. The +interval range is 1 to 65535. + +</div> + +<div class="cfgcmd"> + +set protocols ospfv3 interface \<interface\> hello-interval +\<number\> + +Set number of seconds for Hello Interval timer value. Setting this value, +Hello packet will be sent every timer value seconds on the specified +interface. This value must be the same for all routers attached to a +common network. The default value is 10 seconds. The interval range is 1 +to 65535. + +</div> + +<div class="cfgcmd"> + +set protocols ospfv3 interface \<interface\> mtu-ignore + +This command disables check of the MTU value in the OSPF DBD packets. +Thus, use of this command allows the OSPF adjacency to reach the FULL +state even though there is an interface MTU mismatch between two OSPF +routers. + +</div> + +<div class="cfgcmd"> + +set protocols ospfv3 interface \<interface\> network \<type\> + +This command allows to specify the distribution type for the network +connected to this interface: + +**broadcast** – broadcast IP addresses distribution. +**point-to-point** – address distribution in point-to-point networks. + +</div> + +<div class="cfgcmd"> + +set protocols ospfv3 interface \<interface\> priority \<number\> + +This command sets Router Priority integer value. The router with the +highest priority will be more eligible to become Designated Router. +Setting the value to 0, makes the router ineligible to become Designated +Router. The default value is 1. The interval range is 0 to 255. + +</div> + +<div class="cfgcmd"> + +set protocols ospfv3 interface \<interface\> passive + +This command specifies interface as passive. Passive interface advertises +its address, but does not run the OSPF protocol (adjacencies are not formed +and hello packets are not generated). + +</div> + +<div class="cfgcmd"> + +set protocols ospfv3 interface \<interface\> retransmit-interval +\<number\> + +This command sets number of seconds for RxmtInterval timer value. This +value is used when retransmitting Database Description and Link State +Request packets if acknowledge was not received. The default value is 5 +seconds. The interval range is 3 to 65535. + +</div> + +<div class="cfgcmd"> + +set protocols ospfv3 interface \<interface\> transmit-delay +\<number\> + +This command sets number of seconds for InfTransDelay value. It allows to +set and adjust for each interface the delay interval before starting the +synchronizing process of the router's database with all neighbors. The +default value is 1 seconds. The interval range is 3 to 65535. + +</div> + +#### Graceful Restart + +<div class="cfgcmd"> + +set protocols ospfv3 graceful-restart \[grace-period (1-1800)\] + +Configure Graceful Restart `3623` restarting support. When enabled, +the default grace period is 120 seconds. + +To perform a graceful shutdown, the FRR `graceful-restart prepare ip ospf` EXEC-level command needs to be issued before restarting the +ospfd daemon. + +</div> + +<div class="cfgcmd"> + +set protocols ospfv3 graceful-restart helper enable \[router-id A.B.C.D\] + +Configure Graceful Restart `3623` helper support. By default, helper support +is disabled for all neighbours. This config enables/disables helper support +on this router for all neighbours. + +To enable/disable helper support for a specific neighbour, the router-id +(A.B.C.D) has to be specified. + +</div> + +<div class="cfgcmd"> + +set protocols ospfv3 graceful-restart helper lsa-check-disable + +By default <span class="title-ref">strict-lsa-checking</span> is configured then the helper will abort +the Graceful Restart when a LSA change occurs which affects the restarting +router. + +This command disables it. + +</div> + +<div class="cfgcmd"> + +set protocols ospfv3 graceful-restart helper supported-grace-time + +Supports as HELPER for configured grace period. + +</div> + +<div class="cfgcmd"> + +set protocols ospfv3 graceful-restart helper planned-only + +It helps to support as HELPER only for planned restarts. + +By default, it supports both planned and unplanned outages. + +</div> + +#### Redistribution Configuration + +<div class="cfgcmd"> + +set protocols ospfv3 redistribute \<route source\> + +This command redistributes routing information from the given route source +to the OSPFv3 process. There are five modes available for route source: +bgp, connected, kernel, ripng, static. + +</div> + +<div class="cfgcmd"> + +set protocols ospf redistribute \<route source\> route-map \<name\> + +This command allows to use route map to filter redistributed routes from +given route source. There are five modes available for route source: bgp, +connected, kernel, ripng, static. + +</div> + +#### Operational Mode Commands + +<div class="opcmd"> + +show ipv6 ospfv3 neighbor + +This command displays the neighbors status. + +</div> + +<div class="opcmd"> + +show ipv6 ospfv3 neighbor detail + +This command displays the neighbors information in a detailed form, not +just a summary table. + +</div> + +<div class="opcmd"> + +show ipv6 ospfv3 neighbor drchoice + +This command displays the neighbor DR choice information. + +</div> + +<div class="opcmd"> + +show ipv6 ospfv3 interface \[prefix\]|\[\<interface\> \[prefix\]\] + +This command displays state and configuration of OSPF the specified +interface, or all interfaces if no interface is given. Whith the argument +`prefix` this command shows connected prefixes to advertise. + +</div> + +<div class="opcmd"> + +show ipv6 ospfv3 route + +This command displays the OSPF routing table, as determined by the most +recent SPF calculation. + +</div> + +<div class="opcmd"> + +show ipv6 ospfv3 border-routers + +This command displays a table of paths to area boundary and autonomous +system boundary routers. + +</div> + +<div class="opcmd"> + +show ipv6 ospfv3 database + +This command displays a summary table with a database contents (LSA). + +</div> + +<div class="opcmd"> + +show ipv6 ospfv3 database \<type\> \[A.B.C.D\] +\[adv-router \<A.B.C.D\>|self-originate\] + +This command displays a database contents for a specific link +advertisement type. + +</div> + +<div class="opcmd"> + +show ipv6 ospfv3 redistribute + +This command displays external information redistributed into OSPFv3 + +</div> + +#### Configuration Example + +A typical configuration using 2 nodes. + +**Node 1:** + +``` none +set protocols ospfv3 interface eth1 area 0.0.0.0 +set protocols ospfv3 area 0.0.0.0 range 2001:db8:1::/64 +set protocols ospfv3 parameters router-id 192.168.1.1 +set protocols ospfv3 redistribute connected +``` + +**Node 2:** + +``` none +set protocols ospfv3 interface eth1 area 0.0.0.0 +set protocols ospfv3 area 0.0.0.0 range 2001:db8:2::/64 +set protocols ospfv3 parameters router-id 192.168.2.1 +set protocols ospfv3 redistribute connected +``` + +**To see the redistributed routes:** + +``` none +show ipv6 ospfv3 redistribute +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +You cannot easily redistribute IPv6 routes via OSPFv3 on a +WireGuard interface link. This requires you to configure link-local +addresses manually on the WireGuard interfaces, see `T1483`. + +</div> + +Example configuration for WireGuard interfaces: + +**Node 1** + +``` none +set interfaces wireguard wg01 address 'fe80::216:3eff:fe51:fd8c/64' +set interfaces wireguard wg01 address '192.168.0.1/24' +set interfaces wireguard wg01 peer ospf02 allowed-ips '::/0' +set interfaces wireguard wg01 peer ospf02 allowed-ips '0.0.0.0/0' +set interfaces wireguard wg01 peer ospf02 endpoint '10.1.1.101:12345' +set interfaces wireguard wg01 peer ospf02 pubkey 'ie3...=' +set interfaces wireguard wg01 port '12345' +set protocols ospfv3 parameters router-id 192.168.1.1 +set protocols ospfv3 interface 'wg01' area 0.0.0.0 +set protocols ospfv3 interface 'lo' area 0.0.0.0 +``` + +**Node 2** + +``` none +set interfaces wireguard wg01 address 'fe80::216:3eff:fe0a:7ada/64' +set interfaces wireguard wg01 address '192.168.0.2/24' +set interfaces wireguard wg01 peer ospf01 allowed-ips '::/0' +set interfaces wireguard wg01 peer ospf01 allowed-ips '0.0.0.0/0' +set interfaces wireguard wg01 peer ospf01 endpoint '10.1.1.100:12345' +set interfaces wireguard wg01 peer ospf01 pubkey 'NHI...=' +set interfaces wireguard wg01 port '12345' +set protocols ospfv3 parameters router-id 192.168.1.2 +set protocols ospfv3 interface 'wg01' area 0.0.0.0 +set protocols ospfv3 interface 'lo' area 0.0.0.0 +``` + +**Status** + +``` none +vyos@ospf01:~$ sh ipv6 ospfv3 neighbor +Neighbor ID Pri DeadTime State/IfState Duration I/F[State] +192.168.0.2 1 00:00:37 Full/PointToPoint 00:18:03 wg01[PointToPoint] + +vyos@ospf02# run sh ipv6 ospfv3 neighbor +Neighbor ID Pri DeadTime State/IfState Duration I/F[State] +192.168.0.1 1 00:00:39 Full/PointToPoint 00:19:44 wg01[PointToPoint] +``` diff --git a/docs/configuration/protocols/md-pim.md b/docs/configuration/protocols/md-pim.md new file mode 100644 index 00000000..2f31de95 --- /dev/null +++ b/docs/configuration/protocols/md-pim.md @@ -0,0 +1,345 @@ +lastproofread +2023-11-13 + +# PIM – Protocol Independent Multicast + +VyOS supports `PIM-SM (PIM Sparse Mode)` as well as +`IGMP (Internet Group Management Protocol)` v2 and v3 + +`PIM (Protocol Independent Multicast)` must be configured in every +interface of every participating router. Every router must also have the +location of the Rendevouz Point manually configured. Then, unidirectional +shared trees rooted at the Rendevouz Point will automatically be built +for multicast distribution. + +Traffic from multicast sources will go to the Rendezvous Point, and +receivers will pull it from a shared tree using `IGMP (Internet +Group Management Protocol)`. + +Multicast receivers will talk IGMP to their local router, so, besides +having PIM configured in every router, IGMP must also be configured in +any router where there could be a multicast receiver locally connected. + +VyOS supports both IGMP version 2 and version 3 (which allows +source-specific multicast). + +## PIM-SM - PIM Sparse Mode + +<div class="cfgcmd"> + +set protocols pim ecmp + +If PIM has the a choice of ECMP nexthops for a particular +`RPF (Reverse Path Forwarding)`, PIM will cause S,G flows to be +spread out amongst the nexthops. If this command is not specified then +the first nexthop found will be used. + +</div> + +<div class="cfgcmd"> + +set protocols pim ecmp rebalance + +If PIM is using ECMP and an interface goes down, cause PIM to rebalance all +S,G flows across the remaining nexthops. If this command is not configured +PIM only modifies those S,G flows that were using the interface that went +down. + +</div> + +<div class="cfgcmd"> + +set protocols pim join-prune-interval \<n\> + +Modify the join/prune interval that PIM uses to the new value. Time is +specified in seconds. + +The default time is 60 seconds. + +If you enter a value smaller than 60 seconds be aware that this can and +will affect convergence at scale. + +</div> + +<div class="cfgcmd"> + +set protocols pim keep-alive-timer \<n\> + +Modify the time out value for a S,G flow from 1-65535 seconds. If choosing +a value below 31 seconds be aware that some hardware platforms cannot see +data flowing in better than 30 second chunks. + +</div> + +<div class="cfgcmd"> + +set protocols pim packets \<n\> + +When processing packets from a neighbor process the number of packets +incoming at one time before moving on to the next task. + +The default value is 3 packets. + +This command is only useful at scale when you can possibly have a large +number of PIM control packets flowing. + +</div> + +<div class="cfgcmd"> + +set protocols pim register-accept-list \<prefix-list\> + +When PIM receives a register packet the source of the packet will be compared +to the prefix-list specified, and if a permit is received normal processing +continues. If a deny is returned for the source address of the register packet +a register stop message is sent to the source. + +</div> + +<div class="cfgcmd"> + +set protocols pim register-suppress-time \<n\> + +Modify the time that pim will register suppress a FHR will send register +notifications to the kernel. + +</div> + +<div class="cfgcmd"> + +set protocols pim rp \<address\> group \<group\> + +In order to use PIM, it is necessary to configure a `RP (Rendezvous Point)` +for join messages to be sent to. Currently the only methodology to do this is +via static rendezvous point commands. + +All routers in the PIM network must agree on these values. + +The first ip address is the RP's address and the second value is the matching +prefix of group ranges covered. + +</div> + +<div class="cfgcmd"> + +set protocols pim rp keep-alive-timer \<n\> + +Modify the time out value for a S,G flow from 1-65535 seconds at +`RP (Rendezvous Point)`. The normal keepalive period for the KAT(S,G) +defaults to 210 seconds. However, at the `RP (Rendezvous Point)`, the +keepalive period must be at least the Register_Suppression_Time, or the RP +may time out the (S,G) state before the next Null-Register arrives. +Thus, the KAT(S,G) is set to max(Keepalive_Period, RP_Keepalive_Period) +when a Register-Stop is sent. + +If choosing a value below 31 seconds be aware that some hardware platforms +cannot see data flowing in better than 30 second chunks. + +See `7761#section-4.1` for details. + +</div> + +<div class="cfgcmd"> + +set protocols pim no-v6-secondary + +When sending PIM hello packets tell PIM to not send any v6 secondary +addresses on the interface. This information is used to allow PIM to use v6 +nexthops in it's decision for `RPF (Reverse Path Forwarding)` lookup +if this option is not set (default). + +</div> + +<div class="cfgcmd"> + +set protocols pim spt-switchover infinity-and-beyond \[prefix-list \<list\>\] + +On the last hop router if it is desired to not switch over to the SPT tree +configure this command. + +Optional parameter prefix-list can be use to control which groups to switch or +not switch. If a group is PERMIT as per the prefix-list, then the SPT switchover +does not happen for it and if it is DENY, then the SPT switchover happens. + +</div> + +<div class="cfgcmd"> + +set protocols pim ssm prefix-list \<list\> + +Specify a range of group addresses via a prefix-list that forces PIM to never +do `SSM (Source-Specific Multicast)` over. + +</div> + +### Interface specific commands + +<div class="cfgcmd"> + +set protocols pim interface \<interface\> bfd \[profile \<name\>\] + +Automatically create BFD session for each RIP peer discovered in this +interface. When the BFD session monitor signalize that the link is down +the RIP peer is removed and all the learned routes associated with that +peer are removed. + +If optional profile parameter is used, select a BFD profile for the BFD +sessions created via this interface. + +</div> + +<div class="cfgcmd"> + +set protocols pim interface \<interface\> dr-priority \<n\> + +Set the `DR (Designated Router)` Priority for the interface. +This command is useful to allow the user to influence what node becomes +the DR for a LAN segment. + +</div> + +<div class="cfgcmd"> + +set protocols pim interface \<interface\> hello \<n\> + +Set the PIM hello and hold interval for a interface. + +</div> + +<div class="cfgcmd"> + +set protocols pim interface \<interface\> no-bsm + +Tell PIM that we would not like to use this interface to process +bootstrap messages. + +</div> + +<div class="cfgcmd"> + +set protocols pim interface \<interface\> no-unicast-bsm + +Tell PIM that we would not like to use this interface to process +unicast bootstrap messages. + +</div> + +<div class="cfgcmd"> + +set protocols pim interface \<interface\> passive + +Disable sending and receiving PIM control packets on the interface. + +<div class="cfgcmd"> + +set protocols pim interface \<interface\> source-address \<ip-address\> + +</div> + +If you have multiple addresses configured on a particular interface and would +like PIM to use a specific source address associated with that interface. + +</div> + +## IGMP - Internet Group Management Protocol) + +<div class="cfgcmd"> + +set protocols pim igmp watermark-warning \<n\> + +Configure watermark warning generation for an IGMP group limit. Generates +warning once the configured group limit is reached while adding new groups. + +</div> + +### Interface specific commands + +<div class="cfgcmd"> + +set protocols pim interface \<interface\> igmp +join \<multicast-address\> source-address \<IP-address\> + +Use this command to allow the selected interface to join a multicast +group defining the multicast address you want to join and the source +IP address too. + +</div> + +<div class="cfgcmd"> + +set protocols pim interface \<interface\> igmp +query-interval \<seconds\> + +Use this command to configure in the selected interface the IGMP +host query interval (1-1800) in seconds that PIM will use. + +</div> + +<div class="cfgcmd"> + +set protocols pim interface \<interface\> igmp +query-max-response-time \<n\> + +Use this command to configure in the selected interface the IGMP +query response timeout value (10-250) in deciseconds. If a report is +not returned in the specified time, it will be assumed the (S,G) or +(\*,G) state `7761#section-4.1` has timed out. + +</div> + +<div class="cfgcmd"> + +set protocols pim interface \<interface\> igmp version \<version-number\> + +Use this command to define in the selected interface whether you +choose IGMP version 2 or 3. + +The default value is 3. + +</div> + +#### Example + +In the following example we can see a basic multicast setup: + +<img src="/_static/images/multicast-basic.webp" class="align-center" style="width:90.0%" alt="Network Topology Diagram" /> + +**Router 1** + +``` none +set interfaces ethernet eth2 address '172.16.0.2/24' +set interfaces ethernet eth1 address '100.64.0.1/24' +set protocols ospf area 0 network '172.16.0.0/24' +set protocols ospf area 0 network '100.64.0.0/24' +set protocols igmp interface eth1 +set protocols pim interface eth1 +set protocols pim interface eth2 +set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' +``` + +**Router 3** + +``` none +set interfaces dummy dum0 address '172.16.255.1/24' +set interfaces ethernet eth0 address '172.16.0.1/24' +set interfaces ethernet eth1 address '172.16.1.1/24' +set protocols ospf area 0 network '172.16.0.0/24' +set protocols ospf area 0 network '172.16.255.0/24' +set protocols ospf area 0 network '172.16.1.0/24' +set protocols pim interface dum0 +set protocols pim interface eth0 +set protocols pim interface eth1 +set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' +``` + +**Router 2** + +``` none +set interfaces ethernet eth1 address '10.0.0.1/24' +set interfaces ethernet eth2 address '172.16.1.2/24' +set protocols ospf area 0 network '10.0.0.0/24' +set protocols ospf area 0 network '172.16.1.0/24' +set protocols pim interface eth1 +set protocols pim interface eth2 +set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' +``` diff --git a/docs/configuration/protocols/md-pim6.md b/docs/configuration/protocols/md-pim6.md new file mode 100644 index 00000000..6b3c00fc --- /dev/null +++ b/docs/configuration/protocols/md-pim6.md @@ -0,0 +1,122 @@ +# PIM6 - Protocol Independent Multicast for IPv6 + +VyOS facilitates IPv6 Multicast by supporting **PIMv6** and **MLD**. + +PIMv6 (Protocol Independent Multicast for IPv6) must be configured in every +interface of every participating router. Every router must also have the +location of the Rendevouz Point manually configured. +Then, unidirectional shared trees rooted at the Rendevouz Point will +automatically be built for multicast distribution. + +Traffic from multicast sources will go to the Rendezvous Point, and receivers +will pull it from a shared tree using MLD (Multicast Listener Discovery). + +Multicast receivers will talk MLD to their local router, so, besides having +PIMv6 configured in every router, MLD must also be configured in any router +where there could be a multicast receiver locally connected. + +VyOS supports both MLD version 1 and version 2 +(which allows source-specific multicast). + +## Basic commands + +These are the commands for a basic setup. + +<div class="cfgcmd"> + +set protocols pim6 interface \<interface-name\> + +Use this command to enable PIMv6 in the selected interface so that it +can communicate with PIMv6 neighbors. This command also enables MLD reports +and query on the interface unless `mld disable` is configured. + +</div> + +<div class="cfgcmd"> + +set protocols pim6 interface \<interface-name\> mld disable + +Disable MLD reports and query on the interface. + +</div> + +## Tuning commands + +You can also tune multicast with the following commands. + +<div class="cfgcmd"> + +set protocols pim6 interface \<interface-name\> mld interval \<seconds\> + +Use this command to configure in the selected interface the MLD +host query interval (1-65535) in seconds that PIM will use. +The default value is 125 seconds. + +</div> + +<div class="cfgcmd"> + +set protocols pim6 interface \<interface-name\> mld join \<multicast-address\> + +Use this command to allow the selected interface to join a multicast group. + +</div> + +<div class="cfgcmd"> + +set protocols pim6 interface \<interface-name\> mld join \<multicast-address\> source \<source-address\> + +Use this command to allow the selected interface to join a source-specific multicast +group. + +</div> + +<div class="cfgcmd"> + +set protocols pim6 interface \<interface-name\> mld last-member-query-count \<count\> + +Set the MLD last member query count. The default value is 2. + +</div> + +<div class="cfgcmd"> + +set protocols pim6 interface \<interface-name\> mld last-member-query-interval \<milliseconds\> + +Set the MLD last member query interval in milliseconds (100-6553500). The default value is 1000 milliseconds. + +</div> + +<div class="cfgcmd"> + +set protocols pim6 interface \<interface-name\> mld max-response-time \<milliseconds\> + +Set the MLD query response timeout in milliseconds (100-6553500). The default value is 10000 milliseconds. + +</div> + +<div class="cfgcmd"> + +set protocols pim6 interface \<interface-name\> mld version \<version-number\> + +Set the MLD version used on this interface. The default value is 2. + +</div> + +### Configuration Example + +To enable MLD reports and query on interfaces <span class="title-ref">eth0</span> and \`eth1\`: + +``` none +set protocols pim6 interface eth0 +set protocols pim6 interface eth1 +``` + +The following configuration explicitly joins multicast group <span class="title-ref">ff15::1234</span> on interface <span class="title-ref">eth1</span> +and source-specific multicast group <span class="title-ref">ff15::5678</span> with source address <span class="title-ref">2001:db8::1</span> on interface +\`eth1\`: + +``` none +set protocols pim6 interface eth0 mld join ff15::1234 +set protocols pim6 interface eth1 mld join ff15::5678 source 2001:db8::1 +``` diff --git a/docs/configuration/protocols/md-rip.md b/docs/configuration/protocols/md-rip.md new file mode 100644 index 00000000..1bd580ab --- /dev/null +++ b/docs/configuration/protocols/md-rip.md @@ -0,0 +1,361 @@ +lastproofread +2021-10-04 + +# RIP + +`RIP (Routing Information Protocol)` is a widely deployed interior gateway +protocol. RIP was developed in the 1970s at Xerox Labs as part of the XNS +routing protocol. RIP is a distance-vector protocol and is based on the +Bellman-Ford algorithms. As a distance-vector protocol, RIP router send updates +to its neighbors periodically, thus allowing the convergence to a known +topology. In each update, the distance to any given network will be broadcast +to its neighboring router. + +Supported versions of RIP are: + +> - RIPv1 as described in `1058` +> - RIPv2 as described in `2453` + +## General Configuration + +<div class="cfgcmd"> + +set protocols rip network \<A.B.C.D/M\> + +This command enables RIP and sets the RIP enable interface by NETWORK. +The interfaces which have addresses matching with NETWORK are enabled. + +</div> + +<div class="cfgcmd"> + +set protocols rip interface \<interface\> + +This command specifies a RIP enabled interface by interface name. Both +the sending and receiving of RIP packets will be enabled on the port +specified in this command. + +</div> + +<div class="cfgcmd"> + +set protocols rip neighbor \<A.B.C.D\> + +This command specifies a RIP neighbor. When a neighbor doesn’t understand +multicast, this command is used to specify neighbors. In some cases, not +all routers will be able to understand multicasting, where packets are +sent to a network or a group of addresses. In a situation where a neighbor +cannot process multicast packets, it is necessary to establish a direct +link between routers. + +</div> + +<div class="cfgcmd"> + +set protocols rip passive-interface interface \<interface\> + +This command sets the specified interface to passive mode. On passive mode +interface, all receiving packets are processed as normal and VyOS does not +send either multicast or unicast RIP packets except to RIP neighbors +specified with neighbor command. + +</div> + +<div class="cfgcmd"> + +set protocols rip passive-interface interface default + +This command specifies all interfaces to passive mode. + +</div> + +## Optional Configuration + +<div class="cfgcmd"> + +set protocols rip default-distance \<distance\> + +This command change the distance value of RIP. The distance range is 1 to 255. + +> <div class="note"> +> +> <div class="title"> +> +> Note +> +> </div> +> +> Routes with a distance of 255 are effectively disabled and not +> installed into the kernel. +> +> </div> + +</div> + +<div class="cfgcmd"> + +set protocols rip network-distance \<A.B.C.D/M\> distance \<distance\> + +This command sets default RIP distance to a specified value when the routes +source IP address matches the specified prefix. + +</div> + +<div class="cfgcmd"> + +set protocols rip network-distance \<A.B.C.D/M\> access-list \<name\> + +This command can be used with previous command to sets default RIP distance +to specified value when the route source IP address matches the specified +prefix and the specified access-list. + +</div> + +<div class="cfgcmd"> + +set protocols rip default-information originate + +This command generate a default route into the RIP. + +</div> + +<div class="cfgcmd"> + +set protocols rip distribute-list access-list \<in|out\> \<number\> + +This command can be used to filter the RIP path using access lists. +`in` and `out` this is the direction in which the access +lists are applied. + +</div> + +<div class="cfgcmd"> + +set protocols rip distribute-list interface \<interface\> access-list \<in|out\> \<number\> + +This command allows you apply access lists to a chosen interface to +filter the RIP path. + +</div> + +<div class="cfgcmd"> + +set protocols rip distribute-list prefix-list \<in|out\> \<name\> + +This command can be used to filter the RIP path using prefix lists. +`in` and `out` this is the direction in which the prefix +lists are applied. + +</div> + +<div class="cfgcmd"> + +set protocols rip distribute-list interface \<interface\> prefix-list \<in|out\> \<name\> + +This command allows you apply prefix lists to a chosen interface to +filter the RIP path. + +</div> + +<div class="cfgcmd"> + +set protocols rip route \<A.B.C.D/M\> + +This command is specific to FRR and VyOS. The route command makes a static +route only inside RIP. This command should be used only by advanced users +who are particularly knowledgeable about the RIP protocol. In most cases, +we recommend creating a static route in VyOS and redistributing it in RIP +using `redistribute static`. + +</div> + +<div class="cfgcmd"> + +set protocols rip timers update \<seconds\> + +This command specifies the update timer. Every update timer seconds, the +RIP process is awakened to send an unsolicited response message containing +the complete routing table to all neighboring RIP routers. The time range +is 5 to 2147483647. The default value is 30 seconds. + +</div> + +<div class="cfgcmd"> + +set protocols rip timers timeout \<seconds\> + +This command specifies the timeout timer. Upon expiration of the timeout, +the route is no longer valid; however, it is retained in the routing table +for a short time so that neighbors can be notified that the route has been +dropped. The time range is 5 to 2147483647. The default value is 180 +seconds. + +</div> + +<div class="cfgcmd"> + +set protocols rip timers garbage-collection \<seconds\> + +This command specifies the garbage-collection timer. Upon expiration of +the garbage-collection timer, the route is finally removed from the +routing table. The time range is 5 to 2147483647. The default value is 120 +seconds. + +</div> + +## Redistribution Configuration + +<div class="cfgcmd"> + +set protocols rip redistribute \<route source\> + +This command redistributes routing information from the given route source +into the RIP tables. There are five modes available for route source: bgp, +connected, kernel, ospf, static. + +</div> + +<div class="cfgcmd"> + +set protocols rip redistribute \<route source\> metric \<metric\> + +This command specifies metric for redistributed routes from the given route +source. There are five modes available for route source: bgp, connected, +kernel, ospf, static. The metric range is 1 to 16. + +</div> + +<div class="cfgcmd"> + +set protocols rip redistribute \<route source\> route-map \<name\> + +This command allows to use route map to filter redistributed routes from +the given route source. There are five modes available for route source: +bgp, connected, kernel, ospf, static. + +</div> + +<div class="cfgcmd"> + +set protocols rip default-metric \<metric\> + +This command modifies the default metric (hop count) value for redistributed +routes. The metric range is 1 to 16. The default value is 1. This command +does not affect connected route even if it is redistributed by +`redistribute connected`. To modify connected routes metric +value, please use `redistribute connected metric`. + +</div> + +## Interfaces Configuration + +<div class="cfgcmd"> + +set interfaces \<inttype\> \<intname\> ip rip authentication plaintext-password \<text\> + +This command sets the interface with RIP simple password authentication. +This command also sets authentication string. The string must be shorter +than 16 characters. + +</div> + +<div class="cfgcmd"> + +set interfaces \<inttype\> \<intname\> ip rip authentication md5 \<id\> password \<text\> + +This command sets the interface with RIP MD5 authentication. This command +also sets MD5 Key. The key must be shorter than 16 characters. + +</div> + +<div class="cfgcmd"> + +set interfaces \<inttype\> \<intname\> ip rip split-horizon disable + +This command disables split-horizon on the interface. By default, VyOS does +not advertise RIP routes out the interface over which they were learned +(split horizon).3 + +</div> + +<div class="cfgcmd"> + +set interfaces \<inttype\> \<intname\> ip rip split-horizon poison-reverse + +This command enables poison-reverse on the interface. If both poison reverse +and split horizon are enabled, then VyOS advertises the learned routes +as unreachable over the interface on which the route was learned. + +</div> + +## Operational Mode Commands + +<div class="opcmd"> + +show ip rip + +This command displays RIP routes. + +</div> + +``` none +Codes: R - RIP, C - connected, S - Static, O - OSPF, B - BGP +Sub-codes: + (n) - normal, (s) - static, (d) - default, (r) - redistribute, + (i) - interface + + Network Next Hop Metric From Tag Time +C(i) 10.0.12.0/24 0.0.0.0 1 self 0 +C(i) 10.0.13.0/24 0.0.0.0 1 self 0 +R(n) 10.0.23.0/24 10.0.12.2 2 10.0.12.2 0 02:53 +``` + +<div class="opcmd"> + +show ip rip status + +The command displays current RIP status. It includes RIP timer, filtering, +version, RIP enabled interface and RIP peer information. + +</div> + +``` none +Routing Protocol is "rip" + Sending updates every 30 seconds with +/-50%, next due in 11 seconds + Timeout after 180 seconds, garbage collect after 120 seconds + Outgoing update filter list for all interface is not set + Incoming update filter list for all interface is not set + Default redistribution metric is 1 + Redistributing: + Default version control: send version 2, receive any version + Interface Send Recv Key-chain + eth0 2 1 2 + eth2 2 1 2 + Routing for Networks: + 10.0.12.0/24 + eth0 + Routing Information Sources: + Gateway BadPackets BadRoutes Distance Last Update + 10.0.12.2 0 0 120 00:00:11 + Distance: (default is 120) +``` + +## Configuration Example + +Simple RIP configuration using 2 nodes and redistributing connected interfaces. + +**Node 1:** + +``` none +set interfaces loopback address 10.1.1.1/32 +set protocols rip network 192.168.0.0/24 +set protocols rip redistribute connected +``` + +**Node 2:** + +``` none +set interfaces loopback address 10.2.2.2/32 +set protocols rip network 192.168.0.0/24 +set protocols rip redistribute connected +``` diff --git a/docs/configuration/protocols/md-rpki.md b/docs/configuration/protocols/md-rpki.md new file mode 100644 index 00000000..f41e4d59 --- /dev/null +++ b/docs/configuration/protocols/md-rpki.md @@ -0,0 +1,238 @@ +# RPKI + +> There are two types of Network Admins who deal with BGP, those who have +> created an international incident and/or outage, and those who are lying +> +> -- [tweet by EvilMog](https://twitter.com/Evil_Mog/status/1230924170508169216), 2020-02-21 + +`RPKI (Resource Public Key Infrastructure)` is a framework designed to +secure the Internet routing infrastructure. It associates BGP route +announcements with the correct originating `ASN (Autonomus System +Number)` which BGP routers can then use to check each route against the +corresponding `ROA (Route Origin Authorisation)` for validity. RPKI is +described in `6480`. + +A BGP-speaking router like VyOS can retrieve ROA information from RPKI +"Relying Party software" (often just called an "RPKI server" or "RPKI +validator") by using `RTR (RPKI to Router)` protocol. There are several +open source implementations to choose from, such as NLNetLabs' [Routinator](https://www.nlnetlabs.nl/projects/rpki/routinator/) +(written in Rust), OpenBSD's [rpki-client](https://www.rpki-client.org/) (written in C), and [StayRTR](https://github.com/bgp/stayrtr/) (written +in Go). The RTR protocol is described in `8210`. + +<div class="tip"> + +<div class="title"> + +Tip + +</div> + +If you are new to these routing security technologies then there is an +[excellent guide to RPKI](https://rpki.readthedocs.io/) by NLnet Labs which will get you up to speed +very quickly. Their documentation explains everything from what RPKI is to +deploying it in production. It also has some +[help and operational guidance](https://rpki.readthedocs.io/en/latest/about/help.html) including "What can I do about my route +having an Invalid state?" + +</div> + +## Getting started + +First you will need to deploy an RPKI validator for your routers to use. NLnet +Labs provides a collection of [software](https://rpki.readthedocs.io/en/latest/ops/tools.html#relying-party-software) you can compare and settle on one. +Once your server is running you can start validating announcements. + +Imported prefixes during the validation may have values: + +> valid +> The prefix and ASN that originated it match a signed ROA. These are +> probably trustworthy route announcements. +> +> invalid +> The prefix or prefix length and ASN that originated it doesn't +> match any existing ROA. This could be the result of a prefix hijack, or +> merely a misconfiguration, but should probably be treated as +> untrustworthy route announcements. +> +> notfound +> No ROA exists which covers that prefix. Unfortunately this is the case for +> about 40%-50% of the prefixes which were announced to the `DFZ +> (default-free zone)` at the start of 2024. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you are responsible for the global addresses assigned to your +network, please make sure that your prefixes have ROAs associated with them +to avoid being <span class="title-ref">notfound</span> by RPKI. For most ASNs this will involve +publishing ROAs via your `RIR (Regional Internet Registry)` (RIPE +NCC, APNIC, ARIN, LACNIC, or AFRINIC), and is something you are encouraged +to do whenever you plan to announce addresses into the DFZ. + +Particularly large networks may wish to run their own RPKI certificate +authority and publication server instead of publishing ROAs via their RIR. +This is a subject far beyond the scope of VyOS' documentation. Consider +reading about [Krill](https://www.nlnetlabs.nl/projects/rpki/krill/) if this is a rabbit hole you need or especially want +to dive down. + +</div> + +### Features of the Current Implementation + +In a nutshell, the current implementation provides the following features: + +- The BGP router can connect to one or more RPKI cache servers to receive + validated prefix to origin AS mappings. Advanced failover can be implemented + by server sockets with different preference values. +- If no connection to an RPKI cache server can be established after a + pre-defined timeout, the router will process routes without prefix origin + validation. It still will try to establish a connection to an RPKI cache + server in the background. +- By default, enabling RPKI does not change best path selection. In particular, + invalid prefixes will still be considered during best path selection. However, + the router can be configured to ignore all invalid prefixes. +- Route maps can be configured to match a specific RPKI validation state. This + allows the creation of local policies, which handle BGP routes based on the + outcome of the Prefix Origin Validation. +- Updates from the RPKI cache servers are directly applied and path selection is + updated accordingly. (Soft reconfiguration must be enabled for this to work). + +## Configuration + +<div class="cfgcmd"> + +set protocols rpki polling-period \<1-86400\> + +Define the time interval to update the local cache + +The default value is 300 seconds. + +</div> + +<div class="cfgcmd"> + +set protocols rpki expire-interval \<600-172800\> + +Set the number of seconds the router waits until the router +expires the cache. + +The default value is 7200 seconds. + +</div> + +<div class="cfgcmd"> + +set protocols rpki retry-interval \<1-7200\> + +Set the number of seconds the router waits until retrying to connect +to the cache server. + +The default value is 600 seconds. + +</div> + +<div class="cfgcmd"> + +set protocols rpki cache \<address\> port \<port\> + +Defined the IPv4, IPv6 or FQDN and port number of the caching RPKI caching +instance which is used. + +This is a mandatory setting. + +</div> + +<div class="cfgcmd"> + +set protocols rpki cache \<address\> preference \<preference\> + +Multiple RPKI caching instances can be supplied and they need a preference in +which their result sets are used. + +This is a mandatory setting. + +</div> + +### SSH + +Connections to the RPKI caching server can not only be established by TCP using +the RTR protocol but you can also rely on a secure SSH session to the server. +This provides transport integrity and confidentiality and it is a good idea if +your validation software supports it. To enable SSH, first you need to create +an SSH client keypair using `generate ssh client-key /config/auth/id_rsa_rpki`. Once your key is created you can setup the +connection. + +<div class="cfgcmd"> + +set protocols rpki cache \<address\> ssh username \<user\> + +SSH username to establish an SSH connection to the cache server. + +</div> + +<div class="cfgcmd"> + +set protocols rpki cache \<address\> ssh private-key-file \<filepath\> + +Local path that includes the private key file of the router. + +</div> + +<div class="cfgcmd"> + +set protocols rpki cache \<address\> ssh public-key-file \<filepath\> + +Local path that includes the public key file of the router. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +When using SSH, private-key-file and public-key-file +are mandatory options. + +</div> + +## Example + +We can build route-maps for import based on these states. Here is a simple +RPKI configuration, where <span class="title-ref">routinator</span> is the RPKI-validating "cache" +server with ip \`192.0.2.1\`: + +``` none +set protocols rpki cache 192.0.2.1 port '3323' +set protocols rpki cache 192.0.2.1 preference '1' +``` + +Here is an example route-map to apply to routes learned at import. In this +filter we reject prefixes with the state <span class="title-ref">invalid</span>, and set a higher +<span class="title-ref">local-preference</span> if the prefix is RPKI <span class="title-ref">valid</span> rather than merely +<span class="title-ref">notfound</span>. + +``` none +set policy route-map ROUTES-IN rule 10 action 'permit' +set policy route-map ROUTES-IN rule 10 match rpki 'valid' +set policy route-map ROUTES-IN rule 10 set local-preference '300' +set policy route-map ROUTES-IN rule 20 action 'permit' +set policy route-map ROUTES-IN rule 20 match rpki 'notfound' +set policy route-map ROUTES-IN rule 20 set local-preference '125' +set policy route-map ROUTES-IN rule 30 action 'deny' +set policy route-map ROUTES-IN rule 30 match rpki 'invalid' +``` + +Once your routers are configured to reject RPKI-invalid prefixes, you can +test whether the configuration is working correctly using Cloudflare's [test](https://isbgpsafeyet.com/) +website. Keep in mind that in order for this to work, you need to have no +default routes or anything else that would still send traffic to RPKI-invalid +destinations. diff --git a/docs/configuration/protocols/md-segment-routing.md b/docs/configuration/protocols/md-segment-routing.md new file mode 100644 index 00000000..24516103 --- /dev/null +++ b/docs/configuration/protocols/md-segment-routing.md @@ -0,0 +1,442 @@ +# Segment Routing + +Segment Routing (SR) is a network architecture that is similar to source-routing +. In this architecture, the ingress router adds a list of segments, known as +SIDs, to the packet as it enters the network. These segments represent different +portions of the network path that the packet will take. + +The SR segments are portions of the network path taken by the packet, and are +called SIDs. At each node, the first SID of the list is read, executed as a +forwarding function, and may be popped to let the next node read the next SID of +the list. The SID list completely determines the path where the packet is +forwarded. + +Segment Routing can be applied to an existing MPLS-based data plane and defines +a control plane network architecture. In MPLS networks, segments are encoded as +MPLS labels and are added at the ingress router. These MPLS labels are then +exchanged and populated by Interior Gateway Protocols (IGPs) like IS-IS or OSPF +which are running on most ISPs. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Segment routing defines a control plane network architecture and +can be applied to an existing MPLS based dataplane. In the MPLS networks, +segments are encoded as MPLS labels and are imposed at the ingress router. +MPLS labels are exchanged and populated by IGPs like IS-IS.Segment Routing +as per RFC8667 for MPLS dataplane. It supports IPv4, IPv6 and ECMP and has +been tested against Cisco & Juniper routers.however,this deployment is still +EXPERIMENTAL for FRR. + +</div> + +## IS-IS SR Configuration + +Segment routing (SR) is used by the IGP protocols to interconnect network +devices, below configuration shows how to enable SR on IS-IS: + +<div class="note"> + +<div class="title"> + +Note + +</div> + +`Known limitations:` + +No support for level redistribution (L1 to L2 or L2 to L1) + +No support for binding SID + +No support for SRLB + +Only one SRGB and default SPF Algorithm is supported + +</div> + +<div class="cfgcmd"> + +set protocols isis segment-routing global-block high-label-value +\<label-value\> + +Set the Segment Routing Global Block i.e. the label range used by MPLS to +store label in the MPLS FIB for Prefix SID. Note that the block size may +not exceed 65535. + +</div> + +<div class="cfgcmd"> + +set protocols isis segment-routing global-block low-label-value +\<label-value\> + +Set the Segment Routing Global Block i.e. the low label range used by MPLS to +store label in the MPLS FIB for Prefix SID. Note that the block size may +not exceed 65535. + +</div> + +<div class="cfgcmd"> + +set protocols isis segment-routing local-block high-label-value +\<label-value\> + +Set the Segment Routing Local Block i.e. the label range used by MPLS to +store label in the MPLS FIB for Prefix SID. Note that the block size may +not exceed 65535.Segment Routing Local Block, The negative command always +unsets both. + +</div> + +<div class="cfgcmd"> + +set protocols isis segment-routing local-block \<low-label-value +\<label-value\> + +Set the Segment Routing Local Block i.e. the low label range used by MPLS to +store label in the MPLS FIB for Prefix SID. Note that the block size may +not exceed 65535.Segment Routing Local Block, The negative command always +unsets both. + +</div> + +<div class="cfgcmd"> + +set protocols isis segment-routing maximum-label-depth \<1-16\> + +Set the Maximum Stack Depth supported by the router. The value depend of +the MPLS dataplane. + +</div> + +<div class="cfgcmd"> + +set protocols isis segment-routing prefix \<address\> index value +\<0-65535\> + +A segment ID that contains an IP address prefix calculated by an IGP in the +service provider core network. Prefix SIDs are globally unique, this value +indentify it + +</div> + +<div class="cfgcmd"> + +set protocols isis segment-routing prefix \<address\> index +\<no-php-flag | explicit-null| n-flag-clear\> + +this option allows to configure prefix-sid on SR. The ‘no-php-flag’ means NO +Penultimate Hop Popping that allows SR node to request to its neighbor to +not pop the label. The ‘explicit-null’ flag allows SR node to request to its +neighbor to send IP packet with the EXPLICIT-NULL label. The ‘n-flag-clear’ +option can be used to explicitly clear the Node flag that is set by default +for Prefix-SIDs associated to loopback addresses. This option is necessary +to configure Anycast-SIDs. + +</div> + +<div class="opcmd"> + +show isis segment-routing node + +Show detailed information about all learned Segment Routing Nodes + +</div> + +<div class="opcmd"> + +show isis route prefix-sid + +Show detailed information about prefix-sid and label learned + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +more information related IGP - `routing-isis` + +</div> + +## OSPF SR Configuration + +Segment routing (SR) is used by the IGP protocols to interconnect network +devices, below configuration shows how to enable SR on OSPF: + +<div class="cfgcmd"> + +set protocols ospf parameters opaque-lsa + +Enable the Opaque-LSA capability (rfc2370), necessary to transport label +on IGP + +</div> + +<div class="cfgcmd"> + +set protocols ospf segment-routing global-block high-label-value +\<label-value\> + +Set the Segment Routing Global Block i.e. the label range used by MPLS to +store label in the MPLS FIB for Prefix SID. Note that the block size may +not exceed 65535. + +</div> + +<div class="cfgcmd"> + +set protocols ospf segment-routing global-block low-label-value +\<label-value\> + +Set the Segment Routing Global Block i.e. the low label range used by MPLS to +store label in the MPLS FIB for Prefix SID. Note that the block size may +not exceed 65535. + +</div> + +<div class="cfgcmd"> + +set protocols ospf segment-routing local-block high-label-value +\<label-value\> + +Set the Segment Routing Local Block i.e. the label range used by MPLS to +store label in the MPLS FIB for Prefix SID. Note that the block size may +not exceed 65535.Segment Routing Local Block, The negative command always +unsets both. + +</div> + +<div class="cfgcmd"> + +set protocols ospf segment-routing local-block \<low-label-value +\<label-value\> + +Set the Segment Routing Local Block i.e. the low label range used by MPLS to +store label in the MPLS FIB for Prefix SID. Note that the block size may +not exceed 65535.Segment Routing Local Block, The negative command always +unsets both. + +</div> + +<div class="cfgcmd"> + +set protocols ospf segment-routing maximum-label-depth \<1-16\> + +Set the Maximum Stack Depth supported by the router. The value depend of +the MPLS dataplane. + +</div> + +<div class="cfgcmd"> + +set protocols ospf segment-routing prefix \<address\> index value +\<0-65535\> + +A segment ID that contains an IP address prefix calculated by an IGP in the +service provider core network. Prefix SIDs are globally unique, this value +indentify it + +</div> + +<div class="cfgcmd"> + +set protocols ospf segment-routing prefix \<address\> index +\<no-php-flag | explicit-null| n-flag-clear\> + +this option allows to configure prefix-sid on SR. The ‘no-php-flag’ means NO +Penultimate Hop Popping that allows SR node to request to its neighbor to +not pop the label. The ‘explicit-null’ flag allows SR node to request to its +neighbor to send IP packet with the EXPLICIT-NULL label. The ‘n-flag-clear’ +option can be used to explicitly clear the Node flag that is set by default +for Prefix-SIDs associated to loopback addresses. This option is necessary +to configure Anycast-SIDs. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +more information related IGP - `routing-ospf` + +</div> + +## Configuration Example + +we described the configuration SR ISIS / SR OSPF using 2 connected with them to +share label information. + +### Enable IS-IS with Segment Routing (Experimental) + +**Node 1:** + +``` none +set interfaces loopback lo address '192.168.255.255/32' +set interfaces ethernet eth1 address '192.0.2.1/24' + +set protocols isis interface eth1 +set protocols isis interface lo +set protocols isis net '49.0001.1921.6825.5255.00' +set protocols isis segment-routing global-block high-label-value '599' +set protocols isis segment-routing global-block low-label-value '550' +set protocols isis segment-routing prefix 192.168.255.255/32 index value '1' +set protocols isis segment-routing prefix 192.168.255.255/32 index explicit-null +set protocols mpls interface 'eth1' +``` + +**Node 2:** + +``` none +set interfaces loopback lo address '192.168.255.254/32' +set interfaces ethernet eth1 address '192.0.2.2/24' + +set protocols isis interface eth1 +set protocols isis interface lo +set protocols isis net '49.0001.1921.6825.5254.00' +set protocols isis segment-routing global-block high-label-value '599' +set protocols isis segment-routing global-block low-label-value '550' +set protocols isis segment-routing prefix 192.168.255.254/32 index value '2' +set protocols isis segment-routing prefix 192.168.255.254/32 index explicit-null +set protocols mpls interface 'eth1' +``` + +This gives us MPLS segment routing enabled and labels for far end loopbacks: + +``` none +Node-1@vyos:~$ show mpls table + Inbound Label Type Nexthop Outbound Label + ---------------------------------------------------------------------- + 552 SR (IS-IS) 192.0.2.2 IPv4 Explicit Null <-- Node-2 loopback learned on Node-1 + 15000 SR (IS-IS) 192.0.2.2 implicit-null + 15001 SR (IS-IS) fe80::e87:6cff:fe09:1 implicit-null + 15002 SR (IS-IS) 192.0.2.2 implicit-null + 15003 SR (IS-IS) fe80::e87:6cff:fe09:1 implicit-null + +Node-2@vyos:~$ show mpls table + Inbound Label Type Nexthop Outbound Label + --------------------------------------------------------------------- + 551 SR (IS-IS) 192.0.2.1 IPv4 Explicit Null <-- Node-1 loopback learned on Node-2 + 15000 SR (IS-IS) 192.0.2.1 implicit-null + 15001 SR (IS-IS) fe80::e33:2ff:fe80:1 implicit-null + 15002 SR (IS-IS) 192.0.2.1 implicit-null + 15003 SR (IS-IS) fe80::e33:2ff:fe80:1 implicit-null +``` + +Here is the routing tables showing the MPLS segment routing label operations: + +``` none +Node-1@vyos:~$ show ip route isis +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +I 192.0.2.0/24 [115/20] via 192.0.2.2, eth1 inactive, weight 1, 00:07:48 +I>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1, label IPv4 Explicit Null, weight 1, 00:03:39 + +Node-2@vyos:~$ show ip route isis +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +I 192.0.2.0/24 [115/20] via 192.0.2.1, eth1 inactive, weight 1, 00:07:46 +I>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1, label IPv4 Explicit Null, weight 1, 00:03:43 +``` + +### Enable OSPF with Segment Routing (Experimental): + +**Node 1** + +``` none +set interfaces loopback lo address 10.1.1.1/32 +set interfaces ethernet eth0 address 192.168.0.1/24 +set protocols ospf area 0 network '192.168.0.0/24' +set protocols ospf area 0 network '10.1.1.1/32' +set protocols ospf parameters opaque-lsa +set protocols ospf parameters router-id '10.1.1.1' +set protocols ospf segment-routing global-block high-label-value '1100' +set protocols ospf segment-routing global-block low-label-value '1000' +set protocols ospf segment-routing prefix 10.1.1.1/32 index explicit-null +set protocols ospf segment-routing prefix 10.1.1.1/32 index value '1' +``` + +**Node 2** + +``` none +set interfaces loopback lo address 10.1.1.2/32 +set interfaces ethernet eth0 address 192.168.0.2/24 +set protocols ospf area 0 network '192.168.0.0/24' +set protocols ospf area 0 network '10.1.1.2/32' +set protocols ospf parameters opaque-lsa +set protocols ospf parameters router-id '10.1.1.2' +set protocols ospf segment-routing global-block high-label-value '1100' +set protocols ospf segment-routing global-block low-label-value '1000' +set protocols ospf segment-routing prefix 10.1.1.2/32 index explicit-null +set protocols ospf segment-routing prefix 10.1.1.2/32 index value '2' +``` + +This gives us MPLS segment routing enabled and labels for far end loopbacks: + +``` none +Node-1@vyos:~$ show mpls table + Inbound Label Type Nexthop Outbound Label + ----------------------------------------------------------- + 1002 SR (OSPF) 192.168.0.2 IPv4 Explicit Null <-- Node-2 loopback learned on Node-1 + 15000 SR (OSPF) 192.168.0.2 implicit-null + 15001 SR (OSPF) 192.168.0.2 implicit-null + +Node-2@vyos:~$ show mpls table + Inbound Label Type Nexthop Outbound Label + ----------------------------------------------------------- + 1001 SR (OSPF) 192.168.0.1 IPv4 Explicit Null <-- Node-1 loopback learned on Node-2 + 15000 SR (OSPF) 192.168.0.1 implicit-null + 15001 SR (OSPF) 192.168.0.1 implicit-null +``` + +Here is the routing tables showing the MPLS segment routing label operations: + +``` none +Node-1@vyos:~$ show ip route ospf +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +O 10.1.1.1/32 [110/0] is directly connected, lo, weight 1, 00:03:43 +O>* 10.1.1.2/32 [110/1] via 192.168.0.2, eth0, label IPv4 Explicit Null, weight 1, 00:03:32 +O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:43 + +Node-2@vyos:~$ show ip route ospf +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +O>* 10.1.1.1/32 [110/1] via 192.168.0.1, eth0, label IPv4 Explicit Null, weight 1, 00:03:36 +O 10.1.1.2/32 [110/0] is directly connected, lo, weight 1, 00:03:51 +O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:51 +``` diff --git a/docs/configuration/protocols/md-static.md b/docs/configuration/protocols/md-static.md new file mode 100644 index 00000000..dca76d53 --- /dev/null +++ b/docs/configuration/protocols/md-static.md @@ -0,0 +1,322 @@ +# Static + +Static routes are manually configured routes, which, in general, cannot be +updated dynamically from information VyOS learns about the network topology from +other routing protocols. However, if a link fails, the router will remove +routes, including static routes, from the `RIPB (Routing Information +Base)` that used this interface to reach the next hop. In general, static +routes should only be used for very simple network topologies, or to override +the behavior of a dynamic routing protocol for a small number of routes. The +collection of all routes the router has learned from its configuration or from +its dynamic routing protocols is stored in the RIB. Unicast routes are directly +used to determine the forwarding table used for unicast packet forwarding. + +## Static Routes + +<div class="cfgcmd"> + +set protocols static route \<subnet\> next-hop \<address\> + +Configure next-hop <span class="title-ref">\<address\></span> for an IPv4 static route. Multiple static +routes can be created. + +</div> + +<div class="cfgcmd"> + +set protocols static route \<subnet\> next-hop \<address\> disable + +Disable this IPv4 static route entry. + +</div> + +<div class="cfgcmd"> + +set protocols static route \<subnet\> next-hop \<address\> +distance \<distance\> + +Defines next-hop distance for this route, routes with smaller administrative +distance are elected prior to those with a higher distance. + +Range is 1 to 255, default is 1. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Routes with a distance of 255 are effectively disabled and not +installed into the kernel. + +</div> + +</div> + +<div class="cfgcmd"> + +set protocols static route6 \<subnet\> next-hop \<address\> + +Configure next-hop <span class="title-ref">\<address\></span> for an IPv6 static route. Multiple static +routes can be created. + +</div> + +<div class="cfgcmd"> + +set protocols static route6 \<subnet\> next-hop \<address\> disable + +Disable this IPv6 static route entry. + +</div> + +<div class="cfgcmd"> + +set protocols static route6 \<subnet\> next-hop \<address\> +distance \<distance\> + +Defines next-hop distance for this route, routes with smaller administrative +distance are elected prior to those with a higher distance. + +Range is 1 to 255, default is 1. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Routes with a distance of 255 are effectively disabled and not +installed into the kernel. + +</div> + +</div> + +<div class="cfgcmd"> + +set protocols static route6 \<subnet\> next-hop \<address\> segments \<segments\> + +It is possible to specify a static route for ipv6 prefixes using an SRv6 segments +instruction. The <span class="title-ref">/</span> separator can be used to specify multiple segment instructions. + +Example: + +``` none +set protocols static route6 2001:db8:1000::/36 next-hop 2001:db8:201::ffff segments '2001:db8:aaaa::7/2002::4/2002::3/2002::2' +``` + +``` none +vyos@vyos:~$ show ipv6 route +Codes: K - kernel route, C - connected, S - static, R - RIPng, + O - OSPFv3, I - IS-IS, B - BGP, N - NHRP, T - Table, + v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure +C>* 2001:db8:201::/64 is directly connected, eth0.201, 00:00:46 +S>* 2001:db8:1000::/36 [1/0] via 2001:db8:201::ffff, eth0.201, seg6 2001:db8:aaaa::7,2002::4,2002::3,2002::2, weight 1, 00:00:08 +``` + +</div> + +### Interface Routes + +<div class="cfgcmd"> + +set protocols static route \<subnet\> interface +\<interface\> + +Allows you to configure the next-hop interface for an interface-based IPv4 +static route. <span class="title-ref">\<interface\></span> will be the next-hop interface where traffic is +routed for the given <span class="title-ref">\<subnet\></span>. + +</div> + +<div class="cfgcmd"> + +set protocols static route \<subnet\> interface +\<interface\> disable + +Disables interface-based IPv4 static route. + +</div> + +<div class="cfgcmd"> + +set protocols static route \<subnet\> interface +\<interface\> distance \<distance\> + +Defines next-hop distance for this route, routes with smaller administrative +distance are elected prior to those with a higher distance. + +Range is 1 to 255, default is 1. + +</div> + +<div class="cfgcmd"> + +set protocols static route6 \<subnet\> interface +\<interface\> + +Allows you to configure the next-hop interface for an interface-based IPv6 +static route. <span class="title-ref">\<interface\></span> will be the next-hop interface where traffic is +routed for the given <span class="title-ref">\<subnet\></span>. + +</div> + +<div class="cfgcmd"> + +set protocols static route6 \<subnet\> interface +\<interface\> disable + +Disables interface-based IPv6 static route. + +</div> + +<div class="cfgcmd"> + +set protocols static route6 \<subnet\> interface +\<interface\> distance \<distance\> + +Defines next-hop distance for this route, routes with smaller administrative +distance are elected prior to those with a higher distance. + +Range is 1 to 255, default is 1. + +</div> + +<div class="cfgcmd"> + +set protocols static route6 \<subnet\> interface +\<interface\> segments \<segments\> + +It is possible to specify a static route for ipv6 prefixes using an SRv6 segments +instruction. The <span class="title-ref">/</span> separator can be used to specify multiple segment instructions. + +Example: + +``` none +set protocols static route6 2001:db8:1000::/36 interface eth0 segments '2001:db8:aaaa::7/2002::4/2002::3/2002::2' +``` + +</div> + +### Blackhole + +<div class="cfgcmd"> + +set protocols static route \<subnet\> blackhole + +Use this command to configure a "black-hole" route on the router. A +black-hole route is a route for which the system silently discard packets +that are matched. This prevents networks leaking out public interfaces, but +it does not prevent them from being used as a more specific route inside your +network. + +</div> + +<div class="cfgcmd"> + +set protocols static route \<subnet\> blackhole distance \<distance\> + +Defines blackhole distance for this route, routes with smaller administrative +distance are elected prior to those with a higher distance. + +</div> + +<div class="cfgcmd"> + +set protocols static route6 \<subnet\> blackhole + +Use this command to configure a "black-hole" route on the router. A +black-hole route is a route for which the system silently discard packets +that are matched. This prevents networks leaking out public interfaces, but +it does not prevent them from being used as a more specific route inside your +network. + +</div> + +<div class="cfgcmd"> + +set protocols static route6 \<subnet\> blackhole distance \<distance\> + +Defines blackhole distance for this route, routes with smaller administrative +distance are elected prior to those with a higher distance. + +</div> + +### Alternate Routing Tables + +TBD + +Alternate routing tables are used with policy based routing by utilizing +`vrf`. + +# ARP + +`ARP (Address Resolution Protocol)` is a communication protocol used for +discovering the link layer address, such as a MAC address, associated with a +given internet layer address, typically an IPv4 address. This mapping is a +critical function in the Internet protocol suite. ARP was defined in 1982 by +`826` which is Internet Standard STD 37. + +In Internet Protocol Version 6 (IPv6) networks, the functionality of ARP is +provided by the Neighbor Discovery Protocol (NDP). + +To manipulate or display [ARP](https://en.wikipedia.org/wiki/Address_Resolution_Protocol) table entries, the following commands are +implemented. + +## Configure + +<div class="cfgcmd"> + +set protocols static arp interface \<interface\> address \<host\> +mac \<mac\> + +This will configure a static ARP entry always resolving <span class="title-ref">\<address\></span> to +<span class="title-ref">\<mac\></span> for interface <span class="title-ref">\<interface\></span>. + +Example: + +``` none +set protocols static arp interface eth0 address 192.0.2.1 mac 01:23:45:67:89:01 +``` + +</div> + +## Operation + +<div class="opcmd"> + +show protocols static arp + +Display all known ARP table entries spanning across all interfaces + +</div> + +``` none +vyos@vyos:~$ show protocols static arp +Address HWtype HWaddress Flags Mask Iface +10.1.1.1 ether 00:53:00:de:23:2e C eth1 +10.1.1.100 ether 00:53:00:de:23:aa CM eth1 +``` + +<div class="opcmd"> + +show protocols static arp interface eth1 + +Display all known ARP table entries on a given interface only (<span class="title-ref">eth1</span>): + +</div> + +``` none +vyos@vyos:~$ show protocols static arp interface eth1 +Address HWtype HWaddress Flags Mask Iface +10.1.1.1 ether 00:53:00:de:23:2e C eth1 +10.1.1.100 ether 00:53:00:de:23:aa CM eth1 +``` diff --git a/docs/configuration/service/md-broadcast-relay.md b/docs/configuration/service/md-broadcast-relay.md new file mode 100644 index 00000000..2214ade3 --- /dev/null +++ b/docs/configuration/service/md-broadcast-relay.md @@ -0,0 +1,94 @@ +# UDP Broadcast Relay + +Certain vendors use broadcasts to identify their equipment within one ethernet +segment. Unfortunately if you split your network with multiple VLANs you loose +the ability of identifying your equipment. + +This is where "UDP broadcast relay" comes into play! It will forward received +broadcasts to other configured networks. + +Every UDP port which will be forward requires one unique ID. Currently we +support 99 IDs! + +## Configuration + +<div class="cfgcmd"> + +set service broadcast-relay id \<n\> description \<description\> + +A description can be added for each and every unique relay ID. This is +useful to distinguish between multiple different ports/appliactions. + +</div> + +<div class="cfgcmd"> + +set service broadcast-relay id \<n\> interface \<interface\> + +The interface used to receive and relay individual broadcast packets. If you +want to receive/relay packets on both <span class="title-ref">eth1</span> and <span class="title-ref">eth2</span> both interfaces need +to be added. + +</div> + +<div class="cfgcmd"> + +set service broadcast-relay id \<n\> address \<ipv4-address\> + +Set the source IP of forwarded packets, otherwise original senders address +is used. + +</div> + +<div class="cfgcmd"> + +set service broadcast-relay id \<n\> port \<port\> + +The UDP port number used by your apllication. It is mandatory for this kind +of operation. + +</div> + +<div class="cfgcmd"> + +set service broadcast-relay id \<n\> disable + +Each broadcast relay instance can be individually disabled without deleting +the configured node by using the following command: + +</div> + +<div class="cfgcmd"> + +set service broadcast-relay disable + +In addition you can also disable the whole service without the need to remove +it from the current configuration. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +You can run the UDP broadcast relay service on multiple routers +connected to a subnet. There is **NO** UDP broadcast relay packet storm! + +</div> + +## Example + +To forward all broadcast packets received on <span class="title-ref">UDP port 1900</span> on <span class="title-ref">eth3</span>, <span class="title-ref">eth4</span> +or <span class="title-ref">eth5</span> to all other interfaces in this configuration. + +``` none +set service broadcast-relay id 1 description 'SONOS' +set service broadcast-relay id 1 interface 'eth3' +set service broadcast-relay id 1 interface 'eth4' +set service broadcast-relay id 1 interface 'eth5' +set service broadcast-relay id 1 port '1900' +``` diff --git a/docs/configuration/service/md-config-sync.md b/docs/configuration/service/md-config-sync.md new file mode 100644 index 00000000..db803cb4 --- /dev/null +++ b/docs/configuration/service/md-config-sync.md @@ -0,0 +1,121 @@ +# Config Sync + +Configuration synchronization (config sync) is a feature of VyOS that +permits synchronization of the configuration of one VyOS router to +another in a network. + +The main benefit to configuration synchronization is that it eliminates having +to manually replicate configuration changes made on the primary router to the +secondary (replica) router. + +The writing of the configuration to the secondary router is performed through +the VyOS HTTP API. The user can specify which portion(s) of the configuration will +be synchronized and the mode to use - whether to replace or add. + +To prevent issues with divergent configurations between the pair of routers, +synchronization is strictly unidirectional from primary to replica. Both +routers should be online and run the same version of VyOS. + +## Configuration + +<div class="cfgcmd"> + +set service config-sync secondary +\<address[|key|](##SUBST##|key|)timeout|port\> + +Specify the address, API key, timeout and port of the secondary router. +You need to enable and configure the HTTP API service on the secondary +router for config sync to operate. + +</div> + +<div class="cfgcmd"> + +set service config-sync section \<section\> + +Specify the section of the configuration to synchronize. If more than one +section is to be synchronized, repeat the command to add additional +sections as required. + +</div> + +<div class="cfgcmd"> + +set service config-sync mode \<load|set\> + +Two options are available for \`mode\`: either <span class="title-ref">load</span> and replace or <span class="title-ref">set</span> +the configuration section. + +</div> + +``` none +Supported options for <section> include: + firewall + interfaces <interface> + nat + nat66 + pki + policy + protocols <protocol> + qos <interface|policy> + service <service> + system <conntrack| + flow-accounting|option|sflow|static-host-mapping|sysctl|time-zone> + vpn + vrf +``` + +## Example + +- Synchronize the time-zone and OSPF configuration from Router A to Router B +- The address of Router B is 10.0.20.112 and the port used is 8443 + +Configure the HTTP API service on Router B + +``` none +set service https listen-address '10.0.20.112' +set service https port '8443' +set service https api keys id KID key 'foo' +``` + +Configure the config-sync service on Router A + +``` none +set service config-sync mode 'load' +set service config-sync secondary address '10.0.20.112' +set service config-sync secondary port '8443' +set service config-sync secondary key 'foo' +set service config-sync section protocols 'ospf' +set service config-sync section system 'time-zone' +``` + +Make config-sync relevant changes to Router A's configuration + +``` none +vyos@vyos-A# set system time-zone 'America/Los_Angeles' +vyos@vyos-A# commit +INFO:vyos_config_sync:Config synchronization: Mode=load, +Secondary=10.0.20.112 +vyos@vyos-A# save + +vyos@vyos-A# set protocols ospf area 0 network '10.0.48.0/30' +vyos@vyos-A# commit +INFO:vyos_config_sync:Config synchronization: Mode=load, +Secondary=10.0.20.112 +yos@vyos-A# save +``` + +Verify configuration changes have been replicated to Router B + +``` none +vyos@vyos-B:~$ show configuration commands | match time-zone +set system time-zone 'America/Los_Angeles' + +vyos@vyos-B:~$ show configuration commands | match ospf +set protocols ospf area 0 network '10.0.48.0/30' +``` + +## Known issues + +Configuration resynchronization. With the current implementation of <span class="title-ref">service +config-sync</span>, the secondary node must be online. diff --git a/docs/configuration/service/md-conntrack-sync.md b/docs/configuration/service/md-conntrack-sync.md new file mode 100644 index 00000000..011080a5 --- /dev/null +++ b/docs/configuration/service/md-conntrack-sync.md @@ -0,0 +1,380 @@ +# Conntrack Sync + +One of the important features built on top of the Netfilter framework is +connection tracking. Connection tracking allows the kernel to keep track of all +logical network connections or sessions, and thereby relate all of the packets +which may make up that connection. NAT relies on this information to translate +all related packets in the same way, and iptables can use this information to +act as a stateful firewall. + +The connection state however is completely independent of any upper-level +state, such as TCP's or SCTP's state. Part of the reason for this is that when +merely forwarding packets, i.e. no local delivery, the TCP engine may not +necessarily be invoked at all. Even connectionless-mode transmissions such as +UDP, IPsec (AH/ESP), GRE and other tunneling protocols have, at least, a pseudo +connection state. The heuristic for such protocols is often based upon a preset +timeout value for inactivity, after whose expiration a Netfilter connection is +dropped. + +Each Netfilter connection is uniquely identified by a (layer-3 protocol, source +address, destination address, layer-4 protocol, layer-4 key) tuple. The layer-4 +key depends on the transport protocol; for TCP/UDP it is the port numbers, for +tunnels it can be their tunnel ID, but otherwise is just zero, as if it were +not part of the tuple. To be able to inspect the TCP port in all cases, packets +will be mandatorily defragmented. + +It is possible to use either Multicast or Unicast to sync conntrack traffic. +Most examples below show Multicast, but unicast can be specified by using the +"peer" keywork after the specificed interface, as in the following example: + +`set service conntrack-sync interface eth0 peer 192.168.0.250` + +## Configuration + +<div class="cfgcmd"> + +set service conntrack-sync accept-protocol + +Accept only certain protocols: You may want to replicate the state of flows +depending on their layer 4 protocol. + +Protocols are: tcp, sctp, dccp, udp, icmp and ipv6-icmp. + +</div> + +<div class="cfgcmd"> + +set service conntrack-sync event-listen-queue-size \<size\> + +The daemon doubles the size of the netlink event socket buffer size if it +detects netlink event message dropping. This clause sets the maximum buffer +size growth that can be reached. + +Queue size for listening to local conntrack events in MB. + +</div> + +<div class="cfgcmd"> + +set service conntrack-sync expect-sync \<all[|ftp|](##SUBST##|ftp|)h323[|nfs|](##SUBST##|nfs|)sip|sqlnet\> + +Protocol for which expect entries need to be synchronized. + +</div> + +<div class="cfgcmd"> + +set service conntrack-sync failover-mechanism vrrp sync-group \<group\> + +Failover mechanism to use for conntrack-sync. + +Only VRRP is supported. Required option. + +</div> + +<div class="cfgcmd"> + +set service conntrack-sync ignore-address \<x.x.x.x\> + +IP addresses or networks for which local conntrack entries will not be synced + +</div> + +<div class="cfgcmd"> + +set service conntrack-sync interface \<name\> + +Interface to use for syncing conntrack entries. + +</div> + +<div class="cfgcmd"> + +set service conntrack-sync interface \<name\> port \<port\> + +Port number used by connection. + +</div> + +<div class="cfgcmd"> + +set service conntrack-sync listen-address \<ipv4address\> + +Local IPv4 addresses for service to listen on. + +</div> + +<div class="cfgcmd"> + +set service conntrack-sync mcast-group \<x.x.x.x\> + +Multicast group to use for syncing conntrack entries. + +Defaults to 225.0.0.50. + +</div> + +<div class="cfgcmd"> + +set service conntrack-sync interface \<name\> peer \<address\> + +Peer to send unicast UDP conntrack sync entires to, if not using Multicast +configuration from above above. + +</div> + +<div class="cfgcmd"> + +set service conntrack-sync sync-queue-size \<size\> + +Queue size for syncing conntrack entries in MB. + +</div> + +<div class="cfgcmd"> + +set service conntrack-sync disable-external-cache + +This diable the external cache and directly injects the flow-states into the +in-kernel Connection Tracking System of the backup firewall. + +</div> + +<div class="cfgcmd"> + +set service conntrack-sync purge-timeout \<timeout\> + +Timeout (in seconds) for purging synchronized entries on handover events. + +On handover, `conntrackd -t` is invoked, which schedules a conntrack table +flush after `<timeout>` seconds to purge stale (“zombie”) entries and +reduce clashes when multiple handovers occur in a short period. +The default is 60 seconds. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +In VRRP stateful firewall deployments, align VRRP timing with this +behavior: because synchronized conntrack state is purged after the purge +timeout, set **VRRP preempt-delay** to ≥ **purge-timeout** so mastership +can be restored before conntrack state is purged. + +</div> + +<div class="cfgcmd"> + +set service conntrack-sync disable-syslog + +Disable connection logging via Syslog. + +</div> + +<div class="cfgcmd"> + +set service conntrack-sync startup-resync + +Order conntrackd to request a complete conntrack table resync against +the other node at startup. + +</div> + +## Operation + +<div class="opcmd"> + +show conntrack table ipv4 + +Make sure conntrack is enabled by running and show connection tracking table. + +``` none +vyos@vyos:~$ show conntrack table ipv4 +TCP state codes: SS - SYN SENT, SR - SYN RECEIVED, ES - ESTABLISHED, + FW - FIN WAIT, CW - CLOSE WAIT, LA - LAST ACK, + TW - TIME WAIT, CL - CLOSE, LI - LISTEN + +CONN ID Source Destination Protocol TIMEOUT +1015736576 10.35.100.87:58172 172.31.20.12:22 tcp [6] ES 430279 +1006235648 10.35.101.221:57483 172.31.120.21:22 tcp [6] ES 413310 +1006237088 10.100.68.100 172.31.120.21 icmp [1] 29 +1015734848 10.35.100.87:56282 172.31.20.12:22 tcp [6] ES 300 +1015734272 172.31.20.12:60286 239.10.10.14:694 udp [17] 29 +1006239392 10.35.101.221 172.31.120.21 icmp [1] 29 +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If the table is empty and you have a warning message, it means +conntrack is not enabled. To enable conntrack, just create a NAT or a firewall +rule. `set firewall state-policy established action accept` + +</div> + +</div> + +<div class="opcmd"> + +show conntrack-sync cache external + +Show connection syncing external cache entries + +</div> + +<div class="opcmd"> + +show conntrack-sync cache internal + +Show connection syncing internal cache entries + +</div> + +<div class="opcmd"> + +show conntrack-sync statistics + +Retrieve current statistics of connection tracking subsystem. + +``` none +vyos@vyos:~$ show conntrack-sync statistics +Main Table Statistics: + +cache internal: +current active connections: 19606 +connections created: 6298470 failed: 0 +connections updated: 3786793 failed: 0 +connections destroyed: 6278864 failed: 0 + +cache external: +current active connections: 15771 +connections created: 1660193 failed: 0 +connections updated: 77204 failed: 0 +connections destroyed: 1644422 failed: 0 + +traffic processed: + 0 Bytes 0 Pckts + +multicast traffic (active device=eth0.5): + 976826240 Bytes sent 212898000 Bytes recv + 8302333 Pckts sent 2009929 Pckts recv + 0 Error send 0 Error recv + +message tracking: + 0 Malformed msgs 263 Lost msgs +``` + +</div> + +<div class="opcmd"> + +show conntrack-sync status + +Retrieve current status of connection tracking subsystem. + +``` none +vyos@vyos:~$ show conntrack-sync status +sync-interface : eth0.5 +failover-mechanism : vrrp [sync-group GEFOEKOM] +last state transition : no transition yet! +ExpectationSync : disabled +``` + +</div> + +## Example + +The next example is a simple configuration of conntrack-sync. + +<figure> +<img src="/_static/images/service_conntrack_sync-schema.webp" alt="Conntrack Sync Example" /> +</figure> + +Now configure conntrack-sync service on `router1` **and** `router2` + +``` none +set high-availablilty vrrp group internal virtual-address ... etc ... +set high-availability vrrp sync-group syncgrp member 'internal' +set service conntrack-sync accept-protocol 'tcp' +set service conntrack-sync accept-protocol 'udp' +set service conntrack-sync accept-protocol 'icmp' +set service conntrack-sync failover-mechanism vrrp sync-group 'syncgrp' +set service conntrack-sync interface 'eth0' +set service conntrack-sync mcast-group '225.0.0.50' +``` + +On the active router, you should have information in the internal-cache of +conntrack-sync. The same current active connections number should be shown in +the external-cache of the standby router + +On active router run: + +``` none +$ show conntrack-sync statistics + +Main Table Statistics: + +cache internal: +current active connections: 10 +connections created: 8517 failed: 0 +connections updated: 127 failed: 0 +connections destroyed: 8507 failed: 0 + +cache external: +current active connections: 0 +connections created: 0 failed: 0 +connections updated: 0 failed: 0 +connections destroyed: 0 failed: 0 + +traffic processed: + 0 Bytes 0 Pckts + +multicast traffic (active device=eth0): + 868780 Bytes sent 224136 Bytes recv + 20595 Pckts sent 14034 Pckts recv + 0 Error send 0 Error recv + +message tracking: + 0 Malformed msgs 0 Lost msgs +``` + +On standby router run: + +``` none +$ show conntrack-sync statistics + +Main Table Statistics: + +cache internal: +current active connections: 0 +connections created: 0 failed: 0 +connections updated: 0 failed: 0 +connections destroyed: 0 failed: 0 + +cache external: +current active connections: 10 +connections created: 888 failed: 0 +connections updated: 134 failed: 0 +connections destroyed: 878 failed: 0 + +traffic processed: + 0 Bytes 0 Pckts + +multicast traffic (active device=eth0): + 234184 Bytes sent 907504 Bytes recv + 14663 Pckts sent 21495 Pckts recv + 0 Error send 0 Error recv + +message tracking: + 0 Malformed msgs 0 Lost msgs +``` diff --git a/docs/configuration/service/md-console-server.md b/docs/configuration/service/md-console-server.md new file mode 100644 index 00000000..2e28b85d --- /dev/null +++ b/docs/configuration/service/md-console-server.md @@ -0,0 +1,206 @@ +# Console Server + +Starting of with VyOS 1.3 (equuleus) we added support for running VyOS as an +Out-of-Band Management device which provides remote access by means of SSH to +directly attached serial interfaces. + +Serial interfaces can be any interface which is directly connected to the CPU +or chipset (mostly known as a ttyS interface in Linux) or any other USB to +serial converter (Prolific PL2303 or FTDI FT232/FT4232 based chips). + +If you happened to use a Cisco NM-16A - Sixteen Port Async Network Module or +NM-32A - Thirty-two Port Async Network Module - this is your VyOS replacement. + +For USB port information please refor to: `hardware_usb`. + +## Configuration + +Between computers, the most common configuration used was "8N1": eight bit +characters, with one start bit, one stop bit, and no parity bit. Thus 10 Baud +times are used to send a single character, and so dividing the signalling +bit-rate by ten results in the overall transmission speed in characters per +second. This is also the default setting if none of those options are defined. + +<div class="cfgcmd"> + +set service console-server device \<device\> data-bits \[7 | 8\] + +Configure either seven or eight data bits. This defaults to eight data +bits if left unconfigured. + +</div> + +<div class="cfgcmd"> + +set service console-server device \<device\> description \<string\> + +A user friendly description identifying the connected peripheral. + +</div> + +<div class="cfgcmd"> + +set service console-server device \<device\> alias \<string\> + +A user friendly alias for this connection. Can be used instead of the +device name when connecting. + +</div> + +<div class="cfgcmd"> + +set service console-server device \<device\> parity \[even | odd | none\] + +Set the parity option for the console. If unset this will default to none. + +</div> + +<div class="cfgcmd"> + +set service console-server device \<device\> stop-bits \[1 | 2\] + +Configure either one or two stop bits. This defaults to one stop bits if +left unconfigured. + +</div> + +<div class="cfgcmd"> + +set service console-server device \<device\> speed +\[ 300 | 1200 | 2400 | 4800 | 9600 | 19200 | 38400 | 57600 | 115200 \] + +<div class="note"> + +<div class="title"> + +Note + +</div> + +USB to serial converters will handle most of their work in software +so you should be carefull with the selected baudrate as some times they +can't cope with the expected speed. + +</div> + +</div> + +### Remote Access + +Each individual configured console-server device can be directly exposed to +the outside world. A user can directly connect via SSH to the configured +port. + +<div class="cfgcmd"> + +set service console-server device \<device\> ssh port \<port\> + +Accept SSH connections for the given <span class="title-ref">\<device\></span> on TCP port <span class="title-ref">\<port\></span>. +After successfull authentication the user will be directly dropped to +the connected serial device. + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +Multiple users can connect to the same serial device but only +one is allowed to write to the console port. + +</div> + +</div> + +## Operation + +<div class="opcmd"> + +show console-server ports + +Show configured serial ports and their respective interface configuration. + +``` none +vyos@vyos:~$ show console-server ports + usb0b2.4p1.0 on /dev/serial/by-bus/usb0b2.4p1.0@ at 9600n +``` + +</div> + +<div class="opcmd"> + +show console-server user + +Show currently connected users. + +``` none +vyos@vyos:~$ show console-server user + usb0b2.4p1.0 up vyos@localhost +``` + +</div> + +<div class="opcmd"> + +connect console \<device\> + +Locally connect to serial port identified by <span class="title-ref">\<device\></span>. + +``` none +vyos@vyos-r1:~$ connect console usb0b2.4p1.0 +[Enter `^Ec?' for help] +[-- MOTD -- VyOS Console Server] + +vyos-r2 login: +``` + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +Multiple users can connect to the same serial device but only +one is allowed to write to the console port. + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +The sequence `^Ec?` translates to: `Ctrl+E c ?`. To quit +the session use: `Ctrl+E c .` + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +If `alias` is set, it can be used instead of the device when +connecting. + +</div> + +</div> + +<div class="opcmd"> + +show log console-server + +Show the console server log. + +</div> diff --git a/docs/configuration/service/md-dhcp-relay.md b/docs/configuration/service/md-dhcp-relay.md new file mode 100644 index 00000000..2cf304bf --- /dev/null +++ b/docs/configuration/service/md-dhcp-relay.md @@ -0,0 +1,242 @@ +# DHCP Relay + +If you want your router to forward DHCP requests to an external DHCP server +you can configure the system to act as a DHCP relay agent. The DHCP relay +agent works with IPv4 and IPv6 addresses. + +All interfaces used for the DHCP relay must be configured. This includes the +uplink to the DHCP server. + +## IPv4 relay + +### Configuration + +<div class="cfgcmd"> + +set service dhcp-relay interface \<interface\> + +Interfaces that participate in the DHCP relay process. If this command is +used, at least two entries of it are required: one for the interface that +captures the dhcp-requests, and one for the interface to forward such +requests. A warning message will be shown if this command is used, since +new implementations should use `listen-interface` and +`upstream-interface`. + +</div> + +<div class="cfgcmd"> + +set service dhcp-relay listen-interface \<interface\> + +Interface for DHCP Relay Agent to listen for requests. + +</div> + +<div class="cfgcmd"> + +set service dhcp-relay upstream-interface \<interface\> + +Interface for DHCP Relay Agent to forward requests out. + +</div> + +<div class="cfgcmd"> + +set service dhcp-relay server \<server\> + +Configure IP address of the DHCP <span class="title-ref">\<server\></span> which will handle the relayed +packets. + +</div> + +<div class="cfgcmd"> + +set service dhcp-relay relay-options relay-agents-packets discard + +The router should discard DHCP packages already containing relay agent +information to ensure that only requests from DHCP clients are forwarded. + +</div> + +<div class="cfgcmd"> + +set service dhcp-relay disable + +Disable dhcp-relay service. + +</div> + +#### Options + +<div class="cfgcmd"> + +set service dhcp-relay relay-options hop-count \<count\> + +Set the maximum hop <span class="title-ref">\<count\></span> before packets are discarded. Range 0...255, +default 10. + +</div> + +<div class="cfgcmd"> + +set service dhcp-relay relay-options max-size \<size\> + +Set maximum <span class="title-ref">\<size\></span> of DHCP packets including relay agent information. If a +DHCP packet size surpasses this value it will be forwarded without appending +relay agent information. Range 64...1400, default 576. + +</div> + +<div class="cfgcmd"> + +set service dhcp-relay relay-options relay-agents-packets +\<append | discard | forward | replace\> + +Four policies for reforwarding DHCP packets exist: + +- **append:** The relay agent is allowed to append its own relay information + to a received DHCP packet, disregarding relay information already present + in the packet. +- **discard:** Received packets which already contain relay information will + be discarded. +- **forward:** All packets are forwarded, relay information already present + will be ignored. +- **replace:** Relay information already present in a packet is stripped and + replaced with the router's own relay information set. + +</div> + +### Example + +- Listen for DHCP requests on interface `eth1`. +- DHCP server is located at IPv4 address 10.0.1.4 on `eth2`. +- Router receives DHCP client requests on `eth1` and relays them to the + server at 10.0.1.4 on `eth2`. + +<figure> +<img src="/_static/images/service_dhcp-relay01.webp" alt="DHCP relay example" /> +<figcaption aria-hidden="true">DHCP relay example</figcaption> +</figure> + +The generated configuration will look like: + +``` none +show service dhcp-relay + listen-interface eth1 + upstrem-interface eth2 + server 10.0.1.4 + relay-options { + relay-agents-packets discard + } +``` + +Also, for backwards compatibility this configuration, which uses generic +interface definition, is still valid: + +``` none +show service dhcp-relay + interface eth1 + interface eth2 + server 10.0.1.4 + relay-options { + relay-agents-packets discard + } +``` + +### Operation + +<div class="opcmd"> + +restart dhcp relay-agent + +Restart DHCP relay service + +</div> + +## IPv6 relay + +### Configuration + +<div class="cfgcmd"> + +set service dhcpv6-relay listen-interface \<interface\> + +Set eth1 to be the listening interface for the DHCPv6 relay. + +Multiple interfaces may be specified. + +</div> + +<div class="cfgcmd"> + +set service dhcpv6-relay upstream-interface \<interface\> +address \<server\> + +Specifies an upstream network <span class="title-ref">\<interface\></span> from which replies from +<span class="title-ref">\<server\></span> and other relay agents will be accepted. + +</div> + +<div id="dhcp-relay:ipv6_options"> + +<div class="cfgcmd"> + +set service dhcpv6-relay disable + +Disable dhcpv6-relay service. + +</div> + +</div> + +#### Options + +<div class="cfgcmd"> + +set service dhcpv6-relay max-hop-count \<count\> + +Set maximum hop count before packets are discarded, default: 10 + +</div> + +<div class="cfgcmd"> + +set service dhcpv6-relay use-interface-id-option + +If this is set the relay agent will insert the interface ID. This option is +set automatically if more than one listening interfaces are in use. + +</div> + +### Example + +- DHCPv6 requests are received by the router on <span class="title-ref">listening interface</span> `eth1` +- Requests are forwarded through `eth2` as the <span class="title-ref">upstream interface</span> +- External DHCPv6 server is at 2001:db8::4 + +<figure> +<img src="/_static/images/service_dhcpv6-relay01.webp" alt="DHCPv6 relay example" /> +<figcaption aria-hidden="true">DHCPv6 relay example</figcaption> +</figure> + +The generated configuration will look like: + +``` none +commit +show service dhcpv6-relay + listen-interface eth1 { + } + upstream-interface eth2 { + address 2001:db8::4 + } +``` + +### Operation + +<div class="opcmd"> + +restart dhcpv6 relay-agent + +Restart DHCPv6 relay agent immediately. + +</div> diff --git a/docs/configuration/service/md-dhcp-server.md b/docs/configuration/service/md-dhcp-server.md new file mode 100644 index 00000000..f77daec3 --- /dev/null +++ b/docs/configuration/service/md-dhcp-server.md @@ -0,0 +1,1128 @@ +# DHCP Server + +VyOS uses ISC DHCP server for both IPv4 and IPv6 address assignment. + +## IPv4 server + +The network topology is declared by shared-network-name and the subnet +declarations. The DHCP service can serve multiple shared networks, with each +shared network having 1 or more subnets. Each subnet must be present on an +interface. A range can be declared inside a subnet to define a pool of dynamic +addresses. Multiple ranges can be defined and can contain holes. Static +mappings can be set to assign "static" addresses to clients based on their MAC +address. + +### Configuration + +<div class="cfgcmd"> + +set service dhcp-server hostfile-update + +Create DNS record per client lease, by adding clients to /etc/hosts file. +Entry will have format: <span class="title-ref">\<shared-network-name\>\_\<hostname\>.\<domain-name\></span> + +</div> + +<div class="cfgcmd"> + +set service dhcp-server host-decl-name + +Will drop <span class="title-ref">\<shared-network-name\>\_</span> from client DNS record, using only the +host declaration name and domain: <span class="title-ref">\<hostname\>.\<domain-name\></span> + +</div> + +<div class="cfgcmd"> + +set service dhcp-server shared-network-name \<name\> +domain-name \<domain-name\> + +The domain-name parameter should be the domain name that will be appended to +the client's hostname to form a fully-qualified domain-name (FQDN) (DHCP +Option 015). + +This is the configuration parameter for the entire shared network definition. +All subnets will inherit this configuration item if not specified locally. + +</div> + +<div class="cfgcmd"> + +set service dhcp-server shared-network-name \<name\> +domain-search \<domain-name\> + +The domain-name parameter should be the domain name used when completing DNS +request where no full FQDN is passed. This option can be given multiple times +if you need multiple search domains (DHCP Option 119). + +This is the configuration parameter for the entire shared network definition. +All subnets will inherit this configuration item if not specified locally. + +</div> + +<div class="cfgcmd"> + +set service dhcp-server shared-network-name \<name\> +name-server \<address\> + +Inform client that the DNS server can be found at <span class="title-ref">\<address\></span>. + +This is the configuration parameter for the entire shared network definition. +All subnets will inherit this configuration item if not specified locally. + +Multiple DNS servers can be defined. + +</div> + +<div class="cfgcmd"> + +set service dhcp-server shared-network-name \<name\> ping-check + +When the DHCP server is considering dynamically allocating an IP address to a +client, it first sends an ICMP Echo request (a ping) to the address being +assigned. It waits for a second, and if no ICMP Echo response has been heard, +it assigns the address. + +If a response is heard, the lease is abandoned, and the server does not +respond to the client. The lease will remain abandoned for a minimum of +abandon-lease-time seconds (defaults to 24 hours). + +If there are no free addresses but there are abandoned IP addresses, the +DHCP server will attempt to reclaim an abandoned IP address regardless of the +value of abandon-lease-time. + +</div> + +<div class="cfgcmd"> + +set service dhcp-server listen-address \<address\> + +This configuration parameter lets the DHCP server to listen for DHCP +requests sent to the specified address, it is only realistically useful for +a server whose only clients are reached via unicasts, such as via DHCP relay +agents. + +</div> + +#### Individual Client Subnet + +<div class="cfgcmd"> + +set service dhcp-server shared-network-name \<name\> authoritative + +This says that this device is the only DHCP server for this network. If other +devices are trying to offer DHCP leases, this machine will send 'DHCPNAK' to +any device trying to request an IP address that is not valid for this +network. + +</div> + +<div class="cfgcmd"> + +set service dhcp-server shared-network-name \<name\> subnet \<subnet\> +default-router \<address\> + +This is a configuration parameter for the <span class="title-ref">\<subnet\></span>, saying that as part of +the response, tell the client that the default gateway can be reached at +<span class="title-ref">\<address\></span>. + +</div> + +<div class="cfgcmd"> + +set service dhcp-server shared-network-name \<name\> subnet \<subnet\> +name-server \<address\> + +This is a configuration parameter for the subnet, saying that as part of the +response, tell the client that the DNS server can be found at <span class="title-ref">\<address\></span>. + +Multiple DNS servers can be defined. + +</div> + +<div class="cfgcmd"> + +set service dhcp-server shared-network-name \<name\> subnet \<subnet\> +lease \<time\> + +Assign the IP address to this machine for <span class="title-ref">\<time\></span> seconds. + +The default value is 86400 seconds which corresponds to one day. + +</div> + +<div class="cfgcmd"> + +set service dhcp-server shared-network-name \<name\> subnet \<subnet\> +range \<n\> start \<address\> + +Create DHCP address range with a range id of <span class="title-ref">\<n\></span>. DHCP leases are taken +from this pool. The pool starts at address <span class="title-ref">\<address\></span>. + +</div> + +<div class="cfgcmd"> + +set service dhcp-server shared-network-name \<name\> subnet \<subnet\> +range \<n\> stop \<address\> + +Create DHCP address range with a range id of <span class="title-ref">\<n\></span>. DHCP leases are taken +from this pool. The pool stops with address <span class="title-ref">\<address\></span>. + +</div> + +<div class="cfgcmd"> + +set service dhcp-server shared-network-name \<name\> subnet \<subnet\> +exclude \<address\> + +Always exclude this address from any defined range. This address will never +be assigned by the DHCP server. + +This option can be specified multiple times. + +</div> + +<div class="cfgcmd"> + +set service dhcp-server shared-network-name \<name\> subnet \<subnet\> +domain-name \<domain-name\> + +The domain-name parameter should be the domain name that will be appended to +the client's hostname to form a fully-qualified domain-name (FQDN) (DHCP +Option 015). + +</div> + +<div class="cfgcmd"> + +set service dhcp-server shared-network-name \<name\> subnet \<subnet\> +domain-search \<domain-name\> + +The domain-name parameter should be the domain name used when completing DNS +request where no full FQDN is passed. This option can be given multiple times +if you need multiple search domains (DHCP Option 119). + +</div> + +<div class="cfgcmd"> + +set service dhcp-server shared-network-name \<name\> subnet \<subnet\> +ping-check + +When the DHCP server is considering dynamically allocating an IP address to a +client, it first sends an ICMP Echo request (a ping) to the address being +assigned. It waits for a second, and if no ICMP Echo response has been heard, +it assigns the address. + +If a response is heard, the lease is abandoned, and the server does not +respond to the client. The lease will remain abandoned for a minimum of +abandon-lease-time seconds (defaults to 24 hours). + +If a there are no free addresses but there are abandoned IP addresses, the +DHCP server will attempt to reclaim an abandoned IP address regardless of the +value of abandon-lease-time. + +</div> + +<div class="cfgcmd"> + +set service dhcp-server shared-network-name \<name\> subnet \<subnet\> +enable-failover + +Enable DHCP failover configuration for this address pool. + +</div> + +#### High Availability + +VyOS provides High Availability support for DHCP server. DHCP High +Availability can act in two different modes: + +- **Active-active**: both DHCP servers will respond to DHCP requests. If + `mode` is not defined, this is the default behavior. +- **Active-passive**: only `primary` server will respond to DHCP requests. + If this server goes offline, then `secondary` server will take place. + +DHCP High Availability must be configured explicitly by the following +statements on both servers: + +<div class="cfgcmd"> + +set service dhcp-server high-availability mode \[active-active +| active-passive\] + +Define operation mode of High Availability feature. Default value if command +is not specified is <span class="title-ref">active-active</span> + +</div> + +<div class="cfgcmd"> + +set service dhcp-server high-availability source-address \<address\> + +Local IP <span class="title-ref">\<address\></span> used when communicating to the HA peer. + +</div> + +<div class="cfgcmd"> + +set service dhcp-server high-availability remote \<address\> + +Remote peer IP <span class="title-ref">\<address\></span> of the second DHCP server in this HA +cluster. + +</div> + +<div class="cfgcmd"> + +set service dhcp-server high-availability name \<name\> + +Define the name of the peer server to establish and identify the HA (High Availability) connection. + +</div> + +<div class="cfgcmd"> + +set service dhcp-server high-availability status \<primary +| secondary\> + +The primary and secondary statements determines whether the server is primary +or secondary. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +In order for the primary and the secondary DHCP server to keep +their lease tables in sync, they must be able to reach each other on TCP +port 647. If you have firewall rules in effect, adjust them accordingly. + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +The dialogue between HA partners is neither encrypted nor +authenticated. Since most DHCP servers exist within an organisation's own +secure Intranet, this would be an unnecessary overhead. However, if you +have DHCP HA peers whose communications traverse insecure networks, +then we recommend that you consider the use of VPN tunneling between them +to ensure that the HA partnership is immune to disruption +(accidental or otherwise) via third parties. + +</div> + +</div> + +#### Static mappings + +You can specify a static DHCP assignment on a per host basis. You will need the +MAC address of the station and your desired IP address. The address must be +inside the subnet definition but can be outside of the range statement. + +<div class="cfgcmd"> + +set service dhcp-server shared-network-name \<name\> subnet +\<subnet\> static-mapping \<description\> mac-address \<address\> + +Create a new DHCP static mapping named <span class="title-ref">\<description\></span> which is valid for +the host identified by its MAC <span class="title-ref">\<address\></span>. + +</div> + +<div class="cfgcmd"> + +set service dhcp-server shared-network-name \<name\> subnet +\<subnet\> static-mapping \<description\> ip-address \<address\> + +Static DHCP IP address assign to host identified by <span class="title-ref">\<description\></span>. IP +address must be inside the <span class="title-ref">\<subnet\></span> which is defined but can be outside +the dynamic range created with `set service dhcp-server +shared-network-name <name> subnet <subnet> range <n>`. If no ip-address is +specified, an IP from the dynamic pool is used. + +This is useful, for example, in combination with hostfile update. + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +This is the equivalent of the host block in dhcpd.conf of +isc-dhcpd. + +</div> + +</div> + +**Example:** + +- IP address `192.168.1.100` shall be statically mapped to + client named `client1` + +``` none +set service dhcp-server shared-network-name 'NET1' subnet 192.168.1.0/24 static-mapping client1 ip-address 192.168.1.100 +set service dhcp-server shared-network-name 'NET1' subnet 192.168.1.0/24 static-mapping client1 mac-address aa:bb:11:22:33:00 +``` + +The configuration will look as follows: + +``` none +show service dhcp-server shared-network-name NET1 + subnet 192.168.1.0/24 { + static-mapping client1 { + ip-address 192.168.1.100 + mac-address aa:bb:11:22:33:00 + } + } +``` + +### Options + +<table> +<colgroup> +<col style="width: 11%" /> +<col style="width: 6%" /> +<col style="width: 22%" /> +<col style="width: 39%" /> +<col style="width: 19%" /> +</colgroup> +<thead> +<tr> +<th>Setting name</th> +<th>Option number</th> +<th>ISC-DHCP Option name</th> +<th>Option description</th> +<th>Multi</th> +</tr> +</thead> +<tbody> +<tr> +<td>client-prefix-length</td> +<td>1</td> +<td>subnet-mask</td> +<td>Specifies the clients subnet mask as per RFC 950. If unset, +subnet declaration is used.</td> +<td>N</td> +</tr> +<tr> +<td>time-offset</td> +<td>2</td> +<td>time-offset</td> +<td>Offset of the client's subnet in seconds from Coordinated +Universal Time (UTC)</td> +<td>N</td> +</tr> +<tr> +<td>default-router</td> +<td>3</td> +<td>routers</td> +<td>IPv4 address of router on the client's subnet</td> +<td>N</td> +</tr> +<tr> +<td>time-server</td> +<td>4</td> +<td>time-servers</td> +<td>RFC 868 time server IPv4 address</td> +<td>Y</td> +</tr> +<tr> +<td>name-server</td> +<td>6</td> +<td>domain-name-servers</td> +<td>DNS server IPv4 address</td> +<td>Y</td> +</tr> +<tr> +<td>domain-name</td> +<td>15</td> +<td>domain-name</td> +<td>Client domain name</td> +<td>Y</td> +</tr> +<tr> +<td>ip-forwarding</td> +<td>19</td> +<td>ip-forwarding</td> +<td>Enable IP forwarding on client</td> +<td>N</td> +</tr> +<tr> +<td>ntp-server</td> +<td>42</td> +<td>ntp-servers</td> +<td>IP address of NTP server</td> +<td>Y</td> +</tr> +<tr> +<td>wins-server</td> +<td>44</td> +<td>netbios-name-servers</td> +<td>NetBIOS over TCP/IP name server</td> +<td>Y</td> +</tr> +<tr> +<td>server-identifier</td> +<td>54</td> +<td>dhcp-server-identifier</td> +<td>IP address for DHCP server identifier</td> +<td>N</td> +</tr> +<tr> +<td>bootfile-server</td> +<td>siaddr</td> +<td>next-server</td> +<td>IPv4 address of next bootstrap server</td> +<td>N</td> +</tr> +<tr> +<td>tftp-server-name</td> +<td>66</td> +<td>tftp-server-name</td> +<td>Name or IPv4 address of TFTP server</td> +<td>N</td> +</tr> +<tr> +<td>bootfile-name</td> +<td>67</td> +<td>bootfile-name, filename</td> +<td>Bootstrap file name</td> +<td>N</td> +</tr> +<tr> +<td>bootfile-size</td> +<td>13</td> +<td>boot-size</td> +<td>Boot image length in 512-octet blocks</td> +<td>N</td> +</tr> +<tr> +<td>smtp-server</td> +<td>69</td> +<td>smtp-server</td> +<td>IP address of SMTP server</td> +<td>Y</td> +</tr> +<tr> +<td>pop-server</td> +<td>70</td> +<td>pop-server</td> +<td>IP address of POP3 server</td> +<td>Y</td> +</tr> +<tr> +<td>domain-search</td> +<td>119</td> +<td>domain-search</td> +<td>Client domain search</td> +<td>Y</td> +</tr> +<tr> +<td>static-route</td> +<td>121, 249</td> +<td>rfc3442-static-route, windows-static-route</td> +<td>Classless static route</td> +<td>N</td> +</tr> +<tr> +<td>wpad-url</td> +<td>252</td> +<td>wpad-url, wpad-url code 252 = text</td> +<td>Web Proxy Autodiscovery (WPAD) URL</td> +<td>N</td> +</tr> +<tr> +<td>lease</td> +<td></td> +<td>default-lease-time, max-lease-time</td> +<td>Lease timeout in seconds (default: 86400)</td> +<td>N</td> +</tr> +<tr> +<td>range</td> +<td></td> +<td>range</td> +<td>DHCP lease range</td> +<td>Y</td> +</tr> +<tr> +<td>exclude</td> +<td></td> +<td></td> +<td>IP address to exclude from DHCP lease range</td> +<td>Y</td> +</tr> +<tr> +<td>failover</td> +<td></td> +<td></td> +<td>DHCP failover parameters</td> +<td></td> +</tr> +<tr> +<td>static-mapping</td> +<td></td> +<td></td> +<td>Name of static mapping</td> +<td>Y</td> +</tr> +</tbody> +</table> + +Multi: can be specified multiple times. + +### Raw Parameters + +Raw parameters can be passed to shared-network-name, subnet and static-mapping: + +``` none +set service dhcp-server shared-network-name <name> shared-network-parameters + <text> Additional shared-network parameters for DHCP server. +set service dhcp-server shared-network-name <name> subnet <subnet> subnet-parameters + <text> Additional subnet parameters for DHCP server. +set service dhcp-server shared-network-name <name> subnet <subnet> static-mapping <description> static-mapping-parameters + <text> Additional static-mapping parameters for DHCP server. + Will be placed inside the "host" block of the mapping. +``` + +These parameters are passed as-is to isc-dhcp's dhcpd.conf under the +configuration node they are defined in. They are not validated so an error in +the raw parameters won't be caught by vyos's scripts and will cause dhcpd to +fail to start. Always verify that the parameters are correct before committing +the configuration. Refer to isc-dhcp's dhcpd.conf manual for more information: +<https://kb.isc.org/docs/isc-dhcp-44-manual-pages-dhcpdconf> + +Quotes can be used inside parameter values by replacing all quote characters +with the string `"`. They will be replaced with literal quote characters +when generating dhcpd.conf. + +### Example + +Please see the `dhcp-dns-quick-start` configuration. + +#### High Availability + +Configuration of a DHCP HA pair + +- Setup DHCP HA for network 192.0.2.0/24 +- Use active-active HA mode. +- Default gateway and DNS server is at <span class="title-ref">192.0.2.254</span> +- The primary DHCP server named dhcp-primary uses address <span class="title-ref">192.168.189.252</span> +- The secondary DHCP server named dhcp-secondary uses address <span class="title-ref">192.168.189.253</span> +- DHCP range spans from <span class="title-ref">192.168.189.10</span> - <span class="title-ref">192.168.189.250</span> + +Common configuration, valid for both primary and secondary node. + +``` none +set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 default-router '192.0.2.254' +set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 name-server '192.0.2.254' +set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 domain-name 'vyos.net' +set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 start '192.0.2.10' +set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 stop '192.0.2.250' +set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 enable-failover +``` + +**Primary** + +``` none +set service dhcp-server high-availability mode 'active-active' +set service dhcp-server high-availability source-address '192.168.189.252' +set service dhcp-server high-availability name 'dhcp-secondary' +set service dhcp-server high-availability remote '192.168.189.253' +set service dhcp-server high-availability status 'primary' +``` + +**Secondary** + +``` none +set service dhcp-server high-availability mode 'active-active' +set service dhcp-server high-availability source-address '192.168.189.253' +set service dhcp-server high-availability name 'dhcp-primary' +set service dhcp-server high-availability remote '192.168.189.252' +set service dhcp-server high-availability status 'secondary' +``` + +#### Raw Parameters + +- Override static-mapping's name-server with a custom one that will be sent only + to this host. +- An option that takes a quoted string is set by replacing all quote characters + with the string `"` inside the static-mapping-parameters value. + The resulting line in dhcpd.conf will be + `option pxelinux.configfile "pxelinux.cfg/01-00-15-17-44-2d-aa";`. + +``` none +set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping example static-mapping-parameters "option domain-name-servers 192.0.2.11, 192.0.2.12;" +set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping example static-mapping-parameters "option pxelinux.configfile "pxelinux.cfg/01-00-15-17-44-2d-aa";" +``` + +#### Option 43 for UniFI + +- These parameters need to be part of the DHCP global options. + They stay unchanged. + +``` none +set service dhcp-server global-parameters 'option space ubnt;' +set service dhcp-server global-parameters 'option ubnt.unifi-address code 1 = ip-address;' +set service dhcp-server global-parameters 'class "ubnt" {' +set service dhcp-server global-parameters 'match if substring (option vendor-class-identifier, 0, 4) = "ubnt";' +set service dhcp-server global-parameters 'option vendor-class-identifier "ubnt";' +set service dhcp-server global-parameters 'vendor-option-space ubnt;' +set service dhcp-server global-parameters '}' +``` + +- Now we add the option to the scope, adapt to your setup + +``` none +set service dhcp-server shared-network-name example-scope subnet 10.1.1.0/24 subnet-parameters 'option ubnt.unifi-address 172.16.1.10;' +``` + +### Operation Mode + +<div class="opcmd"> + +show log dhcp server + +Show DHCP server daemon log file + +</div> + +<div class="opcmd"> + +show log dhcp client + +Show logs from all DHCP client processes. + +</div> + +<div class="opcmd"> + +show log dhcp client interface \<interface\> + +Show logs from specific <span class="title-ref">interface</span> DHCP client process. + +</div> + +<div class="opcmd"> + +restart dhcp server + +Restart the DHCP server + +</div> + +<div class="opcmd"> + +show dhcp server statistics + +Show the DHCP server statistics: + +</div> + +``` none +vyos@vyos:~$ show dhcp server statistics +Pool Size Leases Available Usage +----------- ------ -------- ----------- ------- +dhcpexample 99 2 97 2% +``` + +<div class="opcmd"> + +show dhcp server statistics pool \<pool\> + +Show the DHCP server statistics for the specified pool. + +</div> + +<div class="opcmd"> + +show dhcp server leases + +Show statuses of all active leases: + +</div> + +``` none +vyos@vyos:~$ show dhcp server leases +IP Address MAC address State Lease start Lease expiration Remaining Pool Hostname Origin +-------------- ----------------- ------- ------------------- ------------------- ----------- -------- ---------- -------- +192.168.11.134 00:50:79:66:68:09 active 2023/11/29 09:51:05 2023/11/29 10:21:05 0:24:10 LAN VPCS1 local +192.168.11.133 50:00:00:06:00:00 active 2023/11/29 09:51:38 2023/11/29 10:21:38 0:24:43 LAN VYOS-6 local +10.11.11.108 50:00:00:05:00:00 active 2023/11/29 09:51:43 2023/11/29 10:21:43 0:24:48 VIF-1001 VYOS5 local +192.168.11.135 00:50:79:66:68:07 active 2023/11/29 09:55:16 2023/11/29 09:59:16 0:02:21 remote +vyos@vyos:~$ +``` + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +Static mappings aren't shown. To show all states, use +`show dhcp server leases state all`. + +</div> + +<div class="opcmd"> + +show dhcp server leases origin \[local | remote\] + +Show statuses of all active leases granted by local (this server) or +remote (failover server): + +</div> + +``` none +vyos@vyos:~$ show dhcp server leases origin remote +IP Address MAC address State Lease start Lease expiration Remaining Pool Hostname Origin +-------------- ----------------- ------- ------------------- ------------------- ----------- -------- ---------- -------- +192.168.11.135 00:50:79:66:68:07 active 2023/11/29 09:55:16 2023/11/29 09:59:16 0:02:21 remote +vyos@vyos:~$ +``` + +<div class="opcmd"> + +show dhcp server leases pool \<pool\> + +Show only leases in the specified pool. + +</div> + +``` none +vyos@vyos:~$ show dhcp server leases pool LAN +IP Address MAC address State Lease start Lease expiration Remaining Pool Hostname Origin +-------------- ----------------- ------- ------------------- ------------------- ----------- ------ ---------- -------- +192.168.11.134 00:50:79:66:68:09 active 2023/11/29 09:51:05 2023/11/29 10:21:05 0:23:55 LAN VPCS1 local +192.168.11.133 50:00:00:06:00:00 active 2023/11/29 09:51:38 2023/11/29 10:21:38 0:24:28 LAN VYOS-6 local +vyos@vyos:~$ +``` + +<div class="opcmd"> + +show dhcp server leases sort \<key\> + +Sort the output by the specified key. Possible keys: ip, hardware_address, +state, start, end, remaining, pool, hostname (default = ip) + +</div> + +<div class="opcmd"> + +show dhcp server leases state \<state\> + +Show only leases with the specified state. Possible states: all, active, +free, expired, released, abandoned, reset, backup (default = active) + +</div> + +## IPv6 server + +VyOS also provides DHCPv6 server functionality which is described in this +section. + +### Configuration + +<div class="cfgcmd"> + +set service dhcpv6-server preference \<preference value\> + +Clients receiving advertise messages from multiple servers choose the server +with the highest preference value. The range for this value is `0...255`. + +</div> + +<div class="cfgcmd"> + +set service dhcpv6-server shared-network-name \<name\> subnet +\<prefix\> lease-time {default | maximum | minimum} + +The default lease time for DHCPv6 leases is 24 hours. This can be changed by +supplying a `default-time`, `maximum-time` and `minimum-time`. All +values need to be supplied in seconds. + +</div> + +<div class="cfgcmd"> + +set service dhcpv6-server shared-network-name \<name\> subnet +\<prefix\> nis-domain \<domain-name\> + +A `NIS (Network Information Service)` domain can be set to be used for +DHCPv6 clients. + +</div> + +<div class="cfgcmd"> + +set service dhcpv6-server shared-network-name \<name\> subnet +\<prefix\> nisplus-domain \<domain-name\> + +The procedure to specify a `NIS+ (Network Information Service Plus)` +domain is similar to the NIS domain one: + +</div> + +<div class="cfgcmd"> + +set service dhcpv6-server shared-network-name \<name\> subnet +\<prefix\> nis-server \<address\> + +Specify a NIS server address for DHCPv6 clients. + +</div> + +<div class="cfgcmd"> + +set service dhcpv6-server shared-network-name \<name\> subnet +\<prefix\> nisplus-server \<address\> + +Specify a NIS+ server address for DHCPv6 clients. + +</div> + +<div class="cfgcmd"> + +set service dhcpv6-server shared-network-name \<name\> subnet +\<prefix\> sip-server \<address | fqdn\> + +Specify a `SIP (Session Initiation Protocol)` server by IPv6 +address of Fully Qualified Domain Name for all DHCPv6 clients. + +</div> + +<div class="cfgcmd"> + +set service dhcpv6-server shared-network-name \<name\> subnet +\<prefix\> sntp-server-address \<address\> + +A SNTP server address can be specified for DHCPv6 clients. + +</div> + +#### Prefix Delegation + +<div class="note"> + +<div class="title"> + +Note + +</div> + +VyOS =\< 1.4.3 does not add the prefixes to the routing table. + +</div> + +To hand out individual prefixes to your clients the following configuration is +used: + +<div class="cfgcmd"> + +set service dhcpv6-server shared-network-name \<name\> subnet +\<prefix\> prefix-delegation start \<address\> prefix-length \<length\> + +Hand out prefixes of size <span class="title-ref">\<length\></span> to clients in subnet <span class="title-ref">\<prefix\></span> when +they request for prefix delegation. + +</div> + +<div class="cfgcmd"> + +set service dhcpv6-server shared-network-name \<name\> subnet +\<prefix\> prefix-delegation start \<address\> stop \<address\> + +Delegate prefixes from the range indicated by the start and stop qualifier. + +</div> + +**Example:** + +To delegate /64's from a bigger /56 + +``` none +set service dhcpv6-server shared-network-name MYNET subnet 2001:db8:0:1::/64 prefix-delegation start 2001:0db8:1:: prefix-length '64' +set service dhcpv6-server shared-network-name MYNET subnet 2001:db8:0:1::/64 prefix-delegation start 2001:0db8:1:: stop '2001:0db8:1:ff::' +``` + +#### Address pools + +DHCPv6 address pools must be configured for the system to act as a DHCPv6 +server. The following example describes a common scenario. + +**Example:** + +- A shared network named `NET1` serves subnet `2001:db8::/64` +- It is connected to `eth1` +- DNS server is located at `2001:db8::ffff` +- Address pool shall be `2001:db8::100` through `2001:db8::199`. +- Lease time will be left at the default value which is 24 hours + +``` none +set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 address-range start 2001:db8::100 stop 2001:db8::199 +set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 name-server 2001:db8::ffff +``` + +The configuration will look as follows: + +``` none +show service dhcpv6-server + shared-network-name NET1 { + subnet 2001:db8::/64 { + address-range { + start 2001:db8::100 { + stop 2001:db8::199 + } + } + name-server 2001:db8::ffff + } + } +``` + +#### Static mappings + +In order to map specific IPv6 addresses to specific hosts static mappings can +be created. The following example explains the process. + +**Example:** + +- IPv6 address `2001:db8::101` shall be statically mapped +- IPv6 prefix `2001:db8:0:101::/64` shall be statically mapped +- Host specific mapping shall be named `client1` + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +The identifier is the device's DUID: colon-separated hex list (as +used by isc-dhcp option dhcpv6.client-id). If the device already has a +dynamic lease from the DHCPv6 server, its DUID can be found with `show service dhcpv6 server leases`. + +</div> + +``` none +set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 ipv6-address 2001:db8::101 +set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 ipv6-prefix 2001:db8:0:101::/64 +set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 identifier 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff +``` + +The configuration will look as follows: + +``` none +show service dhcpv6-server shared-network-name NET1 + subnet 2001:db8::/64 { + static-mapping client1 { + identifier 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff + ipv6-address 2001:db8::101 + ipv6-prefix 2001:db8:0:101::/64 + } + } +``` + +### Operation Mode + +<div class="opcmd"> + +show log dhcpv6 server + +Show DHCPv6 server daemon log file + +</div> + +<div class="opcmd"> + +show log dhcpv6 client + +Show logs from all DHCPv6 client processes. + +</div> + +<div class="opcmd"> + +show log dhcpv6 client interface \<interface\> + +Show logs from specific <span class="title-ref">interface</span> DHCPv6 client process. + +</div> + +<div class="opcmd"> + +restart dhcpv6 server + +To restart the DHCPv6 server + +</div> + +<div class="opcmd"> + +show dhcpv6 server leases + +Shows status of all assigned leases: + +</div> + +``` none +vyos@vyos:~$ show dhcpv6 server leases +IPv6 address State Last communication Lease expiration Remaining Type Pool DUID +------------- ------- -------------------- ------------------- ----------- ------------- ----- -------------------------------------------- +2001:db8::101 active 2019/12/05 19:40:10 2019/12/06 07:40:10 11:45:21 non-temporary NET1 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff +2001:db8::102 active 2019/12/05 14:01:23 2019/12/06 02:01:23 6:06:34 non-temporary NET1 00:01:00:01:11:22:33:44:fa:fb:fc:fd:fe:ff +``` + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +Static mappings aren't shown. To show all states, use `show dhcp server leases state all`. + +</div> + +<div class="opcmd"> + +show dhcpv6 server leases pool \<pool\> + +Show only leases in the specified pool. + +</div> + +<div class="opcmd"> + +show dhcpv6 server leases sort \<key\> + +Sort the output by the specified key. Possible keys: expires, duid, ip, +last_comm, pool, remaining, state, type (default = ip) + +</div> + +<div class="opcmd"> + +show dhcpv6 server leases state \<state\> + +Show only leases with the specified state. Possible states: abandoned, +active, all, backup, expired, free, released, reset (default = active) + +</div> diff --git a/docs/configuration/service/md-dns.md b/docs/configuration/service/md-dns.md new file mode 100644 index 00000000..08a24b48 --- /dev/null +++ b/docs/configuration/service/md-dns.md @@ -0,0 +1,574 @@ +# DNS Forwarding + +## Configuration + +VyOS provides DNS infrastructure for small networks. It is designed to be +lightweight and have a small footprint, suitable for resource constrained +routers and firewalls. For this we utilize PowerDNS recursor. + +The VyOS DNS forwarder does not require an upstream DNS server. It can serve as +a full recursive DNS server - but it can also forward queries to configurable +upstream DNS servers. By not configuring any upstream DNS servers you also +avoid being tracked by the provider of your upstream DNS server. + +<div class="cfgcmd"> + +set service dns forwarding system + +Forward incoming DNS queries to the DNS servers configured under the `system name-server` nodes. + +</div> + +<div class="cfgcmd"> + +set service dns forwarding dhcp \<interface\> + +Interfaces whose DHCP client nameservers to forward requests to. + +</div> + +<div class="cfgcmd"> + +set service dns forwarding name-server \<address\> port \<port\> + +Send all DNS queries to the IPv4/IPv6 DNS server specified under <span class="title-ref">\<address\></span> +on optional port specified under <span class="title-ref">\<port\></span>. The port defaults to 53. You can +configure multiple nameservers here. + +</div> + +<div class="cfgcmd"> + +set service dns forwarding domain \<domain-name\> name-server \<address\> + +Forward received queries for a particular domain +(specified via <span class="title-ref">domain-name</span>) to a given nameserver. Multiple nameservers +can be specified. You can use this feature for a DNS split-horizon +configuration. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +This also works for reverse-lookup zones (`18.172.in-addr.arpa`). + +</div> + +</div> + +<div class="cfgcmd"> + +set service dns forwarding domain \<domain-name\> addnta + +Add NTA (negative trust anchor) for this domain. This must be set if the +domain does not support DNSSEC. + +</div> + +<div class="cfgcmd"> + +set service dns forwarding domain \<domain-name\> recursion-desired + +Set the "recursion desired" bit in requests to the upstream nameserver. + +</div> + +<div class="cfgcmd"> + +set service dns forwarding allow-from \<network\> + +Given the fact that open DNS recursors could be used on DDoS amplification +attacks, you must configure the networks which are allowed to use this +recursor. A network of `0.0.0.0/0` or `::/0` would allow all IPv4 and +IPv6 networks to query this server. This is generally a bad idea. + +</div> + +<div class="cfgcmd"> + +set service dns forwarding dnssec +\<off | process-no-validate | process | log-fail | validate\> + +The PowerDNS recursor has 5 different levels of DNSSEC processing, which can +be set with the dnssec setting. In order from least to most processing, these +are: + +- **off** In this mode, no DNSSEC processing takes place. The recursor will + not set the DNSSEC OK (DO) bit in the outgoing queries and will ignore the + DO and AD bits in queries. +- **process-no-validate** In this mode the recursor acts as a "security + aware, non-validating" nameserver, meaning it will set the DO-bit on + outgoing queries and will provide DNSSEC related RRsets (NSEC, RRSIG) to + clients that ask for them (by means of a DO-bit in the query), except for + zones provided through the auth-zones setting. It will not do any + validation in this mode, not even when requested by the client. +- **process** When dnssec is set to process the behavior is similar to + process-no-validate. However, the recursor will try to validate the data + if at least one of the DO or AD bits is set in the query; in that case, + it will set the AD-bit in the response when the data is validated + successfully, or send SERVFAIL when the validation comes up bogus. +- **log-fail** In this mode, the recursor will attempt to validate all data + it retrieves from authoritative servers, regardless of the client's DNSSEC + desires, and will log the validation result. This mode can be used to + determine the extra load and amount of possibly bogus answers before + turning on full-blown validation. Responses to client queries are the same + as with process. +- **validate** The highest mode of DNSSEC processing. In this mode, all + queries will be validated and will be answered with a SERVFAIL in case of + bogus data, regardless of the client's request. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The popular Unix/Linux `dig` tool sets the AD-bit in the query. +This might lead to unexpected query results when testing. Set `+noad` +on the `dig` command line when this is the case. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The `CD`-bit is honored correctly for process and validate. For +log-fail, failures will be logged too. + +</div> + +</div> + +<div class="cfgcmd"> + +set service dns forwarding ignore-hosts-file + +Do not use the local `/etc/hosts` file in name resolution. VyOS DHCP +server will use this file to add resolvers to assigned addresses. + +</div> + +<div class="cfgcmd"> + +set service dns forwarding cache-size \<0-2147483647\> + +Maximum number of DNS cache entries. 1 million per CPU core will generally +suffice for most installations. + +This defaults to 10000. + +</div> + +<div class="cfgcmd"> + +set service dns forwarding negative-ttl \<0-7200\> + +A query for which there is authoritatively no answer is cached to quickly +deny a record's existence later on, without putting a heavy load on the +remote server. In practice, caches can become saturated with hundreds of +thousands of hosts which are tried only once. + +This setting, which defaults to 3600 seconds, puts a maximum on the amount +of time negative entries are cached. + +</div> + +<div class="cfgcmd"> + +set service dns forwarding timeout \<10-60000\> + +The number of milliseconds to wait for a remote authoritative server to +respond before timing out and responding with SERVFAIL. + +This setting defaults to 1500 and is valid between 10 and 60000. + +</div> + +<div class="cfgcmd"> + +set service dns forwarding listen-address \<address\> + +The local IPv4 or IPv6 addresses to bind the DNS forwarder to. The forwarder +will listen on this address for incoming connections. + +</div> + +<div class="cfgcmd"> + +set service dns forwarding source-address \<address\> + +The local IPv4 or IPv6 addresses to use as a source address for sending queries. +The forwarder will send forwarded outbound DNS requests from this address. + +</div> + +<div class="cfgcmd"> + +set service dns forwarding no-serve-rfc1918 + +This makes the server authoritatively not aware of: 10.in-addr.arpa, +168.192.in-addr.arpa, 16-31.172.in-addr.arpa, which enabling upstream +DNS server(s) to be used for reverse lookups of these zones. + +</div> + +## Example + +A VyOS router with two interfaces - eth0 (WAN) and eth1 (LAN) - is required to +implement a split-horizon DNS configuration for example.com. + +In this scenario: + +- All DNS requests for example.com must be forwarded to a DNS server + at 192.0.2.254 and 2001:db8:cafe::1 +- All other DNS requests will be forwarded to a different set of DNS servers at + 192.0.2.1, 192.0.2.2, 2001:db8::1:ffff and 2001:db8::2:ffff +- The VyOS DNS forwarder will only listen for requests on the eth1 (LAN) + interface addresses - 192.168.1.254 for IPv4 and 2001:db8::ffff for IPv6 +- The VyOS DNS forwarder will only accept lookup requests from the + LAN subnets - 192.168.1.0/24 and 2001:db8::/64 +- The VyOS DNS forwarder will pass reverse lookups for 10.in-addr.arpa, + 168.192.in-addr.arpa, 16-31.172.in-addr.arpa zones to upstream server. + +``` none +set service dns forwarding domain example.com name-server 192.0.2.254 +set service dns forwarding domain example.com name-server 2001:db8:cafe::1 +set service dns forwarding name-server 192.0.2.1 +set service dns forwarding name-server 192.0.2.2 +set service dns forwarding name-server 192.0.2.3 port 853 +set service dns forwarding name-server 2001:db8::1:ffff +set service dns forwarding name-server 2001:db8::2:ffff +set service dns forwarding name-server 2001:db8::3:ffff port 8053 +set service dns forwarding listen-address 192.168.1.254 +set service dns forwarding listen-address 2001:db8::ffff +set service dns forwarding allow-from 192.168.1.0/24 +set service dns forwarding allow-from 2001:db8::/64 +set service dns forwarding no-serve-rfc1918 +``` + +## Operation + +<div class="opcmd"> + +reset dns forwarding \<all | domain\> + +Resets the local DNS forwarding cache database. You can reset the cache +for all entries or only for entries to a specific domain. + +</div> + +<div class="opcmd"> + +restart dns forwarding + +Restarts the DNS recursor process. This also invalidates the local DNS +forwarding cache. + +</div> + +# Dynamic DNS + +VyOS is able to update a remote DNS record when an interface gets a new IP +address. In order to do so, VyOS includes [ddclient](https://github.com/ddclient/ddclient), a Perl script written for +this only one purpose. + +[ddclient](https://github.com/ddclient/ddclient) uses two methods to update a DNS record. The first one will send +updates directly to the DNS daemon, in compliance with `2136`. The second +one involves a third party service, like DynDNS.com or any other such +service provider. This method uses HTTP requests to transmit the new IP address. You +can configure both in VyOS. + +## Configuration + +### `2136` Based + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> address interface \<interface\> + +Create new dynamic DNS update configuration which will update the IP +address assigned to <span class="title-ref">\<interface\></span> on the service you configured under +<span class="title-ref">\<service-name\></span>. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> description \<text\> + +Set description <span class="title-ref">\<text\></span> for dynamic DNS service being configured. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> key \<filename\> + +File identified by <span class="title-ref">\<filename\></span> containing the TSIG authentication key for RFC2136 +nsupdate on remote DNS server. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> server \<server\> + +Configure the DNS <span class="title-ref">\<server\></span> IP/FQDN used when updating this dynamic +assignment. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> zone \<zone\> + +Configure DNS <span class="title-ref">\<zone\></span> to be updated. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> host-name \<record\> + +Configure DNS <span class="title-ref">\<record\></span> which should be updated. This can be set multiple times. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> ttl \<ttl\> + +Configure optional TTL value on the given resource record. This defaults to +600 seconds. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic interval \<60-3600\> + +Specify interval in seconds to wait between Dynamic DNS updates. +The default is 300 seconds. + +</div> + +#### Example + +- Register DNS record `example.vyos.io` on DNS server `ns1.vyos.io` +- Use auth key file at `/config/auth/my.key` +- Set TTL to 300 seconds + +``` none +# Configuration commands entered: +# +set service dns dynamic name 'VyOS-DNS' address interface 'eth0' +set service dns dynamic name 'VyOS-DNS' description 'RFC 2136 dynamic dns service' +set service dns dynamic name 'VyOS-DNS' key '/config/auth/my.key' +set service dns dynamic name 'VyOS-DNS' server 'ns1.vyos.io' +set service dns dynamic name 'VyOS-DNS' zone 'vyos.io' +set service dns dynamic name 'VyOS-DNS' host-name 'example.vyos.io' +set service dns dynamic name 'VyOS-DNS' protocol 'nsupdate' +set service dns dynamic name 'VyOS-DNS' ttl '300' + +# Resulting config: +# +vyos@vyos# show service dns dynamic + name VyOS-DNS { + address { + interface eth0 + } + description "RFC 2136 dynamic dns service" + host-name example.vyos.io + key /config/auth/my.key + protocol nsupdate + server ns1.vyos.io + ttl 300 + zone vyos.io + } +``` + +This will render the following [ddclient](https://github.com/ddclient/ddclient) configuration entry: + +``` none +# ddclient configuration for interface "eth0": +# + +# Web service dynamic DNS configuration for VyOS-DNS: [nsupdate, example.vyos.io] +use=if, \ +if=eth0, \ +protocol=nsupdate, \ +server=ns1.vyos.io, \ +zone=vyos.io, \ +password='/config/auth/my.key', \ +ttl=300 \ +example.vyos.io +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +You can also keep different DNS zone updated. Just create a new +config node: `set service dns dynamic interface <interface> rfc2136 <other-service-name>` + +</div> + +### HTTP based services + +VyOS is also able to use any service relying on protocols supported by ddclient. + +To use such a service, one must define a login, password, one or multiple +hostnames, protocol and server. + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> address interface \<interface\> + +Create new dynamic DNS update configuration which will update the IP +address assigned to <span class="title-ref">\<interface\></span> on the service you configured under +<span class="title-ref">\<service-name\></span>. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> description \<text\> + +Set description <span class="title-ref">\<text\></span> for dynamic DNS service being configured. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> host-name \<hostname\> + +Setup the dynamic DNS hostname <span class="title-ref">\<hostname\></span> associated with the DynDNS +provider identified by <span class="title-ref">\<service-name\></span>. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> username \<username\> + +Configure <span class="title-ref">\<username\></span> used when authenticating the update request for +DynDNS service identified by <span class="title-ref">\<service-name\></span>. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> password \<password\> + +Configure <span class="title-ref">\<password\></span> used when authenticating the update request for +DynDNS service identified by <span class="title-ref">\<service-name\></span>. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> protocol \<protocol\> + +When a `custom` DynDNS provider is used, the protocol used for communicating +to the provider must be specified under <span class="title-ref">\<protocol\></span>. See the embedded +completion helper when entering above command for available protocols. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> server \<server\> + +When a `custom` DynDNS provider is used the <span class="title-ref">\<server\></span> where update +requests are being sent to must be specified. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> ip-version 'ipv6' + +Allow explicit IPv6 address for the interface. + +</div> + +#### Example: + +Use deSEC (dedyn.io) as your preferred provider: + +``` none +set service dns dynamic name dedyn description 'deSEC dynamic dns service' +set service dns dynamic name dedyn username 'myusername' +set service dns dynamic name dedyn password 'mypassword' +set service dns dynamic name dedyn host-name 'myhostname.dedyn.io' +set service dns dynamic name dedyn protocol 'dyndns2' +set service dns dynamic name dedyn server 'update.dedyn.io' +set service dns dynamic name dedyn address interface 'eth0' +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Multiple services can be used per interface. Just specify as many +services per interface as you like! + +</div> + +#### Example IPv6 only: + +``` none +set service dns dynamic name dedyn description 'deSEC ipv6 dynamic dns service' +set service dns dynamic name dedyn username 'myusername' +set service dns dynamic name dedyn password 'mypassword' +set service dns dynamic name dedyn host-name 'myhostname.dedyn.io' +set service dns dynamic name dedyn protocol 'dyndns2' +set service dns dynamic name dedyn ip-version 'ipv6' +set service dns dynamic name dedyn server 'update6.dedyn.io' +set service dns dynamic name dedyn address interface 'eth0' +``` + +### Running Behind NAT + +By default, [ddclient](https://github.com/ddclient/ddclient) will update a dynamic dns record using the IP address +directly attached to the interface. If your VyOS instance is behind NAT, your +record will be updated to point to your internal IP. + +[ddclient](https://github.com/ddclient/ddclient) has another way to determine the WAN IP address. This is controlled +by: + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> address web \<url\> + +Use configured <span class="title-ref">\<url\></span> to determine your IP address. [ddclient](https://github.com/ddclient/ddclient) will load +<span class="title-ref">\<url\></span> and tries to extract your IP address from the response. + +</div> + +<div class="cfgcmd"> + +set service dns dynamic name \<service-name\> address web skip \<pattern\> + +[ddclient](https://github.com/ddclient/ddclient) will skip any address located before the string set in <span class="title-ref">\<pattern\></span>. + +</div> diff --git a/docs/configuration/service/md-eventhandler.md b/docs/configuration/service/md-eventhandler.md new file mode 100644 index 00000000..5280c43a --- /dev/null +++ b/docs/configuration/service/md-eventhandler.md @@ -0,0 +1,150 @@ +# Event Handler + +## Event Handler Technology Overview + +Event handler allows you to execute scripts when a string that matches a regex or a regex with +a service name appears in journald logs. You can pass variables, arguments, and a full matching string to the script. + +## How to configure Event Handler + +> [1. Create an event handler](#create-an-event-handler) +> +> [2. Add regex to the script](#add-regex-to-the-script) +> +> [3. Add a full path to the script](#add-a-full-path-to-the-script) +> +> [4. Add optional parameters](#add-optional-parameters) + +## Event Handler Configuration Steps + +### 1. Create an event handler + +> <div class="cfgcmd"> +> +> set service event-handler event \<event-handler name\> +> +> </div> +> +> This is an optional command because the event handler will be automatically created after any of the next commands. + +### 2. Add regex to the script + +> <div class="cfgcmd"> +> +> set service event-handler event \<event-handler name\> filter pattern \<regex\> +> +> </div> +> +> This is a mandatory command. Sets regular expression to match against log string message. +> +> <div class="note"> +> +> <div class="title"> +> +> Note +> +> </div> +> +> The regular expression matches if and only if the entire string matches the pattern. +> +> </div> + +### 3. Add a full path to the script + +> <div class="cfgcmd"> +> +> set service event-handler event \<event-handler name\> script path \<path to script\> +> +> </div> +> +> This is a mandatory command. Sets the full path to the script. The script file must be executable. + +### 4. Add optional parameters + +> <div class="cfgcmd"> +> +> set service event-handler event \<event-handler name\> filter syslog-identifier \<sylogid name\> +> +> </div> +> +> This is an optional command. Filters log messages by syslog-identifier. +> +> <div class="cfgcmd"> +> +> set service event-handler event \<event-handler name\> script environment \<env name\> value \<env value\> +> +> </div> +> +> This is an optional command. Adds environment and its value to the script. Use separate commands for each environment. +> +> One implicit environment exists. +> +> - `message`: Full message that has triggered the script. +> +> <div class="cfgcmd"> +> +> set service event-handler event \<event-handler name\> script arguments \<arguments\> +> +> </div> +> +> This is an optional command. Adds arguments to the script. Arguments must be separated by spaces. +> +> <div class="note"> +> +> <div class="title"> +> +> Note +> +> </div> +> +> We don't recomend to use arguments. Using environments is more preffereble. +> +> </div> + +## Example + +> Event handler that monitors the state of interface eth0. +> +> ``` none +> ``` +> +> set service event-handler event INTERFACE_STATE_DOWN filter pattern '.\*eth0.\*,RUNNING,.\*-\>.\*' +> set service event-handler event INTERFACE_STATE_DOWN filter syslog-identifier 'netplugd' +> set service event-handler event INTERFACE_STATE_DOWN script environment interface_action value 'down' +> set service event-handler event INTERFACE_STATE_DOWN script environment interface_name value 'eth2' +> set service event-handler event INTERFACE_STATE_DOWN script path '/config/scripts/eventhandler.py' +> +> Event handler script +> +> ``` none +> ``` +> +> \#!/usr/bin/env python3 +> \# +> \# VyOS event-handler script example +> from os import environ +> import subprocess +> from sys import exit +> +> \# Perform actions according to requirements +> def process_event() -\> None: +> \# Get variables +> message_text = environ.get('message') +> interface_name = environ.get('interface_name') +> interface_action = environ.get('interface_action') +> \# Print the message that triggered this script +> print(f'Logged message: {message_text}') +> \# Prepare a command to run +> command = f'sudo ip link set {interface_name} {interface_action}'.split() +> \# Execute a command +> subprocess.run(command) +> +> if \_\_name\_\_ == '\_\_main\_\_': +> try: +> \# Run script actions and exit +> process_event() +> exit(0) +> except Exception as err: +> \# Exit properly in case if something in the script goes wrong +> print(f'Error running script: {err}') +> exit(1) diff --git a/docs/configuration/service/md-https.md b/docs/configuration/service/md-https.md new file mode 100644 index 00000000..e68bcd50 --- /dev/null +++ b/docs/configuration/service/md-https.md @@ -0,0 +1,122 @@ +# HTTP API + +VyOS provide an HTTP API. You can use it to execute op-mode commands, +update VyOS, set or delete config. + +Please take a look at the `vyosapi` page for an detailed how-to. + +## Configuration + +<div class="cfgcmd"> + +set service https allow-client address \<address\> + +Only allow certain IP addresses or prefixes to access the https +webserver. + +</div> + +<div class="cfgcmd"> + +set service https certificates ca-certificate \<name\> + +Use CA certificate from PKI subsystem + +</div> + +<div class="cfgcmd"> + +set service https certificates certificate \<name\> + +Use certificate from PKI subsystem + +</div> + +<div class="cfgcmd"> + +set service https certificates dh-params \<name\> + +Use `DH (Diffie–Hellman)` parameters from PKI subsystem. +Must be at least 2048 bits in length. + +</div> + +<div class="cfgcmd"> + +set service https listen-address \<address\> + +Webserver should only listen on specified IP address + +</div> + +<div class="cfgcmd"> + +set service https port \<number\> + +Webserver should listen on specified port. + +Default: 443 + +</div> + +<div class="cfgcmd"> + +set service https enable-http-redirect + +Enable automatic redirect from http to https. + +</div> + +<div class="cfgcmd"> + +set service https tls-version \<1.2 | 1.3\> + +Select TLS version used. + +This defaults to both 1.2 and 1.3. + +</div> + +<div class="cfgcmd"> + +set service https vrf \<name\> + +Start Webserver in given VRF. + +</div> + +### API + +<div class="cfgcmd"> + +set service https api keys id \<name\> key \<apikey\> + +Set a named api key. Every key has the same, full permissions +on the system. + +</div> + +<div class="cfgcmd"> + +set service https api debug + +To enable debug messages. Available via `show log` or +`monitor log` + +</div> + +<div class="cfgcmd"> + +set service https api strict + +Enforce strict path checking + +</div> + +## Example Configuration + +Set an API-KEY is the minimal configuration to get a working API Endpoint. + +``` none +set service https api keys id MY-HTTPS-API-ID key MY-HTTPS-API-PLAINTEXT-KEY +``` diff --git a/docs/configuration/service/md-ids.md b/docs/configuration/service/md-ids.md new file mode 100644 index 00000000..b22c93dd --- /dev/null +++ b/docs/configuration/service/md-ids.md @@ -0,0 +1,228 @@ +# DDoS Protection + +## FastNetMon + +FastNetMon is a high-performance DDoS detector/sensor built on top of multiple +packet capture engines: NetFlow, IPFIX, sFlow, AF_PACKET (port mirror). It can +detect hosts in the deployed network sending or receiving large volumes of +traffic, packets/bytes/flows per second and perform a configurable action to +handle that event, such as calling a custom script. + +VyOS includes the FastNetMon Community Edition. + +### Configuration + +<div class="cfgcmd"> + +set service ids ddos-protection alert-script \<text\> + +Configure alert script that will be executed when an attack is detected. + +</div> + +<div class="cfgcmd"> + +set service ids ddos-protection ban-time \<1-4294967294\> + +Configure how long an IP (attacker) should be kept in blocked state. +Default value is 1900. + +</div> + +<div class="cfgcmd"> + +set service ids ddos-protection direction \[in | out\] + +Configure direction for processing traffic. + +</div> + +<div class="cfgcmd"> + +set service ids ddos-protection exclude-network \<x.x.x.x/x\> + +</div> + +<div class="cfgcmd"> + +set service ids ddos-protection exlude-network \<h:h:h:h:h:h:h:h/x\> + +Specify IPv4 and/or IPv6 networks which are going to be excluded. + +</div> + +<div class="cfgcmd"> + +set service ids ddos-protection listen-interface \<text\> + +Configure listen interface for mirroring traffic. + +</div> + +<div class="cfgcmd"> + +set service ids ddos-protection mode \[mirror | sflow\] + +Configure traffic capture mode. + +</div> + +<div class="cfgcmd"> + +set service ids ddos-protection network \<x.x.x.x/x\> + +</div> + +<div class="cfgcmd"> + +set service ids ddos-protection network \<h:h:h:h:h:h:h:h/x\> + +Specify IPv4 and/or IPv6 networks that should be protected/monitored. + +</div> + +<div class="cfgcmd"> + +set service ids ddos-protection sflow listen-address \<x.x.x.x\> + +Configure local IPv4 address to listen for sflow. + +</div> + +<div class="cfgcmd"> + +set service ids ddos-protection sflow port \<1-65535\> + +Configure port number to be used for sflow conection. Default port is 6343. + +</div> + +<div class="cfgcmd"> + +set service ids ddos-protection threshold general +\[fps | mbps | pps\] \<0-4294967294\> + +Configure general threshold parameters. + +</div> + +<div class="cfgcmd"> + +set service ids ddos-protection threshold icmp +\[fps | mbps | pps\] \<0-4294967294\> + +Configure ICMP threshold parameters. + +</div> + +<div class="cfgcmd"> + +set service ids ddos-protection threshold tcp +\[fps | mbps | pps\] \<0-4294967294\> + +Configure TCP threshold parameters + +</div> + +<div class="cfgcmd"> + +set service ids ddos-protection threshold udp +\[fps | mbps | pps\] \<0-4294967294\> + +Configure UDP threshold parameters + +</div> + +### Example + +A configuration example can be found in this section. +In this simplified scenario, main things to be considered are: + +> - Network to be protected: 192.0.2.0/24 (public IPs use by +> customers) +> - **ban-time** and **threshold**: these values are kept very low in order +> to easily identify and generate and attack. +> - Direction: **in** and **out**. Protect public network from external +> attacks, and identify internal attacks towards internet. +> - Interface **eth0** used to connect to upstream. + +Since we are analyzing attacks to and from our internal network, two types +of attacks can be identified, and differents actions are needed: + +> - External attack: an attack from the internet towards an internal IP +> is identify. In this case, all connections towards such IP will be +> blocked +> - Internal attack: an attack from the internal network (generated by a +> customer) towards the internet is identify. In this case, all connections +> from this particular IP/Customer will be blocked. + +So, firewall configuration needed for this setup: + +``` none +set firewall group address-group FNMS-DST-Block +set firewall group address-group FNMS-SRC-Block + +set firewall ipv4 forward filter rule 10 action 'drop' +set firewall ipv4 forward filter rule 10 description 'FNMS - block destination' +set firewall ipv4 forward filter rule 10 destination group address-group 'FNMS-DST-Block' + +set firewall ipv4 forward filter rule 20 action 'drop' +set firewall ipv4 forward filter rule 20 description 'FNMS - Block source' +set firewall ipv4 forward filter rule 20 source group address-group 'FNMS-SRC-Block' +``` + +Then, FastNetMon configuration: + +``` none +set service ids ddos-protection alert-script '/config/scripts/fnm-alert.sh' +set service ids ddos-protection ban-time '10' +set service ids ddos-protection direction 'in' +set service ids ddos-protection direction 'out' +set service ids ddos-protection listen-interface 'eth0' +set service ids ddos-protection mode 'mirror' +set service ids ddos-protection network '192.0.2.0/24' +set service ids ddos-protection threshold general pps '100' +``` + +And content of the script: + +``` none +#!/bin/bash + +# alert-script is called twice. +# When an attack occurs, the program calls a bash script twice: +# 1st time when threshold exceed +# 2nd when we collect 100 packets for detailed audit of what happened. + +# Do nothing if “attack_details” is passed as an argument +if [ "${4}" == "attack_details" ]; then + # Do nothing + exit +fi +# Arguments: +ip=$1 +direction=$2 +pps_rate=$3 +action=$4 + +logger -t FNMS "** Start - Running alert script **" + +if [ "${direction}" == "incoming" ] ; then + group="FNMS-DST-Block" + origin="external" +else + group="FNMS-SRC-Block" + origin="internal" +fi + +if [ "${action}" == "ban" ] ; then + logger -t FNMS "Attack detected for IP ${ip} and ${direction} direction from ${origin} network. Need to block IP address." + logger -t FNMS "Adding IP address ${ip} to firewall group ${group}." + sudo nft add element ip vyos_filter A_${group} { ${ip} } +else + logger -t FNMS "Timeout for IP ${ip}, removing it from group ${group}." + sudo nft delete element ip vyos_filter A_${group} { ${ip} } +fi +logger -t FNMS "** End - Running alert script **" +exit +``` diff --git a/docs/configuration/service/md-index.md b/docs/configuration/service/md-index.md new file mode 100644 index 00000000..420efc6d --- /dev/null +++ b/docs/configuration/service/md-index.md @@ -0,0 +1,28 @@ +# Service + +<div class="toctree" maxdepth="1" includehidden=""> + +broadcast-relay +config-sync +conntrack-sync +console-server +dhcp-relay +dhcp-server +dns +eventhandler +https +ids +ipoe-server +lldp +mdns +monitoring +ntp +pppoe-server +router-advert +salt-minion +snmp +ssh +tftp-server +webproxy + +</div> diff --git a/docs/configuration/service/md-ipoe-server.md b/docs/configuration/service/md-ipoe-server.md new file mode 100644 index 00000000..dc66163d --- /dev/null +++ b/docs/configuration/service/md-ipoe-server.md @@ -0,0 +1,656 @@ +# IPoE Server + +VyOS utilizes [accel-ppp]() to provide `IPoE (Internet Protocol over +Ethernet)` server functionality. It can be used with local authentication +(mac-address) or a connected RADIUS server. + +IPoE is a method of delivering an IP payload over an Ethernet-based access +network or an access network using bridged Ethernet over Asynchronous Transfer +Mode (ATM) without using PPPoE. It directly encapsulates the IP datagrams in +Ethernet frames, using the standard `894` encapsulation. + +The use of IPoE addresses the disadvantage that PPP is unsuited for multicast +delivery to multiple users. Typically, IPoE uses Dynamic Host Configuration +Protocol and Extensible Authentication Protocol to provide the same +functionality as PPPoE, but in a less robust manner. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Please be aware, due to an upstream bug, config changes/commits +will restart the ppp daemon and will reset existing IPoE sessions, +in order to become effective. + +</div> + +## Configuring IPoE Server + +IPoE can be configure on different interfaces, it will depend on each specific +situation which interface will provide IPoE to clients. The clients mac address +and the incoming interface is being used as control parameter, to authenticate +a client. + +The example configuration below will assign an IP to the client on the incoming +interface eth2 with the client mac address 08:00:27:2f:d8:06. Other DHCP +discovery requests will be ignored, unless the client mac has been enabled in +the configuration. + +``` none +set interfaces ethernet eth1 address '192.168.0.1/24' +set service ipoe-server authentication interface eth1.100 mac 00:50:79:66:68:00 +set service ipoe-server authentication interface eth1.101 mac 00:50:79:66:68:01 +set service ipoe-server authentication mode 'local' +set service ipoe-server client-ip-pool IPOE-POOL range '192.168.0.2-192.168.0.254' +set service ipoe-server default-pool 'IPOE-POOL' +set service ipoe-server gateway-address '192.168.0.1/24' +set service ipoe-server interface eth1 mode 'l2' +set service ipoe-server interface eth1 network 'vlan' +set service ipoe-server interface eth1 vlan '100-200' +``` + +<div class="cfgcmd"> + +set service ipoe-server authentication interface \<interface\> mac \<MAC\> + +Creates local IPoE user with username=\*\*\<interface\>\*\* and +password=\*\*\<MAC\>\*\* (mac-address) + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication mode \<local | radius\> + +Set authentication backend. The configured authentication backend is used +for all queries. + +- **radius**: All authentication queries are handled by a configured RADIUS + server. +- **local**: All authentication queries are handled locally. +- **noauth**: Authentication disabled + +</div> + +<div class="cfgcmd"> + +set service ipoe-server client-ip-pool \<POOL-NAME\> range \<x.x.x.x-x.x.x.x | x.x.x.x/x\> + +Use this command to define the first IP address of a pool of +addresses to be given to IPoE clients. If notation `x.x.x.x-x.x.x.x`, +it must be within a /24 subnet. If notation `x.x.x.x/x` is +used there is possibility to set host/netmask. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server default-pool \<POOL-NAME\> + +Use this command to define default address pool name. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server gateway-address \<x.x.x.x/x\> + +Specifies address to be used as server ip address if radius can assign +only client address. In such case if client address is matched network +and mask then specified address and mask will be used. You can specify +multiple such options. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server interface \<interface\> mode \<l2 | l3\> + +Set authentication backend. The configured authentication backend is used +for all queries. + +- **l2**: It means that clients are on same network where interface + is.\*\*(default)\*\* +- **local**: It means that client are behind some router. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server interface \<interface\> network \<shared | vlan\> + +Specify where interface is shared by multiple users or it is vlan-per-user. + +- **shared**: Multiple clients share the same network. **(default)** +- **vlan**: One VLAN per client. + +</div> + +``` none +vyos@vyos:~$ show ipoe-server sessions + + ifname | username | calling-sid | ip | rate-limit | type | comp | state | uptime +--------+----------+-------------------+-------------+------------+------+------+--------+---------- + ipoe0 | eth1.100 | 00:50:79:66:68:00 | 192.168.0.2 | | ipoe | | active | 00:04:55 + ipoe1 | eth1.101 | 00:50:79:66:68:01 | 192.168.0.3 | | ipoe | | active | 00:04:44 +``` + +## Configuring RADIUS authentication + +To enable RADIUS based authentication, the authentication mode needs to be +changed within the configuration. Previous settings like the local users, still +exists within the configuration, however they are not used if the mode has been +changed from local to radius. Once changed back to local, it will use all local +accounts again. + +``` none +set service ipoe-server authentication mode radius +``` + +<div class="cfgcmd"> + +set service ipoe-server authentication radius server \<server\> key \<secret\> + +Configure RADIUS <span class="title-ref">\<server\></span> and its required shared <span class="title-ref">\<secret\></span> for +communicating with the RADIUS server. + +</div> + +Since the RADIUS server would be a single point of failure, multiple RADIUS +servers can be setup and will be used subsequentially. +For example: + +``` none +set service ipoe-server authentication radius server 10.0.0.1 key 'foo' +set service ipoe-server authentication radius server 10.0.0.2 key 'foo' +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Some RADIUS severs use an access control list which allows or denies +queries, make sure to add your VyOS router to the allowed client list. + +</div> + +### RADIUS source address + +If you are using OSPF as IGP, always the closest interface connected to the +RADIUS server is used. With VyOS 1.2 you can bind all outgoing RADIUS requests +to a single source IP e.g. the loopback interface. + +<div class="cfgcmd"> + +set service ipoe-server authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queires. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The `source-address` must be configured on one of VyOS interface. +Best practice would be a loopback or dummy interface. + +</div> + +### RADIUS advanced options + +<div class="cfgcmd"> + +set service ipoe-server authentication radius server \<server\> port \<port\> + +Configure RADIUS <span class="title-ref">\<server\></span> and its required port for authentication requests. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication radius server \<server\> fail-time \<time\> + +Mark RADIUS server as offline for this given <span class="title-ref">\<time\></span> in seconds. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication radius server \<server\> disable + +Temporary disable this RADIUS server. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication radius acct-timeout \<timeout\> + +Timeout to wait reply for Interim-Update packets. (default 3 seconds) + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication radius dynamic-author server \<address\> + +Specifies IP address for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication radius dynamic-author port \<port\> + +Port for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication radius dynamic-author key \<secret\> + +Secret for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication radius max-try \<number\> + +Maximum number of tries to send Access-Request/Accounting-Request queries + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication radius timeout \<timeout\> + +Timeout to wait response from server (seconds) + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication radius nas-identifier \<identifier\> + +Value to send to RADIUS server in NAS-Identifier attribute and to be matched +in DM/CoA requests. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication radius nas-ip-address \<address\> + +Value to send to RADIUS server in NAS-IP-Address attribute and to be matched +in DM/CoA requests. Also DM/CoA server will bind to that address. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queires. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication radius rate-limit attribute \<attribute\> + +Specifies which RADIUS server attribute contains the rate limit information. +The default attribute is <span class="title-ref">Filter-Id</span>. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you set a custom RADIUS attribute you must define it on both +dictionaries at RADIUS server and client. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication radius rate-limit enable + +Enables bandwidth shaping via RADIUS. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication radius rate-limit vendor + +Specifies the vendor dictionary, dictionary needs to be in +/usr/share/accel-ppp/radius. + +</div> + +Received RADIUS attributes have a higher priority than parameters defined within +the CLI configuration, refer to the explanation below. + +### Allocation clients ip addresses by RADIUS + +If the RADIUS server sends the attribute `Framed-IP-Address` then this IP +address will be allocated to the client and the option `default-pool` within the CLI +config is being ignored. + +If the RADIUS server sends the attribute `Framed-Pool`, IP address will be allocated +from a predefined IP pool whose name equals the attribute value. + +If the RADIUS server sends the attribute `Stateful-IPv6-Address-Pool`, IPv6 address +will be allocated from a predefined IPv6 pool `prefix` whose name equals the attribute value. + +If the RADIUS server sends the attribute `Delegated-IPv6-Prefix-Pool`, IPv6 +delegation pefix will be allocated from a predefined IPv6 pool `delegate` +whose name equals the attribute value. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +`Stateful-IPv6-Address-Pool` and `Delegated-IPv6-Prefix-Pool` are defined in +RFC6911. If they are not defined in your RADIUS server, add new [dictionary](https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911). + +</div> + +User interface can be put to VRF context via RADIUS Access-Accept packet, or change +it via RADIUS CoA. `Accel-VRF-Name` is used from these purposes. It is custom [ACCEL-PPP attribute](https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel). +Define it in your RADIUS server. + +## IPv6 + +<div class="cfgcmd"> + +set service ipoe-server client-ipv6-pool \<IPv6-POOL-NAME\> prefix \<address\> +mask \<number-of-bits\> + +Use this comand to set the IPv6 address pool from which an IPoE client +will get an IPv6 prefix of your defined length (mask) to terminate the +IPoE endpoint at their side. The mask length can be set from 48 to 128 +bit long, the default value is 64. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server client-ipv6-pool \<IPv6-POOL-NAME\> delegate \<address\> +delegation-prefix \<number-of-bits\> + +Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on +IPoE. You will have to set your IPv6 pool and the length of the +delegation prefix. From the defined IPv6 pool you will be handing out +networks of the defined length (delegation-prefix). The length of the +delegation prefix can be set from 32 to 64 bit long. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server default-ipv6-pool \<IPv6-POOL-NAME\> + +Use this command to define default IPv6 address pool name. + +</div> + +``` none +set service ipoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' +set service ipoe-server client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' +set service ipoe-server default-ipv6-pool IPv6-POOL +``` + +## Scripting + +<div class="cfgcmd"> + +set service ipoe-server extended-scripts on-change \<path_to_script\> + +Script to run when session interface changed by RADIUS CoA handling + +</div> + +<div class="cfgcmd"> + +set service ipoe-server extended-scripts on-down \<path_to_script\> + +Script to run when session interface going to terminate + +</div> + +<div class="cfgcmd"> + +set service ipoe-server extended-scripts on-pre-up \<path_to_script\> + +Script to run before session interface comes up + +</div> + +<div class="cfgcmd"> + +set service ipoe-server extended-scripts on-up \<path_to_script\> + +Script to run when session interface is completely configured and started + +</div> + +## Advanced Options + +### Authentication Advanced Options + +<div class="cfgcmd"> + +set service ipoe-server authentication interface \<interface\> mac \<MAC\> vlan +\<vlan-id\> + +VLAN monitor for automatic creation of VLAN interfaces for specific user on specific \<interface\> + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication interface \<interface\> mac \<MAC\> rate-limit +download \<bandwidth\> + +Download bandwidth limit in kbit/s for user on interface <span class="title-ref">\<interface\></span>. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server authentication interface \<interface\> mac \<MAC\> rate-limit +upload \<bandwidth\> + +Upload bandwidth limit in kbit/s for for user on interface <span class="title-ref">\<interface\></span>. + +</div> + +### Client IP Pool Advanced Options + +<div class="cfgcmd"> + +set service ipoe-server client-ip-pool \<POOL-NAME\> next-pool \<NEXT-POOL-NAME\> + +Use this command to define the next address pool name. + +</div> + +### Advanced Interface Options + +<div class="cfgcmd"> + +set service ipoe-server interface \<interface\> client-subnet \<x.x.x.x/x\> + +Specify local range of ip address to give to dhcp clients. First IP in range is router IP. +If you need more customization use <span class="title-ref">client-ip-pool</span> + +</div> + +<div class="cfgcmd"> + +set service ipoe-server interface \<interface\> external-dhcp dhcp-relay \<x.x.x.x\> + +Specify DHCPv4 relay IP address to pass requests to. If specified giaddr is also needed. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server interface \<interface\> external-dhcp giaddr \<x.x.x.x\> + +Specifies relay agent IP addre + +</div> + +### Global Advanced options + +<div class="cfgcmd"> + +set service ipoe-server description \<description\> + +Set description. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server limits burst \<value\> + +Burst count + +</div> + +<div class="cfgcmd"> + +set service ipoe-server limits connection-limit \<value\> + +Acceptable rate of connections (e.g. 1/min, 60/sec) + +</div> + +<div class="cfgcmd"> + +set service ipoe-server limits timeout \<value\> + +Timeout in seconds + +</div> + +<div class="cfgcmd"> + +set service ipoe-server max-concurrent-sessions + +Maximum number of concurrent session start attempts + +</div> + +<div class="cfgcmd"> + +set service ipoe-server name-server \<address\> + +Connected client should use <span class="title-ref">\<address\></span> as their DNS server. This +command accepts both IPv4 and IPv6 addresses. Up to two nameservers +can be configured for IPv4, up to three for IPv6. + +</div> + +<div class="cfgcmd"> + +set service ipoe-server shaper fwmark \<1-2147483647\> + +Match firewall mark value + +</div> + +<div class="cfgcmd"> + +set service ipoe-server snmp master-agent + +Enable SNMP + +</div> + +## Monitoring + +<div class="opcmd"> + +show ipoe-server sessions + +Use this command to locally check the active sessions in the IPoE +server. + +</div> + +``` none +vyos@vyos:~$ show ipoe-server sessions +ifname | username | calling-sid | ip | rate-limit | type | comp | state | uptime +----------+----------+-------------------+-------------+------------+------+------+--------+---------- + eth1.100 | eth1.100 | 0c:98:bd:b8:00:01 | 192.168.0.3 | | ipoe | | active | 03:03:58 +``` + +``` none +vyos@vyos:~$ show ipoe-server statistics +uptime: 0.03:31:36 +cpu: 0% +mem(rss/virt): 6044/101360 kB +core: + mempool_allocated: 148628 + mempool_available: 144748 + thread_count: 1 + thread_active: 1 + context_count: 10 + context_sleeping: 0 + context_pending: 0 + md_handler_count: 6 + md_handler_pending: 0 + timer_count: 1 + timer_pending: 0 +sessions: + starting: 0 + active: 1 + finishing: 0 +ipoe: + starting: 0 + active: 1 + delayed: 0 +``` + +## Toubleshooting + +``` none +vyos@vyos:~$sudo journalctl -u accel-ppp@ipoe -b 0 + +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:: recv [DHCPv4 Discover xid=55df9228 chaddr=0c:98:bd:b8:00:01 <Message-Type Discover> <Request-IP 192.168.0.3> <Host-Name vyos> <Request-List Subnet,Broadcast,Router,DNS,Classless-Route,Domain-Name,MTU>] +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: eth1.100: authentication succeeded +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: send [DHCPv4 Offer xid=55df9228 yiaddr=192.168.0.4 chaddr=0c:98:bd:b8:00:01 <Message-Type Offer> <Server-ID 192.168.0.1> <Lease-Time 600> <T1 300> <T2 525> <Router 192.168.0.1> <Subnet 255.255.255.0>] +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: recv [DHCPv4 Request xid=55df9228 chaddr=0c:98:bd:b8:00:01 <Message-Type Request> <Server-ID 192.168.0.1> <Request-IP 192.168.0.4> <Host-Name vyos> <Request-List Subnet,Broadcast,Router,DNS,Classless-Route,Domain-Name,MTU>] +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: ipoe: activate session +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: ipoe: no free IPv6 address +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: ipoe: session started +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: send [DHCPv4 Ack xid=55df9228 yiaddr=192.168.0.4 chaddr=0c:98:bd:b8:00:01 <Message-Type Ack> <Server-ID 192.168.0.1> <Lease-Time 600> <T1 300> <T2 525> <Router 192.168.0.1> <Subnet 255.255.255.0>] +``` diff --git a/docs/configuration/service/md-lldp.md b/docs/configuration/service/md-lldp.md new file mode 100644 index 00000000..84d734a0 --- /dev/null +++ b/docs/configuration/service/md-lldp.md @@ -0,0 +1,176 @@ +# LLDP + +`LLDP (Link Layer Discovery Protocol)` is a vendor-neutral link layer +protocol in the Internet Protocol Suite used by network devices for advertising +their identity, capabilities, and neighbors on an IEEE 802 local area network, +principally wired Ethernet. The protocol is formally referred to by the IEEE +as Station and Media Access Control Connectivity Discovery specified in IEEE +802.1AB and IEEE 802.3-2012 section 6 clause 79. + +LLDP performs functions similar to several proprietary protocols, such as +`CDP (Cisco Discovery Protocol)`, +`FDP (Foundry Discovery Protocol)`, +`NDP (Nortel Discovery Protocol)` and `LLTD (Link Layer Topology +Discovery)`. + +Information gathered with LLDP is stored in the device as a `MIB +(Management Information Database)` and can be queried with `SNMP (Simple +Network Management Protocol)` as specified in `2922`. The topology of an +LLDP-enabled network can be discovered by crawling the hosts and querying this +database. Information that may be retrieved include: + +- System Name and Description +- Port name and description +- VLAN name +- IP management address +- System capabilities (switching, routing, etc.) +- MAC/PHY information +- MDI power +- Link aggregation + +## Configuration + +<div class="cfgcmd"> + +set service lldp + +Enable LLDP service + +</div> + +<div class="cfgcmd"> + +set service lldp management-address \<address\> + +Define IPv4/IPv6 management address transmitted via LLDP. Multiple addresses +can be defined. Only addresses connected to the system will be transmitted. + +</div> + +<div class="cfgcmd"> + +set service lldp interface \<interface\> + +Enable transmission of LLDP information on given <span class="title-ref">\<interface\></span>. You can also +say `all` here so LLDP is turned on on every interface. + +</div> + +<div class="cfgcmd"> + +set service lldp interface \<interface\> disable + +Disable transmit of LLDP frames on given <span class="title-ref">\<interface\></span>. Useful to exclude +certain interfaces from LLDP when `all` have been enabled. + +</div> + +<div class="cfgcmd"> + +set service lldp snmp + +Enable SNMP queries of the LLDP database + +</div> + +<div class="cfgcmd"> + +set service lldp legacy-protocols \<cdp[|edp|](##SUBST##|edp|)fdp|sonmp\> + +Enable given legacy protocol on this LLDP instance. Legacy protocols include: + +- `cdp` - Listen for CDP for Cisco routers/switches +- `edp` - Listen for EDP for Extreme routers/switches +- `fdp` - Listen for FDP for Foundry routers/switches +- `sonmp` - Listen for SONMP for Nortel routers/switches + +</div> + +## Operation + +<div class="opcmd"> + +show lldp neighbors + +Displays information about all neighbors discovered via LLDP. + +``` none +vyos@vyos:~$ show lldp neighbors +Capability Codes: R - Router, B - Bridge, W - Wlan r - Repeater, S - Station + D - Docsis, T - Telephone, O - Other + +Device ID Local Proto Cap Platform Port ID +--------- ----- ----- --- -------- ------- +BR2.vyos.net eth0 LLDP R VyOS 1.2.4 eth1 +BR3.vyos.net eth0 LLDP RB VyOS 1.2.4 eth2 +SW1.vyos.net eth0 LLDP B Cisco IOS Software GigabitEthernet0/6 +``` + +</div> + +<div class="opcmd"> + +show lldp neighbors detail + +Get detailed information about LLDP neighbors. + +``` none +vyos@vyos:~$ show lldp neighbors detail +------------------------------------------------------------------------------- +LLDP neighbors: +------------------------------------------------------------------------------- +Interface: eth0, via: LLDP, RID: 28, Time: 0 day, 00:24:33 + Chassis: + ChassisID: mac 00:53:00:01:02:c9 + SysName: BR2.vyos.net + SysDescr: VyOS 1.3-rolling-201912230217 + MgmtIP: 192.0.2.1 + MgmtIP: 2001:db8::ffff + Capability: Bridge, on + Capability: Router, on + Capability: Wlan, off + Capability: Station, off + Port: + PortID: mac 00:53:00:01:02:c9 + PortDescr: eth0 + TTL: 120 + PMD autoneg: supported: no, enabled: no + MAU oper type: 10GigBaseCX4 - X copper over 8 pair 100-Ohm balanced cable + VLAN: 201 eth0.201 + VLAN: 205 eth0.205 + LLDP-MED: + Device Type: Network Connectivity Device + Capability: Capabilities, yes + Capability: Policy, yes + Capability: Location, yes + Capability: MDI/PSE, yes + Capability: MDI/PD, yes + Capability: Inventory, yes + Inventory: + Hardware Revision: None + Software Revision: 4.19.89-amd64-vyos + Firmware Revision: 6.00 + Serial Number: VMware-42 1d 83 b9 fe c1 bd b2-7 + Manufacturer: VMware, Inc. + Model: VMware Virtual Platform + Asset ID: No Asset Tag +------------------------------------------------------------------------------- +``` + +</div> + +<div class="opcmd"> + +show lldp neighbors interface \<interface\> + +Show LLDP neighbors connected via interface <span class="title-ref">\<interface\></span>. + +</div> + +<div class="opcmd"> + +show log lldp + +Used for troubleshooting. + +</div> diff --git a/docs/configuration/service/md-mdns.md b/docs/configuration/service/md-mdns.md new file mode 100644 index 00000000..504843d4 --- /dev/null +++ b/docs/configuration/service/md-mdns.md @@ -0,0 +1,162 @@ +# mDNS Repeater + +Starting with VyOS 1.2 a `mDNS (Multicast DNS)` repeater functionality is +provided. Additional information can be obtained from +<https://en.wikipedia.org/wiki/Multicast_DNS>. + +Multicast DNS uses the reserved address `224.0.0.251`, which is +<span class="title-ref">"administratively scoped"</span> and does not leave the subnet. mDNS repeater +retransmits mDNS packets from one interface to other interfaces. This enables +support for devices using mDNS discovery (like network printers, Apple Airplay, +Chromecast, various IP based home-automation devices etc) across multiple VLANs. + +Since the mDNS protocol sends the `AA(Authoritative Answer)` records in +the packet itself, the repeater does not need to forge the source address. +Instead, the source address is of the interface that repeats the packet. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +You can not run this in a VRRP setup, if multiple mDNS repeaters +are launched in a subnet you will experience the mDNS packet storm death! + +</div> + +## Configuration + +<div class="cfgcmd"> + +set service mdns repeater interface \<interface\> + +To enable mDNS repeater you need to configure at least two interfaces so that +all incoming mDNS packets from one interface configured here can be +re-broadcasted to any other interface(s) configured under this section. + +</div> + +<div class="cfgcmd"> + +set service mdns repeater disable + +mDNS repeater can be temporarily disabled without deleting the service using + +</div> + +<div class="cfgcmd"> + +set service mdns repeater ip-version \<ipv4 | ipv6 | both\> + +mDNS repeater can be enabled either on IPv4 socket or on IPv6 socket or both +to re-broadcast. By default, mDNS repeater will listen on both IPv4 and IPv6. + +</div> + +<div class="cfgcmd"> + +set service mdns repeater allow-service \<service\> + +mDNS repeater can be configured to re-broadcast only specific services. By +default, all services are re-broadcasted. + +</div> + +<div class="cfgcmd"> + +set service mdns repeater browse-domain \<domain\> + +Allow listing additional custom domains to be browsed (in addition to the +default `local`) so that they can be reflected. + +</div> + +<div class="cfgcmd"> + +set service mdns repeater cache-entries \<entries\> + +Specify how many resource records are cached per interface. Bigger values +allow mDNS work correctly in large LANs but also increase memory consumption. + +Defaults to: 4096 + +</div> + +## Firewall recommendations + +Unlike typical routed traffic, mDNS packets relayed between interfaces do not +traverse the FORWARD hook chain in the firewall. Instead, they are processed +through the following hooks: + +> - **INPUT**: For packets received by the local system +> - **OUTPUT**: For packets sent from the local system + +To control or allow mDNS packet forwarding via the relay, you must define +appropriate rules in the INPUT and OUTPUT directions. Rules in the FORWARD +direction will have no effect on mDNS relay traffic. + +``` none +set firewall ipv4 input filter rule 10 action 'accept' +set firewall ipv4 input filter rule 10 destination address '224.0.0.251' +set firewall ipv4 input filter rule 10 destination port '5353' +set firewall ipv4 input filter rule 10 protocol 'udp' +set firewall ipv4 output filter rule 10 action 'accept' +set firewall ipv4 output filter rule 10 destination address '224.0.0.251' +set firewall ipv4 output filter rule 10 destination port '5353' +set firewall ipv4 output filter rule 10 protocol 'udp' +``` + +## Example + +To listen on both <span class="title-ref">eth0</span> and <span class="title-ref">eth1</span> mDNS packets and also repeat packets +received on <span class="title-ref">eth0</span> to <span class="title-ref">eth1</span> (and vice-versa) use the following commands: + +``` none +set service mdns repeater interface 'eth0' +set service mdns repeater interface 'eth1' +``` + +To allow only specific services, for example `_airplay._tcp` or `_ipp._tcp`, +(instead of all services) to be re-broadcasted, use the following command: + +``` none +set service mdns repeater allow-service '_airplay._tcp' +set service mdns repeater allow-service '_ipp._tcp' +``` + +To allow listing additional custom domain, for example +`openthread.thread.home.arpa`, so that it can reflected in addition to the +default `local`, use the following command: + +``` none +set service mdns repeater browse-domain 'openthread.thread.home.arpa' +``` + +## Operation + +<div class="opcmd"> + +restart mdns repeater + +Restart mDNS repeater service. + +</div> + +<div class="opcmd"> + +show log mdns repeater + +Show logs for mDNS repeater service. + +</div> + +<div class="opcmd"> + +monitor log mdns repeater + +Follow the logs for mDNS repeater service. + +</div> diff --git a/docs/configuration/service/md-monitoring.md b/docs/configuration/service/md-monitoring.md new file mode 100644 index 00000000..8dff341a --- /dev/null +++ b/docs/configuration/service/md-monitoring.md @@ -0,0 +1,230 @@ +# Monitoring + +## Azure-data-explorer + +Telegraf output plugin [azure-data-explorer](https://github.com/influxdata/telegraf/tree/master/plugins/outputs/azure_data_explorer) + +<div class="cfgcmd"> + +set service monitoring telegraf azure-data-explorer authentication client-id \<client-id\> + +Authentication application client-id. + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf azure-data-explorer authentication client-secret \<client-secret\> + +Authentication application client-secret. + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf azure-data-explorer authentication tenant-id \<tenant-id\> + +Authentication application tenant-id + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf azure-data-explorer database \<name\> + +Remote database name. + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf azure-data-explorer group-metrics \<single-table | table-per-metric\> + +Type of metrics grouping when push to Azure Data Explorer. The default is +`table-per-metric`. + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf azure-data-explorer table \<name\> + +Name of the single table Only if set group-metrics single-table. + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf azure-data-explorer url \<url\> + +Remote URL. + +</div> + +## Prometheus-client + +Telegraf output plugin [prometheus-client](https://github.com/influxdata/telegraf/tree/master/plugins/outputs/prometheus_client) + +<div class="cfgcmd"> + +set service monitoring telegraf prometheus-client + +Output plugin Prometheus client + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf prometheus-client allow-from \<prefix\> + +Networks allowed to query this server + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf prometheus-client authentication username \<username\> + +HTTP basic authentication username + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf prometheus-client authentication password \<password\> + +HTTP basic authentication username + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf prometheus-client listen-address \<address\> + +Local IP addresses to listen on + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf prometheus-client metric-version \<1 | 2\> + +Metris version, the default is `2` + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf prometheus-client port \<port\> + +Port number used by connection, default is `9273` + +</div> + +Example: + +``` none +set service monitoring telegraf prometheus-client +``` + +``` none +vyos@r14:~$ curl --silent localhost:9273/metrics | egrep -v "#" | grep cpu_usage_system +cpu_usage_system{cpu="cpu-total",host="r14"} 0.20040080160320556 +cpu_usage_system{cpu="cpu0",host="r14"} 0.17182130584191915 +cpu_usage_system{cpu="cpu1",host="r14"} 0.22896393817971655 +``` + +## Splunk + +Telegraf output plugin [splunk](https://www.splunk.com/en_us/blog/it/splunk-metrics-via-telegraf.html). HTTP Event Collector. + +<div class="cfgcmd"> + +set service monitoring telegraf splunk authentication insecure + +Use TLS but skip host validation + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf splunk authentication token \<token\> + +Authorization token + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf splunk authentication url \<url\> + +Remote URL to Splunk collector + +</div> + +Example: + +``` none +set service monitoring telegraf splunk authentication insecure +set service monitoring telegraf splunk authentication token 'xxxxf5b8-xxxx-452a-xxxx-43828911xxxx' +set service monitoring telegraf splunk url 'https://192.0.2.10:8088/services/collector' +``` + +## Telegraf + +Monitoring functionality with `telegraf` and `InfluxDB 2` is provided. +Telegraf is the open source server agent to help you collect metrics, events +and logs from your routers. + +<div class="cfgcmd"> + +set service monitoring telegraf influxdb authentication organization \<organization\> + +Authentication organization name + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf influxdb authentication token \<token\> + +Authentication token + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf bucket \<bucket\> + +Remote `InfluxDB` bucket name + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf influxdb port \<port\> + +Remote port + +</div> + +<div class="cfgcmd"> + +set service monitoring telegraf influxdb url \<url\> + +Remote URL + +</div> + +## Example + +An example of a configuration that sends `telegraf` metrics to remote +`InfluxDB 2` + +``` none +set service monitoring telegraf influxdb authentication organization 'vyos' +set service monitoring telegraf influxdb authentication token 'ZAml9Uy5wrhA...==' +set service monitoring telegraf influxdb bucket 'bucket_vyos' +set service monitoring telegraf influxdb port '8086' +set service monitoring telegraf influxdb url 'http://r1.influxdb2.local' +``` diff --git a/docs/configuration/service/md-ntp.md b/docs/configuration/service/md-ntp.md new file mode 100644 index 00000000..871f5fec --- /dev/null +++ b/docs/configuration/service/md-ntp.md @@ -0,0 +1,136 @@ +# NTP + +`NTP (Network Time Protocol`) is a networking protocol for clock +synchronization between computer systems over packet-switched, variable-latency +data networks. In operation since before 1985, NTP is one of the oldest Internet +protocols in current use. + +NTP is intended to synchronize all participating computers to within a few +milliseconds of `UTC (Coordinated Universal Time)`. It uses the +intersection algorithm, a modified version of Marzullo's algorithm, to select +accurate time servers and is designed to mitigate the effects of variable +network latency. NTP can usually maintain time to within tens of milliseconds +over the public Internet, and can achieve better than one millisecond accuracy +in local area networks under ideal conditions. Asymmetric routes and network +congestion can cause errors of 100 ms or more. + +The protocol is usually described in terms of a client-server model, but can as +easily be used in peer-to-peer relationships where both peers consider the other +to be a potential time source. Implementations send and receive timestamps using +`UDP (User Datagram Protocol)` on port number 123. + +NTP supplies a warning of any impending leap second adjustment, but no +information about local time zones or daylight saving time is transmitted. + +The current protocol is version 4 (NTPv4), which is a proposed standard as +documented in `5905`. It is backward compatible with version 3, specified +in `1305`. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +VyOS 1.4 uses chrony instead of ntpd (see `T3008`) which will +no longer accept anonymous NTP requests as in VyOS 1.3. All configurations +will be migrated to keep the anonymous functionality. For new setups if you +have clients using your VyOS installation as NTP server, you must specify +the <span class="title-ref">allow-client</span> directive. + +</div> + +## Configuration + +<div class="cfgcmd"> + +set service ntp server \<address\> + +Configure one or more servers for synchronisation. Server name can be either +an IP address or `FQDN (Fully Qualified Domain Name)`. + +There are 3 default NTP server set. You are able to change them. + +- `time1.vyos.net` +- `time2.vyos.net` +- `time3.vyos.net` + +</div> + +<div class="cfgcmd"> + +set service ntp server \<address\> \<noselect | nts | pool | prefer\> + +Configure one or more attributes to the given NTP server. + +- `noselect` marks the server as unused, except for display purposes. The + server is discarded by the selection algorithm. +- `nts` enables Network Time Security (NTS) for the server as specified + in `8915` +- `pool` mobilizes persistent client mode association with a number of + remote servers. +- `prefer` marks the server as preferred. All other things being equal, + this host will be chosen for synchronization among a set of correctly + operating hosts. + +</div> + +<div class="cfgcmd"> + +set service ntp listen-address \<address\> + +NTP process will only listen on the specified IP address. You must specify +the <span class="title-ref">\<address\></span> and optionally the permitted clients. Multiple listen +addresses for same IP family is no longer supported. Only one IPv4 and one +IPv6 address can be configured, using separate commands for each. + +</div> + +<div class="cfgcmd"> + +set service ntp allow-client address \<address\> + +List of networks or client addresses permitted to contact this NTP server. + +Multiple networks/client IP addresses can be configured. + +</div> + +<div class="cfgcmd"> + +set service ntp vrf \<name\> + +Specify name of the `VRF (Virtual Routing and Forwarding)` instance. + +</div> + +<div class="cfgcmd"> + +set service ntp leap-second \[ignore[|smear|](##SUBST##|smear|)system|timezone\] + +Define how to handle leap-seconds. + +- \`ignore\`: No correction is applied to the clock for the leap second. The + clock will be corrected later in normal operation when new measurements are + made and the estimated offset includes the one second error. +- \`smear\`: When smearing a leap second, the leap status is suppressed on the + server and the served time is corrected slowly by slewing instead of + stepping. The clients do not need any special configuration as they do not + know there is any leap second and they follow the server time which + eventually brings them back to UTC. Care must be taken to ensure they use + only NTP servers which smear the leap second in exactly the same way for + synchronisation. +- \`system\`: When inserting a leap second, the kernel steps the system clock + backwards by one second when the clock gets to 00:00:00 UTC. When deleting + a leap second, it steps forward by one second when the clock gets to + 23:59:59 UTC. +- \`timezone\`: This directive specifies a timezone in the system timezone + database which chronyd can use to determine when will the next leap second + occur and what is the current offset between TAI and UTC. It will + periodically check if 23:59:59 and 23:59:60 are valid times in the + timezone. This normally works with the right/UTC timezone which is the + default + +</div> diff --git a/docs/configuration/service/md-pppoe-server.md b/docs/configuration/service/md-pppoe-server.md new file mode 100644 index 00000000..3c77e425 --- /dev/null +++ b/docs/configuration/service/md-pppoe-server.md @@ -0,0 +1,957 @@ +lastproofread +2022-09-17 + +# PPPoE Server + +VyOS utilizes [accel-ppp]() to provide PPPoE server functionality. It can +be used with local authentication or a connected RADIUS server. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Please be aware, due to an upstream bug, config +changes/commits will restart the ppp daemon and will reset existing +PPPoE connections from connected users, in order to become effective. + +</div> + +## Configuring PPPoE Server + +``` none +set service pppoe-server access-concentrator PPPoE-Server +set service pppoe-server authentication mode local +set service pppoe-server authentication local-users username test password 'test' +set service pppoe-server client-ip-pool PPPOE-POOL range 192.168.255.2-192.168.255.254 +set service pppoe-server default-pool 'PPPOE-POOL' +set service pppoe-server gateway-address 192.168.255.1 +set service pppoe-server interface eth0 +``` + +<div class="cfgcmd"> + +set service pppoe-server access-concentrator \<name\> + +Use this command to set a name for this PPPoE-server access +concentrator. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication mode \<local | radius\> + +Set authentication backend. The configured authentication backend is used +for all queries. + +- **radius**: All authentication queries are handled by a configured RADIUS + server. +- **local**: All authentication queries are handled locally. +- **noauth**: Authentication disabled. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication local-users username +\<name\> password \<password\> + +Create <span class="title-ref">\<user\></span> for local authentication on this system. The users password +will be set to <span class="title-ref">\<pass\></span>. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server client-ip-pool \<POOL-NAME\> +range \<x.x.x.x-x.x.x.x | x.x.x.x/x\> + +Use this command to define the first IP address of a pool of +addresses to be given to pppoe clients. If notation `x.x.x.x-x.x.x.x`, +it must be within a /24 subnet. If notation `x.x.x.x/x` is +used there is possibility to set host/netmask. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server default-pool \<POOL-NAME\> + +Use this command to define default address pool name. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server interface \<interface\> + +Use this command to define the interface the PPPoE server will use to +listen for PPPoE clients. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server gateway-address \<address\> + +Specifies single <span class="title-ref">\<gateway\></span> IP address to be used as local address of PPP +interfaces. + +</div> + +## Configuring RADIUS authentication + +To enable RADIUS based authentication, the authentication mode needs to be +changed within the configuration. Previous settings like the local users, still +exists within the configuration, however they are not used if the mode has been +changed from local to radius. Once changed back to local, it will use all local +accounts again. + +``` none +set service pppoe-server authentication mode radius +``` + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +server \<server\> key \<secret\> + +Configure RADIUS <span class="title-ref">\<server\></span> and its required shared <span class="title-ref">\<secret\></span> for +communicating with the RADIUS server. + +</div> + +Since the RADIUS server would be a single point of failure, multiple RADIUS +servers can be setup and will be used subsequentially. +For example: + +``` none +set service pppoe-server authentication radius server 10.0.0.1 key 'foo' +set service pppoe-server authentication radius server 10.0.0.2 key 'foo' +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Some RADIUS severs use an access control list which allows or denies +queries, make sure to add your VyOS router to the allowed client list. + +</div> + +### RADIUS source address + +If you are using OSPF as IGP, always the closest interface connected to the +RADIUS server is used. With VyOS 1.2 you can bind all outgoing RADIUS requests +to a single source IP e.g. the loopback interface. + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +source-address \<address\> + +Source IPv4 address used in all RADIUS server queires. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The `source-address` must be configured on one of VyOS interface. +Best practice would be a loopback or dummy interface. + +</div> + +### RADIUS advanced options + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +server \<server\> port \<port\> + +Configure RADIUS <span class="title-ref">\<server\></span> and its required port for authentication requests. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +server \<server\> fail-time \<time\> + +Mark RADIUS server as offline for this given <span class="title-ref">\<time\></span> in seconds. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +server \<server\> disable + +Temporary disable this RADIUS server. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +acct-timeout \<timeout\> + +Timeout to wait reply for Interim-Update packets. (default 3 seconds) + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +dynamic-author server \<address\> + +Specifies IP address for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +dynamic-author port \<port\> + +Port for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication radius dynamic-author +key \<secret\> + +Secret for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +max-try \<number\> + +Maximum number of tries to send Access-Request/Accounting-Request queries + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +timeout \<timeout\> + +Timeout to wait response from server (seconds) + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +nas-identifier \<identifier\> + +Value to send to RADIUS server in NAS-Identifier attribute and to be matched +in DM/CoA requests. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +nas-ip-address \<address\> + +Value to send to RADIUS server in NAS-IP-Address attribute and to be matched +in DM/CoA requests. Also DM/CoA server will bind to that address. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +source-address \<address\> + +Source IPv4 address used in all RADIUS server queires. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +rate-limit attribute \<attribute\> + +Specifies which RADIUS server attribute contains the rate limit information. +The default attribute is `Filter-Id`. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you set a custom RADIUS attribute you must define it on both +dictionaries at RADIUS server and client. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +rate-limit enable + +Enables bandwidth shaping via RADIUS. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication radius +rate-limit vendor + +Specifies the vendor dictionary, dictionary needs to be in +/usr/share/accel-ppp/radius. + +</div> + +Received RADIUS attributes have a higher priority than parameters defined within +the CLI configuration, refer to the explanation below. + +### Allocation clients ip addresses by RADIUS + +If the RADIUS server sends the attribute `Framed-IP-Address` then this IP +address will be allocated to the client and the option `default-pool` +within the CLI config is being ignored. + +If the RADIUS server sends the attribute `Framed-Pool`, IP address will +be allocated from a predefined IP pool whose name equals the attribute value. + +If the RADIUS server sends the attribute `Stateful-IPv6-Address-Pool`, +IPv6 address will be allocated from a predefined IPv6 pool `prefix` +whose name equals the attribute value. + +If the RADIUS server sends the attribute `Delegated-IPv6-Prefix-Pool`, +IPv6 delegation pefix will be allocated from a predefined IPv6 pool `delegate` +whose name equals the attribute value. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +`Stateful-IPv6-Address-Pool` and `Delegated-IPv6-Prefix-Pool` +are defined in RFC6911. If they are not defined in your RADIUS server, +add new [dictionary](https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911). + +</div> + +User interface can be put to VRF context via RADIUS Access-Accept packet, +or change it via RADIUS CoA. `Accel-VRF-Name` is used from these purposes. +It is custom [ACCEL-PPP attribute](https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel). Define it in your RADIUS server. + +### Renaming clients interfaces by RADIUS + +If the RADIUS server uses the attribute `NAS-Port-Id`, ppp tunnels will be +renamed. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The value of the attribute `NAS-Port-Id` must be less than 16 +characters, otherwise the interface won't be renamed. + +</div> + +## Automatic VLAN Creation + +<div class="cfgcmd"> + +set service pppoe-server interface \<interface\> vlan \<id | range\> + +VLAN's can be created by Accel-ppp on the fly via the use of a Kernel module +named `vlan_mon`, which is monitoring incoming vlans and creates the +necessary VLAN if required and allowed. VyOS supports the use of either +VLAN ID's or entire ranges, both values can be defined at the same time for +an interface. + +When configured, PPPoE will create the necessary VLANs when required. Once +the user session has been cancelled and the VLAN is not needed anymore, VyOS +will remove it again. + +</div> + +``` none +set service pppoe-server interface eth3 vlan 100 +set service pppoe-server interface eth3 vlan 200 +set service pppoe-server interface eth3 vlan 500-1000 +set service pppoe-server interface eth3 vlan 2000-3000 +``` + +## Bandwidth Shaping + +Bandwidth rate limits can be set for local users or RADIUS based +attributes. + +### For Local Users + +<div class="cfgcmd"> + +set service pppoe-server authentication local-users username +\<user\> rate-limit download \<bandwidth\> + +Download bandwidth limit in kbit/s for <span class="title-ref">\<user\></span>. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication local-users username +\<user\> rate-limit upload \<bandwidth\> + +Upload bandwidth limit in kbit/s for <span class="title-ref">\<user\></span>. + +</div> + +``` none +set service pppoe-server access-concentrator 'ACN' +set service pppoe-server authentication local-users username foo password 'bar' +set service pppoe-server authentication local-users username foo rate-limit download '20480' +set service pppoe-server authentication local-users username foo rate-limit upload '10240' +set service pppoe-server authentication mode 'local' +set service pppoe-server client-ip-pool IP-POOL range '10.1.1.100/24' +set service pppoe-server default-pool 'IP-POOL' +set service pppoe-server name-server '10.100.100.1' +set service pppoe-server name-server '10.100.200.1' +set service pppoe-server interface 'eth1' +set service pppoe-server gateway-address '10.1.1.2' +``` + +Once the user is connected, the user session is using the set limits and +can be displayed via `show pppoe-server sessions`. + +``` none +show pppoe-server sessions +ifname | username | ip | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes +-------+----------+------------+-------------------+-------------+--------+----------+----------+---------- +ppp0 | foo | 10.1.1.100 | 00:53:00:ba:db:15 | 20480/10240 | active | 00:00:11 | 214 B | 76 B +``` + +### For RADIUS users + +The current attribute `Filter-Id` is being used as default and can be +setup within RADIUS: + +Filter-Id=2000/3000 (means 2000Kbit down-stream rate and 3000Kbit +up-stream rate) + +The command below enables it, assuming the RADIUS connection has been +setup and is working. + +<div class="cfgcmd"> + +set service pppoe-server authentication radius rate-limit enable + +Use this command to enable bandwidth shaping via RADIUS. + +</div> + +Other attributes can be used, but they have to be in one of the +dictionaries in */usr/share/accel-ppp/radius*. + +## Load Balancing + +<div class="cfgcmd"> + +set service pppoe-server pado-delay \<number-of-ms\> +sessions \<number-of-sessions\> + +Use this command to enable the delay of PADO (PPPoE Active Discovery +Offer) packets, which can be used as a session balancing mechanism +with other PPPoE servers. + +</div> + +``` none +set service pppoe-server pado-delay 50 sessions '500' +set service pppoe-server pado-delay 100 sessions '1000' +set service pppoe-server pado-delay 300 sessions '3000' +``` + +In the example above, the first 499 sessions connect without delay. PADO +packets will be delayed 50 ms for connection from 500 to 999, this trick +allows other PPPoE servers send PADO faster and clients will connect to +other servers. Last command says that this PPPoE server can serve only +3000 clients. + +## IPv6 + +<div class="cfgcmd"> + +set service pppoe-server ppp-options +ipv6 \<require | prefer | allow | deny\> + +Specifies IPv6 negotiation preference. + +- **require** - Require IPv6 negotiation +- **prefer** - Ask client for IPv6 negotiation, do not fail if it rejects +- **allow** - Negotiate IPv6 only if client requests +- **deny** - Do not negotiate IPv6 (default value) + +</div> + +<div class="cfgcmd"> + +set service pppoe-server client-ipv6-pool \<IPv6-POOL-NAME\> +prefix \<address\> mask \<number-of-bits\> + +Use this comand to set the IPv6 address pool from which an PPPoE client +will get an IPv6 prefix of your defined length (mask) to terminate the +PPPoE endpoint at their side. The mask length can be set from 48 to 128 +bit long, the default value is 64. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server client-ipv6-pool \<IPv6-POOL-NAME\> +delegate \<address\> delegation-prefix \<number-of-bits\> + +Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on +PPPoE. You will have to set your IPv6 pool and the length of the +delegation prefix. From the defined IPv6 pool you will be handing out +networks of the defined length (delegation-prefix). The length of the +delegation prefix can be set from 32 to 64 bit long. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server default-ipv6-pool \<IPv6-POOL-NAME\> + +Use this command to define default IPv6 address pool name. + +</div> + +``` none +set service pppoe-server ppp-options ipv6 allow +set service pppoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' +set service pppoe-server client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' +set service pppoe-server default-ipv6-pool IPv6-POOL +``` + +### IPv6 Advanced Options + +<div class="cfgcmd"> + +set service pppoe-server ppp-options ipv6-accept-peer-interface-id + +Accept peer interface identifier. By default is not defined. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server ppp-options ipv6-interface-id +\<random | x:x:x:x\> + +Specifies fixed or random interface identifier for IPv6. +By default is fixed. + +- **random** - Random interface identifier for IPv6 +- **x:x:x:x** - Specify interface identifier for IPv6 + +</div> + +<div class="cfgcmd"> + +set service pppoe-server ppp-options ipv6-interface-id +\<random | x:x:x:x\> + +Specifies peer interface identifier for IPv6. By default is fixed. + +- **random** - Random interface identifier for IPv6 +- **x:x:x:x** - Specify interface identifier for IPv6 +- **ipv4-addr** - Calculate interface identifier from IPv4 address. +- **calling-sid** - Calculate interface identifier from calling-station-id. + +</div> + +## Scripting + +<div class="cfgcmd"> + +set service pppoe-server extended-scripts on-change \<path_to_script\> + +Script to run when session interface changed by RADIUS CoA handling + +</div> + +<div class="cfgcmd"> + +set service pppoe-server extended-scripts on-down \<path_to_script\> + +Script to run when session interface going to terminate + +</div> + +<div class="cfgcmd"> + +set service pppoe-server extended-scripts on-pre-up \<path_to_script\> + +Script to run before session interface comes up + +</div> + +<div class="cfgcmd"> + +set service pppoe-server extended-scripts on-up \<path_to_script\> + +Script to run when session interface is completely configured and started + +</div> + +## Advanced Options + +### Authentication Advanced Options + +<div class="cfgcmd"> + +set service pppoe-server authentication local-users +username \<user\> disable + +Disable <span class="title-ref">\<user\></span> account. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication local-users +username \<user\> static-ip \<address\> + +Assign static IP address to <span class="title-ref">\<user\></span> account. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server authentication protocols +\<pap | chap | mschap | mschap-v2\> + +Require the peer to authenticate itself using one of the following protocols: +pap, chap, mschap, mschap-v2. + +</div> + +### Client IP Pool Advanced Options + +<div class="cfgcmd"> + +set service pppoe-server client-ip-pool \<POOL-NAME\> +next-pool \<NEXT-POOL-NAME\> + +Use this command to define the next address pool name. + +</div> + +### PPP Advanced Options + +<div class="cfgcmd"> + +set service pppoe-server ppp-options disable-ccp + +Disable Compression Control Protocol (CCP). +CCP is enabled by default. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server ppp-options interface-cache \<number\> + +Specifies number of interfaces to keep in cache. It means that don’t +destroy interface after corresponding session is destroyed, instead +place it to cache and use it later for new sessions repeatedly. +This should reduce kernel-level interface creation/deletion rate lack. +Default value is **0**. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server ppp-options ipv4 +\<require | prefer | allow | deny\> + +Specifies IPv4 negotiation preference. + +- **require** - Require IPv4 negotiation +- **prefer** - Ask client for IPv4 negotiation, do not fail if it rejects +- **allow** - Negotiate IPv4 only if client requests (Default value) +- **deny** - Do not negotiate IPv4 + +</div> + +<div class="cfgcmd"> + +set service pppoe-server ppp-options lcp-echo-failure \<number\> + +Defines the maximum <span class="title-ref">\<number\></span> of unanswered echo requests. Upon reaching the +value <span class="title-ref">\<number\></span>, the session will be reset. Default value is **3**. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server ppp-options lcp-echo-interval \<interval\> + +If this option is specified and is greater than 0, then the PPP module will +send LCP pings of the echo request every <span class="title-ref">\<interval\></span> seconds. +Default value is **30**. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server ppp-options lcp-echo-timeout + +Specifies timeout in seconds to wait for any peer activity. If this option +specified it turns on adaptive lcp echo functionality and "lcp-echo-failure" +is not used. Default value is **0**. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server ppp-options min-mtu \<number\> + +Defines minimum acceptable MTU. If client will try to negotiate less then +specified MTU then it will be NAKed or disconnected if rejects greater MTU. +Default value is **100**. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server ppp-options mppe \<require | prefer | deny\> + +Specifies `MPPE (Microsoft Point-to-Point Encryption)` negotiation +preference. + +- **require** - ask client for mppe, if it rejects drop connection +- **prefer** - ask client for mppe, if it rejects don't fail. (Default value) +- **deny** - deny mppe + +Default behavior - don't ask client for mppe, but allow it if client wants. +Please note that RADIUS may override this option by MS-MPPE-Encryption-Policy +attribute. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server ppp-options mru \<number\> + +Defines preferred MRU. By default is not defined. + +</div> + +### Global Advanced options + +<div class="cfgcmd"> + +set service pppoe-server description \<description\> + +Set description. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server limits burst \<value\> + +Burst count + +</div> + +<div class="cfgcmd"> + +set service pppoe-server limits connection-limit \<value\> + +Acceptable rate of connections (e.g. 1/min, 60/sec) + +</div> + +<div class="cfgcmd"> + +set service pppoe-server limits timeout \<value\> + +Timeout in seconds + +</div> + +<div class="cfgcmd"> + +set service pppoe-server mtu + +Maximum Transmission Unit (MTU) (default: **1492**) + +</div> + +<div class="cfgcmd"> + +set service pppoe-server max-concurrent-sessions + +Maximum number of concurrent session start attempts + +</div> + +<div class="cfgcmd"> + +set service pppoe-server name-server \<address\> + +Connected client should use <span class="title-ref">\<address\></span> as their DNS server. This +command accepts both IPv4 and IPv6 addresses. Up to two nameservers +can be configured for IPv4, up to three for IPv6. + +</div> + +<div class="cfgcmd"> + +set service pppoe-server service-name \<names\> + +Specifies Service-Name to respond. If absent any Service-Name is +acceptable and client’s Service-Name will be sent back. Also possible +set multiple service-names: <span class="title-ref">sn1,sn2,sn3</span> + +</div> + +Per default the user session is being replaced if a second +authentication request succeeds. Such session requests can be either +denied or allowed entirely, which would allow multiple sessions for a +user in the latter case. If it is denied, the second session is being +rejected even if the authentication succeeds, the user has to terminate +its first session and can then authentication again. + +<div class="cfgcmd"> + +set service pppoe-server session-control + +- **disable**: Disables session control. +- **deny**: Deny second session authorization. +- **replace**: Terminate first session when second is authorized **(default)** + +</div> + +<div class="cfgcmd"> + +set service pppoe-server shaper fwmark \<1-2147483647\> + +Match firewall mark value + +</div> + +<div class="cfgcmd"> + +set service pppoe-server snmp master-agent + +Enable SNMP + +</div> + +<div class="cfgcmd"> + +set service pppoe-server wins-server \<address\> + +Windows Internet Name Service (WINS) servers propagated to client + +</div> + +## Monitoring + +<div class="opcmd"> + +show pppoe-server sessions + +Use this command to locally check the active sessions in the PPPoE +server. + +</div> + +``` none +show pppoe-server sessions +ifname | username | ip | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes +-------+----------+------------+-------------------+-------------+--------+----------+----------+---------- +ppp0 | foo | 10.1.1.100 | 00:53:00:ba:db:15 | 20480/10240 | active | 00:00:11 | 214 B | 76 B +``` + +## Examples + +### IPv4 + +The example below uses ACN as access-concentrator name, assigns an +address from the pool 10.1.1.100-111, terminates at the local endpoint +10.1.1.1 and serves requests only on eth1. + +``` none +set service pppoe-server access-concentrator 'ACN' +set service pppoe-server authentication local-users username foo password 'bar' +set service pppoe-server authentication mode 'local' +set service pppoe-server client-ip-pool IP-POOL range '10.1.1.100-10.1.1.111' +set service pppoe-server default-pool 'IP-POOL' +set service pppoe-server interface eth1 +set service pppoe-server gateway-address '10.1.1.2' +set service pppoe-server name-server '10.100.100.1' +set service pppoe-server name-server '10.100.200.1' +``` + +### Dual-Stack IPv4/IPv6 provisioning with Prefix Delegation + +The example below covers a dual-stack configuration. + +``` none +set service pppoe-server authentication local-users username test password 'test' +set service pppoe-server authentication mode 'local' +set service pppoe-server client-ip-pool IP-POOL range '192.168.0.1/24' +set service pppoe-server default-pool 'IP-POOL' +set service pppoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' +set service pppoe-server client-ipv6-pool IPV6-POOL prefix '2001:db8:8002::/48' mask '64' +set service pppoe-server default-ipv6-pool IPv6-POOL +set service pppoe-server ppp-options ipv6 allow +set service pppoe-server name-server '10.1.1.1' +set service pppoe-server name-server '2001:db8:4860::8888' +set service pppoe-server interface 'eth2' +set service pppoe-server gateway-address '10.100.100.1' +``` + +The client, once successfully authenticated, will receive an IPv4 and an +IPv6 /64 address to terminate the PPPoE endpoint on the client side and +a /56 subnet for the clients internal use. + +``` none +vyos@pppoe-server:~$ sh pppoe-server sessions + ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes +--------+----------+-------------+--------------------------+---------------------+-------------------+------------+--------+----------+----------+---------- + ppp0 | test | 192.168.0.1 | 2001:db8:8002:0:200::/64 | 2001:db8:8003::1/56 | 00:53:00:12:42:eb | | active | 00:00:49 | 875 B | 2.1 KiB +``` diff --git a/docs/configuration/service/md-router-advert.md b/docs/configuration/service/md-router-advert.md new file mode 100644 index 00000000..3367e7aa --- /dev/null +++ b/docs/configuration/service/md-router-advert.md @@ -0,0 +1,241 @@ +# Router Advertisements + +`RAs (Router advertisements)` are described in `4861#section-4.6.2`. +They are part of what is known as `SLAAC (Stateless Address +Autoconfiguration)`. + +Supported interface types: + +> - bonding +> - bridge +> - ethernet +> - geneve +> - l2tpv3 +> - openvpn +> - pseudo-ethernet +> - tunnel +> - vxlan +> - wireguard +> - wireless +> - wwan + +## Configuration + +<div class="cfgcmd"> + +set service router-advert interface \<interface\> ... + +</div> + +<table> +<colgroup> +<col style="width: 25%" /> +<col style="width: 25%" /> +<col style="width: 50%" /> +</colgroup> +<thead> +<tr> +<th>Field</th> +<th>VyOS Option</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td>Cur Hop Limit</td> +<td>hop-limit</td> +<td>Hop count field of the outgoing RA packets</td> +</tr> +<tr> +<td>"Managed address configuration" flag</td> +<td>managed-flag</td> +<td>Tell hosts to use the administered stateful protocol (i.e. DHCP) for autoconfiguration</td> +</tr> +<tr> +<td>"Other configuration" flag</td> +<td>other-config-flag</td> +<td>Tell hosts to use the administered (stateful) protocol (i.e. DHCP) for autoconfiguration of other (non-address) information</td> +</tr> +<tr> +<td>MTU</td> +<td>link-mtu</td> +<td>Link MTU value placed in RAs, exluded in RAs if unset</td> +</tr> +<tr> +<td>Router Lifetime</td> +<td>default-lifetime</td> +<td>Lifetime associated with the default router in units of seconds</td> +</tr> +<tr> +<td>Reachable Time</td> +<td>reachable-time</td> +<td>Time, in milliseconds, that a node assumes a neighbor is reachable after having received a reachability confirmation</td> +</tr> +<tr> +<td>Retransmit Timer</td> +<td>retrans-timer</td> +<td>Time in milliseconds between retransmitted Neighbor Solicitation messages</td> +</tr> +<tr> +<td>Default Router Preference</td> +<td>default-preference</td> +<td>Preference associated with the default router</td> +</tr> +<tr> +<td>Interval</td> +<td>interval</td> +<td>Min and max intervals between unsolicited multicast RAs</td> +</tr> +<tr> +<td>DNSSL</td> +<td>dnssl</td> +<td>DNS search list to advertise</td> +</tr> +<tr> +<td>Name Server</td> +<td>name-server</td> +<td>Advertise DNS server per <a href="https://tools.ietf.org/html/rfc6106">https://tools.ietf.org/html/rfc6106</a></td> +</tr> +</tbody> +</table> + +### Advertising a Prefix + +<div class="cfgcmd"> + +set service router-advert interface \<interface\> prefix \<prefix/mask\> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +You can also opt for using <span class="title-ref">::/64</span> as prefix for your `RAs (Router +Advertisements)`. This will take the IPv6 GUA prefix assigned to the interface, +which comes in handy when using DHCPv6-PD. + +</div> + +</div> + +<table> +<colgroup> +<col style="width: 25%" /> +<col style="width: 75%" /> +</colgroup> +<thead> +<tr> +<th>VyOS Field</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td>decrement-lifetime</td> +<td>Lifetime is decremented by the number of seconds since the last RA - use in conjunction with a DHCPv6-PD prefix</td> +</tr> +<tr> +<td>deprecate-prefix</td> +<td>Upon shutdown, this option will deprecate the prefix by announcing it in the shutdown RA</td> +</tr> +<tr> +<td>no-autonomous-flag</td> +<td>Prefix can not be used for stateless address auto-configuration</td> +</tr> +<tr> +<td>no-on-link-flag</td> +<td>Prefix can not be used for on-link determination</td> +</tr> +<tr> +<td>preferred-lifetime</td> +<td>Time in seconds that the prefix will remain preferred (default 4 hours)</td> +</tr> +<tr> +<td>valid-lifetime</td> +<td>Time in seconds that the prefix will remain valid (default: 30 days)</td> +</tr> +</tbody> +</table> + +### Advertising a NAT64 Prefix + +<div class="cfgcmd"> + +set service router-advert interface \<interface\> nat64prefix \<prefix/mask\> + +Enable PREF64 option as outlined in `8781`. + +NAT64 prefix mask must be one of: /32, /40, /48, /56, /64 or 96. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The well known NAT64 prefix is `64:ff9b::/96` + +</div> + +</div> + +<table> +<colgroup> +<col style="width: 25%" /> +<col style="width: 75%" /> +</colgroup> +<thead> +<tr> +<th>VyOS Field</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td>valid-lifetime</td> +<td>Time in seconds that the prefix will remain valid (default: 65528 seconds)</td> +</tr> +</tbody> +</table> + +### Disabling Advertisements + +To disable advertisements without deleting the configuration: + +<div class="cfgcmd"> + +set service router-advert interface \<interface\> no-send-advert + +If set, the router will no longer send periodic router advertisements and +will not respond to router solicitations. + +</div> + +<div class="cfgcmd"> + +set service router-advert interface \<interface\> no-send-interval + +Advertisement Interval Option (specified by Mobile IPv6) is always included in +Router Advertisements unless this option is set. + +</div> + +## Example + +Your LAN connected on eth0 uses prefix `2001:db8:beef:2::/64` with the router +beeing `2001:db8:beef:2::1` + +``` none +set interfaces ethernet eth0 address 2001:db8:beef:2::1/64 + +set service router-advert interface eth0 default-preference 'high' +set service router-advert interface eth0 name-server '2001:db8::1' +set service router-advert interface eth0 name-server '2001:db8::2' +set service router-advert interface eth0 other-config-flag +set service router-advert interface eth0 prefix 2001:db8:beef:2::/64 +``` diff --git a/docs/configuration/service/md-salt-minion.md b/docs/configuration/service/md-salt-minion.md new file mode 100644 index 00000000..8783d0b4 --- /dev/null +++ b/docs/configuration/service/md-salt-minion.md @@ -0,0 +1,58 @@ +# Salt-Minion + +[SaltStack](https://saltproject.io/) is Python-based, open-source +software for event-driven IT automation, remote task execution, and +configuration management. Supporting the "infrastructure as code" +approach to data center system and network deployment and management, +configuration automation, SecOps orchestration, vulnerability remediation, +and hybrid cloud control. + +## Requirements + +To use the Salt-Minion, a running Salt-Master is required. You can find more +in the [Salt Poject Documentaion](https://docs.saltproject.io/en/latest/contents.html) + +## Configuration + +<div class="cfgcmd"> + +set service salt-minion hash \<type\> + +The hash type used when discovering file on master server (default: sha256) + +</div> + +<div class="cfgcmd"> + +set service salt-minion id \<id\> + +Explicitly declare ID for this minion to use (default: hostname) + +</div> + +<div class="cfgcmd"> + +set service salt-minion interval \<1-1440\> + +Interval in minutes between updates (default: 60) + +</div> + +<div class="cfgcmd"> + +set service salt-minion master \<hostname | IP\> + +The hostname or IP address of the master + +</div> + +<div class="cfgcmd"> + +set service salt-minion master-key \<key\> + +URL with signature of master for auth reply verification + +</div> + +Please take a look in the Automation section to find some usefull +Examples. diff --git a/docs/configuration/service/md-snmp.md b/docs/configuration/service/md-snmp.md new file mode 100644 index 00000000..84877df3 --- /dev/null +++ b/docs/configuration/service/md-snmp.md @@ -0,0 +1,252 @@ +# SNMP + +`SNMP (Simple Network Management Protocol)` is an Internet Standard +protocol for collecting and organizing information about managed devices on +IP networks and for modifying that information to change device behavior. +Devices that typically support SNMP include cable modems, routers, switches, +servers, workstations, printers, and more. + +SNMP is widely used in network management for network monitoring. SNMP exposes +management data in the form of variables on the managed systems organized in +a management information base ([MIB](https://en.wikipedia.org/wiki/Management_information_base)) which describe the system status and +configuration. These variables can then be remotely queried (and, in some +circumstances, manipulated) by managing applications. + +Three significant versions of SNMP have been developed and deployed. SNMPv1 is +the original version of the protocol. More recent versions, SNMPv2c and SNMPv3, +feature improvements in performance, flexibility and security. + +SNMP is a component of the Internet Protocol Suite as defined by the Internet +Engineering Task Force (IETF). It consists of a set of standards for network +management, including an application layer protocol, a database schema, and a +set of data objects. + +## Overview and basic concepts + +In typical uses of SNMP, one or more administrative computers called managers +have the task of monitoring or managing a group of hosts or devices on a +computer network. Each managed system executes a software component called an +agent which reports information via SNMP to the manager. + +An SNMP-managed network consists of three key components: + +- Managed devices +- Agent - software which runs on managed devices +- Network management station (NMS) - software which runs on the manager + +A managed device is a network node that implements an SNMP interface that +allows unidirectional (read-only) or bidirectional (read and write) access to +node-specific information. Managed devices exchange node-specific information +with the NMSs. Sometimes called network elements, the managed devices can be +any type of device, including, but not limited to, routers, access servers, +switches, cable modems, bridges, hubs, IP telephones, IP video cameras, +computer hosts, and printers. + +An agent is a network-management software module that resides on a managed +device. An agent has local knowledge of management information and translates +that information to or from an SNMP-specific form. + +A network management station executes applications that monitor and control +managed devices. NMSs provide the bulk of the processing and memory resources +required for network management. One or more NMSs may exist on any managed +network. + +<figure> +<img src="/_static/images/service_snmp_communication_principles_diagram.webp" alt="Principle of SNMP Communication" /> +<figcaption>Image thankfully borrowed from +<a href="https://en.wikipedia.org/wiki/File:SNMP_communication_principles_diagram.PNG">https://en.wikipedia.org/wiki/File:SNMP_communication_principles_diagram.PNG</a> +which is under the GNU Free Documentation License</figcaption> +</figure> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +VyOS SNMP supports both IPv4 and IPv6. + +</div> + +## SNMP Protocol Versions + +VyOS itself supports [SNMPv2](https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_2) (version 2) and [SNMPv3](https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_3) (version 3) where the +later is recommended because of improved security (optional authentication and +encryption). + +### SNMPv2 + +SNMPv2 is the original and most commonly used version. For authorizing clients, +SNMP uses the concept of communities. Communities may have authorization set +to read only (this is most common) or to read and write (this option is not +actively used in VyOS). + +SNMP can work synchronously or asynchronously. In synchronous communication, +the monitoring system queries the router periodically. In asynchronous, the +router sends notification to the "trap" (the monitoring host). + +SNMPv2 does not support any authentication mechanisms, other than client source +address, so you should specify addresses of clients allowed to monitor the +router. Note that SNMPv2 also supports no encryption and always sends data in +plain text. + +#### Example + +``` none +# Define a community +set service snmp community routers authorization ro + +# Allow monitoring access from the entire network +set service snmp community routers network 192.0.2.0/24 +set service snmp community routers network 2001::db8:ffff:eeee::/64 + +# Allow monitoring access from specific addresses +set service snmp community routers client 203.0.113.10 +set service snmp community routers client 203.0.113.20 + +# Define optional router information +set service snmp location "UK, London" +set service snmp contact "admin@example.com" + +# Trap target if you want asynchronous communication +set service snmp trap-target 203.0.113.10 + +# Listen only on specific IP addresses (port defaults to 161) +set service snmp listen-address 172.16.254.36 port 161 +set service snmp listen-address 2001:db8::f00::1 +``` + +### SNMPv3 + +SNMPv3 (version 3 of the SNMP protocol) introduced a whole slew of new security +related features that have been missing from the previous versions. Security +was one of the biggest weakness of SNMP until v3. Authentication in SNMP +Versions 1 and 2 amounts to nothing more than a password (community string) +sent in clear text between a manager and agent. Each SNMPv3 message contains +security parameters which are encoded as an octet string. The meaning of these +security parameters depends on the security model being used. + +The security approach in SNMPv3 targets: + +- Confidentiality – Encryption of packets to prevent snooping by an + unauthorized source. +- Integrity – Message integrity to ensure that a packet has not been tampered + while in transit including an optional packet replay protection mechanism. +- Authentication – to verify that the message is from a valid source. + +#### Example + +- Let SNMP daemon listen only on IP address 192.0.2.1 +- Configure new SNMP user named "vyos" with password "vyos12345678" +- New user will use SHA/AES for authentication and privacy + +``` none +set service snmp listen-address 192.0.2.1 +set service snmp location 'VyOS Datacenter' +set service snmp v3 engineid '000000000000000000000002' +set service snmp v3 group default mode 'ro' +set service snmp v3 group default view 'default' +set service snmp v3 user vyos auth plaintext-password 'vyos12345678' +set service snmp v3 user vyos auth type 'sha' +set service snmp v3 user vyos group 'default' +set service snmp v3 user vyos privacy plaintext-password 'vyos12345678' +set service snmp v3 user vyos privacy type 'aes' +set service snmp v3 view default oid 1 +``` + +After commit the plaintext passwords will be hashed and stored in your +configuration. The resulting CLI config will look like: + +``` none +vyos@vyos# show service snmp + listen-address 192.0.2.1 { + } + location "VyOS Datacenter" + v3 { + engineid 000000000000000000000002 + group default { + mode ro + view default + } + user vyos { + auth { + encrypted-password 4e52fe55fd011c9c51ae2c65f4b78ca93dcafdfe + type sha + } + group default + privacy { + encrypted-password 4e52fe55fd011c9c51ae2c65f4b78ca93dcafdfe + type aes + } + } + view default { + oid 1 { + } + } + } +``` + +You can test the SNMPv3 functionality from any linux based system, just run the +following command: `snmpwalk -v 3 -u vyos -a SHA -A vyos12345678 -x AES -X vyos12345678 -l authPriv 192.0.2.1 .1` + +## VyOS MIBs + +All SNMP MIBs are located in each image of VyOS here: `/usr/share/snmp/mibs/` + +You are be able to download the files using SCP, once the SSH service +has been activated like so + +``` none +scp -r vyos@your_router:/usr/share/snmp/mibs /your_folder/mibs +``` + +## SNMP Extensions + +To extend SNMP agent functionality, custom scripts can be executed every time +the agent is being called. This can be achieved by using +`arbitrary extensioncommands`. The first step is to create a functional +script of course, then upload it to your VyOS instance via the command +`scp your_script.sh vyos@your_router:/config/user-data`. +Once the script is uploaded, it needs to be configured via the command below. + +``` none +set service snmp script-extensions extension-name my-extension script your_script.sh +commit +``` + +The OID `.1.3.6.1.4.1.8072.1.3.2.3.1.1.4.116.101.115.116`, once called, will +contain the output of the extension. + +``` none +root@vyos:/home/vyos# snmpwalk -v2c -c public 127.0.0.1 nsExtendOutput1 +NET-SNMP-EXTEND-MIB::nsExtendOutput1Line."my-extension" = STRING: hello +NET-SNMP-EXTEND-MIB::nsExtendOutputFull."my-extension" = STRING: hello +NET-SNMP-EXTEND-MIB::nsExtendOutNumLines."my-extension" = INTEGER: 1 +NET-SNMP-EXTEND-MIB::nsExtendResult."my-extension" = INTEGER: 0 +``` + +## SolarWinds + +If you happen to use SolarWinds Orion as NMS you can also use the Device +Templates Management. A template for VyOS can be easily imported. + +Create a file named `VyOS-1.3.6.1.4.1.44641.ConfigMgmt-Commands` using the +following content: + +``` none +<Configuration-Management Device="VyOS" SystemOID="1.3.6.1.4.1.44641"> + <Commands> + <Command Name="Reset" Value="set terminal width 0${CRLF}set terminal length 0"/> + <Command Name="Reboot" Value="reboot${CRLF}Yes"/> + <Command Name="EnterConfigMode" Value="configure"/> + <Command Name="ExitConfigMode" Value="commit${CRLF}exit"/> + <Command Name="DownloadConfig" Value="show configuration commands"/> + <Command Name="SaveConfig" Value="commit${CRLF}save"/> + <Command Name="Version" Value="show version"/> + <Command Name="MenuBased" Value="False"/> + <Command Name="VirtualPrompt" Value=":~"/> + </Commands> +</Configuration-Management> +``` diff --git a/docs/configuration/service/md-ssh.md b/docs/configuration/service/md-ssh.md new file mode 100644 index 00000000..12384878 --- /dev/null +++ b/docs/configuration/service/md-ssh.md @@ -0,0 +1,374 @@ +# SSH + +`SSH (Secure Shell)` is a cryptographic network protocol for operating +network services securely over an unsecured network. The standard TCP port for +SSH is 22. The best known example application is for remote login to computer +systems by users. + +SSH provides a secure channel over an unsecured network in a client-server +architecture, connecting an SSH client application with an SSH server. Common +applications include remote command-line login and remote command execution, +but any network service can be secured with SSH. The protocol specification +distinguishes between two major versions, referred to as SSH-1 and SSH-2. + +The most visible application of the protocol is for access to shell accounts +on Unix-like operating systems, but it sees some limited use on Windows as +well. In 2015, Microsoft announced that they would include native support for +SSH in a future release. + +SSH was designed as a replacement for Telnet and for unsecured remote shell +protocols such as the Berkeley rlogin, rsh, and rexec protocols. +Those protocols send information, notably passwords, in plaintext, +rendering them susceptible to interception and disclosure using packet +analysis. The encryption used by SSH is intended to provide confidentiality +and integrity of data over an unsecured network, such as the Internet. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +VyOS 1.1 supported login as user `root`. This has been removed due +to tighter security in VyOS 1.2. + +</div> + +<div class="seealso"> + +SSH `ssh_key_based_authentication` + +</div> + +## Configuration + +<div class="cfgcmd"> + +set service ssh port \<port\> + +Enabling SSH only requires you to specify the port `<port>` you want SSH to +listen on. By default, SSH runs on port 22. + +</div> + +<div class="cfgcmd"> + +set service ssh listen-address \<address\> + +Specify IPv4/IPv6 listen address of SSH server. Multiple addresses can be +defined. + +</div> + +<div class="cfgcmd"> + +set service ssh ciphers \<cipher\> + +Define allowed ciphers used for the SSH connection. A number of allowed +ciphers can be specified, use multiple occurrences to allow multiple ciphers. + +List of supported ciphers: `3des-cbc`, `aes128-cbc`, `aes192-cbc`, +`aes256-cbc`, `aes128-ctr`, `aes192-ctr`, `aes256-ctr`, +`aes128-gcm@openssh.com`, `aes256-gcm@openssh.com`, +`chacha20-poly1305@openssh.com` + +</div> + +<div class="cfgcmd"> + +set service ssh disable-password-authentication + +Disable password based authentication. Login via SSH keys only. This hardens +security! + +</div> + +<div class="cfgcmd"> + +set service ssh disable-host-validation + +Disable the host validation through reverse DNS lookups - can speedup login +time when reverse lookup is not possible. + +</div> + +<div class="cfgcmd"> + +set service ssh mac \<mac\> + +Specifies the available `MAC (Message Authentication Code)` algorithms. +The MAC algorithm is used in protocol version 2 for data integrity protection. +Multiple algorithms can be provided by using multiple commands, defining +one algorithm per command. + +List of supported MACs: `hmac-md5`, `hmac-md5-96`, `hmac-ripemd160`, +`hmac-sha1`, `hmac-sha1-96`, `hmac-sha2-256`, `hmac-sha2-512`, +`umac-64@openssh.com`, `umac-128@openssh.com`, +`hmac-md5-etm@openssh.com`, `hmac-md5-96-etm@openssh.com`, +`hmac-ripemd160-etm@openssh.com`, `hmac-sha1-etm@openssh.com`, +`hmac-sha1-96-etm@openssh.com`, `hmac-sha2-256-etm@openssh.com`, +`hmac-sha2-512-etm@openssh.com`, `umac-64-etm@openssh.com`, +`umac-128-etm@openssh.com` + +</div> + +<div class="cfgcmd"> + +set service ssh access-control \<allow | deny\> \<group | user\> \<name\> + +Add access-control directive to allow or deny users and groups. Directives +are processed in the following order of precedence: `deny-users`, +`allow-users`, `deny-groups` and `allow-groups`. + +</div> + +<div class="cfgcmd"> + +set service ssh client-keepalive-interval \<interval\> + +Specify timeout interval for keepalive message in seconds. + +</div> + +<div class="cfgcmd"> + +set service ssh key-exchange \<kex\> + +Specify allowed `KEX (Key Exchange)` algorithms. + +List of supported algorithms: `diffie-hellman-group1-sha1`, +`diffie-hellman-group14-sha1`, `diffie-hellman-group14-sha256`, +`diffie-hellman-group16-sha512`, `diffie-hellman-group18-sha512`, +`diffie-hellman-group-exchange-sha1`, +`diffie-hellman-group-exchange-sha256`, +`ecdh-sha2-nistp256`, `ecdh-sha2-nistp384`, `ecdh-sha2-nistp521`, +`curve25519-sha256` and `curve25519-sha256@libssh.org`. + +</div> + +<div class="cfgcmd"> + +set service ssh loglevel \<quiet | fatal | error | info | verbose\> + +Set the `sshd` log level. The default is `info`. + +</div> + +<div class="cfgcmd"> + +set service ssh vrf \<name\> + +Specify name of the `VRF (Virtual Routing and Forwarding)` instance. + +</div> + +## Dynamic-protection + +Protects host from brute-force attacks against +SSH. Log messages are parsed, line-by-line, for recognized patterns. If an +attack, such as several login failures within a few seconds, is detected, the +offending IP is blocked. Offenders are unblocked after a set interval. + +<div class="cfgcmd"> + +set service ssh dynamic-protection + +Allow `ssh` dynamic-protection. + +</div> + +<div class="cfgcmd"> + +set service ssh dynamic-protection allow-from \<address | prefix\> + +Whitelist of addresses and networks. Always allow inbound connections from +these systems. + +</div> + +<div class="cfgcmd"> + +set service ssh dynamic-protection block-time \<sec\> + +Block source IP in seconds. Subsequent blocks increase by a factor of 1.5 +The default is 120. + +</div> + +<div class="cfgcmd"> + +set service ssh dynamic-protection detect-time \<sec\> + +Remember source IP in seconds before reset their score. The default is 1800. + +</div> + +<div class="cfgcmd"> + +set service ssh dynamic-protection threshold \<sec\> + +Block source IP when their cumulative attack score exceeds threshold. The +default is 30. + +</div> + +## Operation + +<div class="opcmd"> + +restart ssh + +Restart the SSH daemon process, the current session is not affected, only the +background daemon is restarted. + +</div> + +<div class="opcmd"> + +generate ssh server-key + +Re-generated the public/private keyportion which SSH uses to secure +connections. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Already learned known_hosts files of clients need an update as the +public key will change. + +</div> + +</div> + +<div class="opcmd"> + +generate ssh client-key /path/to/private_key + +Re-generated a known pub/private keyfile which can be used to connect to +other services (e.g. RPKI cache). + +Example: + +``` none +vyos@vyos:~$ generate ssh client-key /config/auth/id_rsa_rpki +Generating public/private rsa key pair. +Your identification has been saved in /config/auth/id_rsa_rpki. +Your public key has been saved in /config/auth/id_rsa_rpki.pub. +The key fingerprint is: +SHA256:XGv2PpdOzVCzpmEzJZga8hTRq7B/ZYL3fXaioLFLS5Q vyos@vyos +The key's randomart image is: ++---[RSA 2048]----+ +| oo | +| ..o | +| . o.o.. o.| +| o+ooo o.o| +| Eo* =.o | +| o = +.o*+ | +| = o *.o.o| +| o * +.o+.+| +| =.. o=.oo| ++----[SHA256]-----+ +``` + +Two new files `/config/auth/id_rsa_rpki` and +`/config/auth/id_rsa_rpki.pub` +will be created. + +</div> + +<div class="opcmd"> + +generate public-key-command user \<username\> path \<location\> + +Generate the configuration mode commands to add a public key for +`ssh_key_based_authentication`. +`<location>` can be a local path or a URL pointing at a remote file. + +Supported remote protocols are FTP, FTPS, HTTP, HTTPS, SCP/SFTP and TFTP. + +Example: + +``` none +alyssa@vyos:~$ generate public-key-command user alyssa path sftp://example.net/home/alyssa/.ssh/id_rsa.pub +# To add this key as an embedded key, run the following commands: +configure +set system login user alyssa authentication public-keys alyssa@example.net key AAA... +set system login user alyssa authentication public-keys alyssa@example.net type ssh-rsa +commit +save +exit + +ben@vyos:~$ generate public-key-command user ben path ~/.ssh/id_rsa.pub +# To add this key as an embedded key, run the following commands: +configure +set system login user ben authentication public-keys ben@vyos key AAA... +set system login user ben authentication public-keys ben@vyos type ssh-dss +commit +save +exit +``` + +</div> + +<div class="opcmd"> + +show log ssh + +Show SSH server log. + +</div> + +<div class="opcmd"> + +monitor log ssh + +Follow the SSH server log. + +</div> + +<div class="opcmd"> + +show log ssh dynamic-protection + +Show SSH dynamic-protection log. + +</div> + +<div class="opcmd"> + +monitor log ssh dynamic-protection + +Follow the SSH dynamic-protection log. + +</div> + +<div class="opcmd"> + +show ssh dynamic-protection + +Show list of IPs currently blocked by SSH dynamic-protection. + +</div> + +<div class="opcmd"> + +show ssh fingerprints + +Show SSH server public key fingerprints. + +</div> + +<div class="opcmd"> + +show ssh fingerprints ascii + +Show SSH server public key fingerprints, including a visual ASCII art representation. + +</div> diff --git a/docs/configuration/service/md-tftp-server.md b/docs/configuration/service/md-tftp-server.md new file mode 100644 index 00000000..1d8e6e15 --- /dev/null +++ b/docs/configuration/service/md-tftp-server.md @@ -0,0 +1,105 @@ +# TFTP Server + +`TFTP (Trivial File Transfer Protocol)` is a simple, lockstep file +transfer protocol which allows a client to get a file from or put a file onto +a remote host. One of its primary uses is in the early stages of nodes booting +from a local area network. TFTP has been used for this application because it +is very simple to implement. + +## Configuration + +<div class="cfgcmd"> + +set service tftp-server directory \<directory\> + +Enable TFTP service by specifying the <span class="title-ref">\<directory\></span> which will be used to serve +files. + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +Choose your `directory` location carefully or you will loose the +content on image upgrades. Any directory under `/config` is save at this +will be migrated. + +</div> + +<div class="cfgcmd"> + +set service tftp-server listen-address \<address\> + +Configure the IPv4 or IPv6 listen address of the TFTP server. Multiple IPv4 and +IPv6 addresses can be given. There will be one TFTP server instances listening +on each IP address. + +</div> + +<div class="cfgcmd"> + +set service tftp-server listen-address \<address\> vrf \<name\> + +</div> + +Additional option to run TFTP server in the `VRF (Virtual Routing and Forwarding)` context + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Configuring a listen-address is essential for the service to work. + +</div> + +<div class="cfgcmd"> + +set service tftp-server allow-upload + +Optional, if you want to enable uploads, else TFTP server will act as a +read-only server. + +</div> + +### Example + +Provide TFTP server listening on both IPv4 and IPv6 addresses `192.0.2.1` and +`2001:db8::1` serving the content from `/config/tftpboot`. Uploading via +TFTP to this server is disabled. + +The resulting configuration will look like: + +``` none +vyos@vyos# show service + tftp-server { + directory /config/tftpboot + listen-address 2001:db8::1 + listen-address 192.0.2.1 + } +``` + +### Verification + +Client: + +``` none +vyos@RTR2:~$ tftp -p -l /config/config.boot -r backup 192.0.2.1 +backup1 100% |******************************| 723 0:00:00 ETA +``` + +Server: + +``` none +vyos@RTR1# ls -ltr /config/tftpboot/ +total 1 +-rw-rw-rw- 1 tftp tftp 1995 May 19 16:02 backup +``` diff --git a/docs/configuration/service/md-webproxy.md b/docs/configuration/service/md-webproxy.md new file mode 100644 index 00000000..4a881cea --- /dev/null +++ b/docs/configuration/service/md-webproxy.md @@ -0,0 +1,536 @@ +# Webproxy + +The proxy service in VyOS is based on [Squid](http://www.squid-cache.org/) and some related modules. + +[Squid](http://www.squid-cache.org/) is a caching and forwarding HTTP web proxy. It has a wide variety of +uses, including speeding up a web server by caching repeated requests, caching +web, DNS and other computer network lookups for a group of people sharing +network resources, and aiding security by filtering traffic. Although primarily +used for HTTP and FTP, Squid includes limited support for several other +protocols including Internet Gopher, SSL,\[6\] TLS and HTTPS. Squid does not +support the SOCKS protocol. + +URL Filtering is provided by [SquidGuard](http://www.squidguard.org/). + +## Configuration + +<div class="cfgcmd"> + +set service webproxy append-domain \<domain\> + +Use this command to specify a domain name to be appended to domain-names +within URLs that do not include a dot `.` the domain is appended. + +Example: to be appended is set to `vyos.net` and the URL received is +`www/foo.html`, the system will use the generated, final URL of +`www.vyos.net/foo.html`. + +``` none +set service webproxy append-domain vyos.net +``` + +</div> + +<div class="cfgcmd"> + +set service webproxy cache-size \<size\> + +The size of the on-disk Proxy cache is user configurable. The Proxies default +cache-size is configured to 100 MB. + +Unit of this command is MB. + +``` none +set service webproxy cache-size 1024 +``` + +</div> + +<div class="cfgcmd"> + +set service webproxy default-port \<port\> + +Specify the port used on which the proxy service is listening for requests. +This port is the default port used for the specified listen-address. + +Default port is 3128. + +``` none +set service webproxy default-port 8080 +``` + +</div> + +<div class="cfgcmd"> + +set service webproxy domain-block \<domain\> + +Used to block specific domains by the Proxy. Specifying "vyos.net" will block +all access to vyos.net, and specifying ".xxx" will block all access to URLs +having an URL ending on .xxx. + +``` none +set service webproxy domain-block vyos.net +``` + +</div> + +<div class="cfgcmd"> + +set service webproxy domain-noncache \<domain\> + +Allow access to sites in a domain without retrieving them from the Proxy +cache. Specifying "vyos.net" will allow access to vyos.net but the pages +accessed will not be cached. It useful for working around problems with +"If-Modified-Since" checking at certain sites. + +``` none +set service webproxy domain-noncache vyos.net +``` + +</div> + +<div class="cfgcmd"> + +set service webproxy listen-address \<address\> + +Specifies proxy service listening address. The listen address is the IP +address on which the web proxy service listens for client requests. + +For security, the listen address should only be used on internal/trusted +networks! + +``` none +set service webproxy listen-address 192.0.2.1 +``` + +</div> + +<div class="cfgcmd"> + +set service webproxy listen-address \<address\> disable-transparent + +Disables web proxy transparent mode at a listening address. + +In transparent proxy mode, all traffic arriving on port 80 and destined for +the Internet is automatically forwarded through the proxy. This allows +immediate proxy forwarding without configuring client browsers. + +Non-transparent proxying requires that the client browsers be configured with +the proxy settings before requests are redirected. The advantage of this is +that the client web browser can detect that a proxy is in use and can behave +accordingly. In addition, web-transmitted malware can sometimes be blocked by +a non-transparent web proxy, since they are not aware of the proxy settings. + +``` none +set service webproxy listen-address 192.0.2.1 disable-transparent +``` + +</div> + +<div class="cfgcmd"> + +set service webproxy listen-address \<address\> port \<port\> + +Sets the listening port for a listening address. This overrides the default +port of 3128 on the specific listen address. + +``` none +set service webproxy listen-address 192.0.2.1 port 8080 +``` + +</div> + +<div class="cfgcmd"> + +set service webproxy reply-block-mime \<mime\> + +Used to block a specific mime-type. + +``` none +# block all PDFs +set service webproxy reply-block-mime application/pdf +``` + +</div> + +<div class="cfgcmd"> + +set service webproxy reply-body-max-size \<size\> + +Specifies the maximum size of a reply body in KB, used to limit the reply +size. + +All reply sizes are accepted by default. + +``` none +set service webproxy reply-body-max-size 2048 +``` + +</div> + +<div class="cfgcmd"> + +set service webproxy safe-ports \<port\> + +Add new port to Safe-ports acl. Ports included by default in Safe-ports acl: +21, 70, 80, 210, 280, 443, 488, 591, 777, 873, 1025-65535 + +</div> + +<div class="cfgcmd"> + +set service webproxy ssl-safe-ports \<port\> + +Add new port to SSL-ports acl. Ports included by default in SSL-ports acl: +443 + +</div> + +### Authentication + +The embedded Squid proxy can use LDAP to authenticate users against a company +wide directory. The following configuration is an example of how to use Active +Directory as authentication backend. Queries are done via LDAP. + +<div class="cfgcmd"> + +set service webproxy authentication children \<number\> + +Maximum number of authenticator processes to spawn. If you start too few +Squid will have to wait for them to process a backlog of credential +verifications, slowing it down. When password verifications are done via a +(slow) network you are likely to need lots of authenticator processes. + +This defaults to 5. + +``` none +set service webproxy authentication children 10 +``` + +</div> + +<div class="cfgcmd"> + +set service webproxy authentication credentials-ttl \<time\> + +Specifies how long squid assumes an externally validated username:password +pair is valid for - in other words how often the helper program is called for +that user. Set this low to force revalidation with short lived passwords. + +Time is in minutes and defaults to 60. + +``` none +set service webproxy authentication credentials-ttl 120 +``` + +</div> + +<div class="cfgcmd"> + +set service webproxy authentication method \<ldap\> + +Proxy authentication method, currently only LDAP is supported. + +``` none +set service webproxy authentication method ldap +``` + +</div> + +<div class="cfgcmd"> + +set service webproxy authentication realm + +Specifies the protection scope (aka realm name) which is to be reported to +the client for the authentication scheme. It is commonly part of the text +the user will see when prompted for their username and password. + +``` none +set service webproxy authentication realm "VyOS proxy auth" +``` + +</div> + +#### LDAP + +<div class="cfgcmd"> + +set service webproxy authentication ldap base-dn \<base-dn\> + +Specifies the base DN under which the users are located. + +``` none +set service webproxy authentication ldap base-dn DC=vyos,DC=net +``` + +</div> + +<div class="cfgcmd"> + +set service webproxy authentication ldap bind-dn \<bind-dn\> + +The DN and password to bind as while performing searches. + +``` none +set service webproxy authentication ldap bind-dn CN=proxyuser,CN=Users,DC=vyos,DC=net +``` + +</div> + +<div class="cfgcmd"> + +set service webproxy authentication ldap filter-expression \<expr\> + +LDAP search filter to locate the user DN. Required if the users are in a +hierarchy below the base DN, or if the login name is not what builds the user +specific part of the users DN. + +The search filter can contain up to 15 occurrences of %s which will be +replaced by the username, as in "uid=%s" for `2037` directories. For a +detailed description of LDAP search filter syntax see `2254`. + +``` none +set service webproxy authentication ldap filter-expression (cn=%s) +``` + +</div> + +<div class="cfgcmd"> + +set service webproxy authentication ldap password \<password\> + +The DN and password to bind as while performing searches. As the password +needs to be printed in plain text in your Squid configuration it is strongly +recommended to use a account with minimal associated privileges. This to limit +the damage in case someone could get hold of a copy of your Squid +configuration file. + +``` none +set service webproxy authentication ldap password vyos +``` + +</div> + +<div class="cfgcmd"> + +set service webproxy authentication ldap persistent-connection + +Use a persistent LDAP connection. Normally the LDAP connection is only open +while validating a username to preserve resources at the LDAP server. This +option causes the LDAP connection to be kept open, allowing it to be reused +for further user validations. + +Recommended for larger installations. + +``` none +set service webproxy authentication ldap persistent-connection +``` + +</div> + +<div class="cfgcmd"> + +set service webproxy authentication ldap port \<port\> + +Specify an alternate TCP port where the ldap server is listening if other than +the default LDAP port 389. + +``` none +set service webproxy authentication ldap port 389 +``` + +</div> + +<div class="cfgcmd"> + +set service webproxy authentication ldap server \<server\> + +Specify the LDAP server to connect to. + +``` none +set service webproxy authentication ldap server ldap.vyos.net +``` + +</div> + +<div class="cfgcmd"> + +set service webproxy authentication ldap use-ssl + +Use TLS encryption. + +``` none +set service webproxy authentication ldap use-ssl +``` + +</div> + +<div class="cfgcmd"> + +set service webproxy authentication ldap username-attribute \<attr\> + +Specifies the name of the DN attribute that contains the username/login. +Combined with the base DN to construct the users DN when no search filter is +specified (<span class="title-ref">filter-expression</span>). + +Defaults to 'uid' + +<div class="note"> + +<div class="title"> + +Note + +</div> + +This can only be done if all your users are located directly under +the same position in the LDAP tree and the login name is used for naming +each user object. If your LDAP tree does not match these criterias or if you +want to filter who are valid users then you need to use a search filter to +search for your users DN (<span class="title-ref">filter-expression</span>). + +</div> + +``` none +set service webproxy authentication ldap username-attribute uid +``` + +</div> + +<div class="cfgcmd"> + +set service webproxy authentication ldap version \<2 | 3\> + +LDAP protocol version. Defaults to 3 if not specified. + +``` none +set service webproxy authentication ldap version 2 +``` + +</div> + +### URL filtering + +<div class="cfgcmd"> + +set service webproxy url-filtering disable + +Disables web filtering without discarding configuration. + +``` none +set service webproxy url-filtering disable +``` + +</div> + +## Operation + +### Filtering + +#### Update + +If you want to use existing blacklists you have to create/download a database +first. Otherwise you will not be able to commit the config changes. + +<div class="opcmd"> + +update webproxy blacklists + +Download/Update complete blacklist + +``` none +vyos@vyos:~$ update webproxy blacklists +Warning: No url-filtering blacklist installed +Would you like to download a default blacklist? [confirm][y] +Connecting to ftp.univ-tlse1.fr (193.49.48.249:21) +blacklists.gz 100% |*************************************************************************************************************| 17.0M 0:00:00 ETA +Uncompressing blacklist... +Checking permissions... +Skip link for [ads] -> [publicite] +Building DB for [adult/domains] - 2467177 entries +Building DB for [adult/urls] - 67798 entries +Skip link for [aggressive] -> [agressif] +Building DB for [agressif/domains] - 348 entries +Building DB for [agressif/urls] - 36 entries +Building DB for [arjel/domains] - 69 entries +... + +Building DB for [webmail/domains] - 374 entries +Building DB for [webmail/urls] - 9 entries + +The webproxy daemon must be restarted +Would you like to restart it now? [confirm][y] + +[ ok ] Restarting squid (via systemctl): squid.service. +vyos@vyos:~$ +``` + +</div> + +<div class="opcmd"> + +update webproxy blacklists category \<category\> + +Download/Update partial blacklist. + +Use tab completion to get a list of categories. + +</div> + +- To auto update the blacklist files + + `set service webproxy url-filtering squidguard auto-update + update-hour 23` + +- To configure blocking add the following to the configuration + + `set service webproxy url-filtering squidguard block-category ads` + + `set service webproxy url-filtering squidguard block-category malware` + +#### Bypassing the webproxy + +Some services don't work correctly when being handled via a web proxy. +So sometimes it is useful to bypass a transparent proxy: + +- To bypass the proxy for every request that is directed to a specific + destination: + + `set service webproxy whitelist destination-address 198.51.100.33` + + `set service webproxy whitelist destination-address 192.0.2.0/24` + +- To bypass the proxy for every request that is coming from a specific source: + + `set service webproxy whitelist source-address 192.168.1.2` + + `set service webproxy whitelist source-address 192.168.2.0/24` + + (This can be useful when a called service has many and/or often changing + destination addresses - e.g. Netflix.) + +## Examples + +``` none +vyos@vyos# show service webproxy + authentication { + children 5 + credentials-ttl 60 + ldap { + base-dn DC=example,DC=local + bind-dn CN=proxyuser,CN=Users,DC=example,DC=local + filter-expression (cn=%s) + password Qwert1234 + server ldap.example.local + username-attribute cn + } + method ldap + realm "VyOS Webproxy" + } + cache-size 100 + default-port 3128 + listen-address 192.168.188.103 { + disable-transparent + } +``` diff --git a/docs/configuration/system/md-acceleration.md b/docs/configuration/system/md-acceleration.md new file mode 100644 index 00000000..21096988 --- /dev/null +++ b/docs/configuration/system/md-acceleration.md @@ -0,0 +1,168 @@ +# Acceleration + +In this command tree, all hardware acceleration options will be handled. +At the moment only [Intel® QAT](https://www.intel.com/content/www/us/en/architecture-and-technology/intel-quick-assist-technology-overview.html) is supported + +## Intel® QAT + +<div class="opcmd"> + +show system acceleration qat + +use this command to check if there is an Intel® QAT supported Processor in +your system. + +``` +vyos@vyos:~$ show system acceleration qat +01:00.0 Co-processor [0b40]: Intel Corporation Atom Processor C3000 Series QuickAssist Technology [8086:19e2] (rev 11) +``` + +if there is non device the command will show `` `No QAT device found ``\` + +</div> + +<div class="cfgcmd"> + +set system acceleration qat + +if there is a supported device, enable Intel® QAT + +</div> + +<div class="opcmd"> + +show system acceleration qat status + +Check if the Intel® QAT device is up and ready to do the job. + +``` +vyos@vyos:~$ show system acceleration qat status +Checking status of all devices. +There is 1 QAT acceleration device(s) in the system: +qat_dev0 - type: c3xxx, inst_id: 0, node_id: 0, bsf: 0000:01:00.0, #accel: 3 #engines: 6 state: up +``` + +</div> + +### Operation Mode + +<div class="opcmd"> + +show system acceleration qat device \<device\> config + +Show the full config uploaded to the QAT device. + +</div> + +<div class="opcmd"> + +show system acceleration qat device \<device\> flows + +Get an overview over the encryption counters. + +</div> + +<div class="opcmd"> + +show system acceleration qat interrupts + +Show binded qat device interrupts to certain core. + +</div> + +### Example + +Let's build a simple VPN between 2 Intel® QAT ready devices. + +Side A: + +``` +set interfaces vti vti1 address '192.168.1.2/24' +set vpn ipsec authentication psk right id '10.10.10.2' +set vpn ipsec authentication psk right id '10.10.10.1' +set vpn ipsec authentication psk right secret 'Qwerty123' +set vpn ipsec esp-group MyESPGroup proposal 1 encryption 'aes256' +set vpn ipsec esp-group MyESPGroup proposal 1 hash 'sha256' +set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group '14' +set vpn ipsec ike-group MyIKEGroup proposal 1 encryption 'aes256' +set vpn ipsec ike-group MyIKEGroup proposal 1 hash 'sha256' +set vpn ipsec interface 'eth0' +set vpn ipsec site-to-site peer right authentication local-id '10.10.10.2' +set vpn ipsec site-to-site peer right authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer right authentication remote-id '10.10.10.1' +set vpn ipsec site-to-site peer right connection-type 'initiate' +set vpn ipsec site-to-site peer right default-esp-group 'MyESPGroup' +set vpn ipsec site-to-site peer right ike-group 'MyIKEGroup' +set vpn ipsec site-to-site peer right local-address '10.10.10.2' +set vpn ipsec site-to-site peer right remote-address '10.10.10.1' +set vpn ipsec site-to-site peer right vti bind 'vti1' +``` + +Side B: + +``` +set interfaces vti vti1 address '192.168.1.1/24' +set vpn ipsec authentication psk left id '10.10.10.2' +set vpn ipsec authentication psk left id '10.10.10.1' +set vpn ipsec authentication psk left secret 'Qwerty123' +set vpn ipsec esp-group MyESPGroup proposal 1 encryption 'aes256' +set vpn ipsec esp-group MyESPGroup proposal 1 hash 'sha256' +set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group '14' +set vpn ipsec ike-group MyIKEGroup proposal 1 encryption 'aes256' +set vpn ipsec ike-group MyIKEGroup proposal 1 hash 'sha256' +set vpn ipsec interface 'eth0' +set vpn ipsec site-to-site peer left authentication local-id '10.10.10.1' +set vpn ipsec site-to-site peer left authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer left authentication remote-id '10.10.10.2' +set vpn ipsec site-to-site peer left connection-type 'initiate' +set vpn ipsec site-to-site peer left default-esp-group 'MyESPGroup' +set vpn ipsec site-to-site peer left ike-group 'MyIKEGroup' +set vpn ipsec site-to-site peer left local-address '10.10.10.1' +set vpn ipsec site-to-site peer left remote-address '10.10.10.2' +set vpn ipsec site-to-site peer left vti bind 'vti1' +``` + +a bandwidth test over the VPN got these results: + +``` +Connecting to host 192.168.1.2, port 5201 +[ 9] local 192.168.1.1 port 51344 connected to 192.168.1.2 port 5201 +[ ID] Interval Transfer Bitrate Retr Cwnd +[ 9] 0.00-1.01 sec 32.3 MBytes 268 Mbits/sec 0 196 KBytes +[ 9] 1.01-2.03 sec 32.5 MBytes 268 Mbits/sec 0 208 KBytes +[ 9] 2.03-3.03 sec 32.5 MBytes 271 Mbits/sec 0 208 KBytes +[ 9] 3.03-4.04 sec 32.5 MBytes 272 Mbits/sec 0 208 KBytes +[ 9] 4.04-5.00 sec 31.2 MBytes 272 Mbits/sec 0 208 KBytes +[ 9] 5.00-6.01 sec 32.5 MBytes 272 Mbits/sec 0 234 KBytes +[ 9] 6.01-7.04 sec 32.5 MBytes 265 Mbits/sec 0 234 KBytes +[ 9] 7.04-8.04 sec 32.5 MBytes 272 Mbits/sec 0 234 KBytes +[ 9] 8.04-9.04 sec 32.5 MBytes 273 Mbits/sec 0 336 KBytes +[ 9] 9.04-10.00 sec 31.2 MBytes 272 Mbits/sec 0 336 KBytes +- - - - - - - - - - - - - - - - - - - - - - - - - +[ ID] Interval Transfer Bitrate Retr +[ 9] 0.00-10.00 sec 322 MBytes 270 Mbits/sec 0 sender +[ 9] 0.00-10.00 sec 322 MBytes 270 Mbits/sec receiver +``` + +with `set system acceleration qat` on both systems the bandwidth +increases. + +``` +Connecting to host 192.168.1.2, port 5201 +[ 9] local 192.168.1.1 port 51340 connected to 192.168.1.2 port 5201 +[ ID] Interval Transfer Bitrate Retr Cwnd +[ 9] 0.00-1.00 sec 97.3 MBytes 817 Mbits/sec 0 1000 KBytes +[ 9] 1.00-2.00 sec 92.5 MBytes 776 Mbits/sec 0 1.07 MBytes +[ 9] 2.00-3.00 sec 92.5 MBytes 776 Mbits/sec 0 820 KBytes +[ 9] 3.00-4.00 sec 92.5 MBytes 776 Mbits/sec 0 899 KBytes +[ 9] 4.00-5.00 sec 91.2 MBytes 765 Mbits/sec 0 972 KBytes +[ 9] 5.00-6.00 sec 92.5 MBytes 776 Mbits/sec 0 1.02 MBytes +[ 9] 6.00-7.00 sec 92.5 MBytes 776 Mbits/sec 0 1.08 MBytes +[ 9] 7.00-8.00 sec 92.5 MBytes 776 Mbits/sec 0 1.14 MBytes +[ 9] 8.00-9.00 sec 91.2 MBytes 765 Mbits/sec 0 915 KBytes +[ 9] 9.00-10.00 sec 92.5 MBytes 776 Mbits/sec 0 1000 KBytes +- - - - - - - - - - - - - - - - - - - - - - - - - +[ ID] Interval Transfer Bitrate Retr +[ 9] 0.00-10.00 sec 927 MBytes 778 Mbits/sec 0 sender +[ 9] 0.00-10.01 sec 925 MBytes 775 Mbits/sec receiver +``` diff --git a/docs/configuration/system/md-conntrack.md b/docs/configuration/system/md-conntrack.md new file mode 100644 index 00000000..2d5afdfd --- /dev/null +++ b/docs/configuration/system/md-conntrack.md @@ -0,0 +1,473 @@ +# Conntrack + +VyOS can be configured to track connections using the connection +tracking subsystem. Connection tracking becomes operational once either +stateful firewall or NAT is configured. + +## Configure + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack table-size \<1-50000000\> + +The connection tracking table contains one entry for each connection being +tracked by the system. + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack expect-table-size \<1-50000000\> + +The connection tracking expect table contains one entry for each expected +connection related to an existing connection. These are generally used by +“connection tracking helper” modules such as FTP. +The default size of the expect table is 2048 entries. + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack hash-size \<1-50000000\> + +Set the size of the hash table. The connection tracking hash table makes +searching the connection tracking table faster. The hash table uses +“buckets” to record entries in the connection tracking table. + +</div> + +<div class="cfgcmd"> + +set system conntrack modules ftp + +</div> + +<div class="cfgcmd"> + +set system conntrack modules h323 + +</div> + +<div class="cfgcmd"> + +set system conntrack modules nfs + +</div> + +<div class="cfgcmd"> + +set system conntrack modules pptp + +</div> + +<div class="cfgcmd"> + +set system conntrack modules sip + +</div> + +<div class="cfgcmd"> + +set system conntrack modules sqlnet + +</div> + +<div class="cfgcmd"> + +set system conntrack modules tftp + +Configure the connection tracking protocol helper modules. +All modules are enable by default. + +Use <span class="title-ref">delete system conntrack modules</span> to deactive all modules.\ +Or, for example ftp, <span class="title-ref">delete system conntrack modules ftp</span>. + +</div> + +### Define Conection Timeouts + +VyOS supports setting timeouts for connections according to the +connection type. You can set timeout values for generic connections, for ICMP +connections, UDP connections, or for TCP connections in a number of different +states. + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout icmp \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout other \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout tcp close \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout tcp close-wait \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout tcp established \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout tcp fin-wait \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout tcp last-ack \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout tcp syn-recv \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout tcp syn-sent \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout tcp time-wait \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout udp other \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout udp stream \<1-21474836\> + +Set the timeout in secounds for a protocol or state. + +</div> + +You can also define custom timeout values to apply to a specific subset of +connections, based on a packet and flow selector. To do this, you need to +create a rule defining the packet and flow selector. + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> description \<test\> + +Set a rule description. + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> destination address \<ip-address\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> source address \<ip-address\> + +set a destination and/or source address. Accepted input: + +``` none +<x.x.x.x> IP address to match +<x.x.x.x/x> Subnet to match +<x.x.x.x>-<x.x.x.x> + IP range to match +!<x.x.x.x> Match everything except the specified address +!<x.x.x.x/x> Match everything except the specified subnet +!<x.x.x.x>-<x.x.x.x> + Match everything except the specified range +``` + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> destination port \<value\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> source port \<value\> + +Set a destination and/or source port. Accepted input: + +``` none +<port name> Named port (any name in /etc/services, e.g., http) +<1-65535> Numbered port +<start>-<end> Numbered port range (e.g., 1001-1005) +``` + +Multiple destination ports can be specified as a comma-separated list. +The whole list can also be "negated" using '!'. For example: +<span class="title-ref">!22,telnet,http,123,1001-1005</span>\` + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol icmp \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol other \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol tcp close \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol tcp close-wait \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol tcp established \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol tcp fin-wait \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol tcp last-ack \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol tcp syn-recv \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol tcp syn-sent \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol tcp time-wait \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol udp other \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol udp stream \<1-21474836\> + +Set the timeout in secounds for a protocol or state in a custom rule. + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack tcp half-open-connections \<1-21474836\> + +Set the maximum number of TCP half-open connections. + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack tcp loose \<enable | disable\> + +Policy to track previously established connections. + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack tcp max-retrans \<1-2147483647\> + +Set the number of TCP maximum retransmit attempts. + +</div> + +<div class="cfgcmd"> + +set system conntrack ignore rule \<1-9999\> description \<text\> + +</div> + +<div class="cfgcmd"> + +set system conntrack ignore rule \<1-9999\> destination address \<ip-address\> + +</div> + +<div class="cfgcmd"> + +set system conntrack ignore rule \<1-9999\> destination port \<port\> + +</div> + +<div class="cfgcmd"> + +set system conntrack ignore rule \<1-9999\> inbound-interface \<interface\> + +</div> + +<div class="cfgcmd"> + +set system conntrack ignore rule \<1-9999\> protocol \<protocol\> + +</div> + +<div class="cfgcmd"> + +set system conntrack ignore rule \<1-9999\> source address \<ip-address\> + +</div> + +<div class="cfgcmd"> + +set system conntrack ignore rule \<1-9999\> source port \<port\> + +Customized ignore rules, based on a packet and flow selector. + +</div> + +<div class="cfgcmd"> + +set system conntrack log icmp destroy + +</div> + +<div class="cfgcmd"> + +set system conntrack log icmp new + +</div> + +<div class="cfgcmd"> + +set system conntrack log icmp update + +</div> + +<div class="cfgcmd"> + +set system conntrack log other destroy + +</div> + +<div class="cfgcmd"> + +set system conntrack log other new + +</div> + +<div class="cfgcmd"> + +set system conntrack log other update + +</div> + +<div class="cfgcmd"> + +set system conntrack log tcp destroy + +</div> + +<div class="cfgcmd"> + +set system conntrack log tcp new + +</div> + +<div class="cfgcmd"> + +set system conntrack log tcp update close-wait + +</div> + +<div class="cfgcmd"> + +set system conntrack log tcp update established + +</div> + +<div class="cfgcmd"> + +set system conntrack log tcp update fin-wait + +</div> + +<div class="cfgcmd"> + +set system conntrack log tcp update last-ack + +</div> + +<div class="cfgcmd"> + +set system conntrack log tcp update syn-received + +</div> + +<div class="cfgcmd"> + +set system conntrack log tcp update time-wait + +</div> + +<div class="cfgcmd"> + +set system conntrack log udp destroy + +</div> + +<div class="cfgcmd"> + +set system conntrack log udp new + +</div> + +<div class="cfgcmd"> + +set system conntrack log udp update + +Log the connection tracking events per protocol. + +</div> diff --git a/docs/configuration/system/md-console.md b/docs/configuration/system/md-console.md new file mode 100644 index 00000000..3a58301d --- /dev/null +++ b/docs/configuration/system/md-console.md @@ -0,0 +1,59 @@ +# Serial Console + +For the average user a serial console has no advantage over a console offered +by a directly attached keyboard and screen. Serial consoles are much slower, +taking up to a second to fill a 80 column by 24 line screen. Serial consoles +generally only support non-proportional ASCII text, with limited support for +languages other than English. + +There are some scenarios where serial consoles are useful. System administration +of remote computers is usually done using `ssh`, but there are times when +access to the console is the only way to diagnose and correct software failures. +Major upgrades to the installed distribution may also require console access. + +<div class="cfgcmd"> + +set system console device \<device\> + +Defines the specified device as a system console. Available console devices +can be (see completion helper): + +- `ttySN` - Serial device name +- `ttyUSBX` - USB Serial device name +- `hvc0` - Xen console + +</div> + +<div class="cfgcmd"> + +set system console device \<device\> speed \<speed\> + +The speed (baudrate) of the console device. Supported values are: + +- `1200` - 1200 bps +- `2400` - 2400 bps +- `4800` - 4800 bps +- `9600` - 9600 bps +- `19200` - 19,200 bps +- `38400` - 38,400 bps (default for Xen console) +- `57600` - 57,600 bps +- `115200` - 115,200 bps (default for serial console) + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you use USB to serial converters for connecting to your VyOS +appliance please note that most of them use software emulation without flow +control. This means you should start with a common baud rate (most likely +9600 baud) as otherwise you probably can not connect to the device using +high speed baud rates as your serial converter simply can not process this +data rate. + +</div> + +</div> diff --git a/docs/configuration/system/md-default-route.md b/docs/configuration/system/md-default-route.md new file mode 100644 index 00000000..c973dc09 --- /dev/null +++ b/docs/configuration/system/md-default-route.md @@ -0,0 +1,48 @@ +# Default Gateway/Route + +In the past (VyOS 1.1) used a gateway-address configured under the system tree +(`set system gateway-address <address>`), this is no longer supported +and existing configurations are migrated to the new CLI command. + +## Configuration + +<div class="cfgcmd"> + +set protocols static route 0.0.0.0/0 next-hop \<address\> + +Specify static route into the routing table sending all non local traffic +to the nexthop address <span class="title-ref">\<address\></span>. + +</div> + +<div class="cfgcmd"> + +delete protocols static route 0.0.0.0/0 + +Delete default route from the system. + +</div> + +## Operation + +<div class="opcmd"> + +show ip route 0.0.0.0 + +Show routing table entry for the default route. + +``` none +vyos@vyos:~$ show ip route 0.0.0.0 +Routing entry for 0.0.0.0/0 + Known via "static", distance 10, metric 0, best + Last update 09:46:30 ago + * 172.18.201.254, via eth0.201 +``` + +</div> + +<div class="seealso"> + +Configuration of `routing-static` + +</div> diff --git a/docs/configuration/system/md-flow-accounting.md b/docs/configuration/system/md-flow-accounting.md new file mode 100644 index 00000000..3a66fce5 --- /dev/null +++ b/docs/configuration/system/md-flow-accounting.md @@ -0,0 +1,312 @@ +# Flow Accounting + +VyOS supports flow-accounting for both IPv4 and IPv6 traffic. The system acts +as a flow exporter, and you are free to use it with any compatible collector. + +Flows can be exported via two different protocols: NetFlow (versions 5, 9 and +10/IPFIX) and sFlow. Additionally, you may save flows to an in-memory table +internally in a router. + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +You need to disable the in-memory table in production environments! +Using `IMT (In-Memory Table)` may lead to heavy CPU overloading and +unstable flow-accounting behavior. + +</div> + +## NetFlow / IPFIX + +NetFlow is a feature that was introduced on Cisco routers around 1996 that +provides the ability to collect IP network traffic as it enters or exits an +interface. By analyzing the data provided by NetFlow, a network administrator +can determine things such as the source and destination of traffic, class of +service, and the causes of congestion. A typical flow monitoring setup (using +NetFlow) consists of three main components: + +- **exporter**: aggregates packets into flows and exports flow records towards + one or more flow collectors +- **collector**: responsible for reception, storage and pre-processing of flow + data received from a flow exporter +- **application**: analyzes received flow data in the context of intrusion + detection or traffic profiling, for example + +For connectionless protocols as like ICMP and UDP, a flow is considered +complete once no more packets for this flow appear after configurable timeout. + +NetFlow is usually enabled on a per-interface basis to limit load on the router +components involved in NetFlow, or to limit the amount of NetFlow records +exported. + +## Configuration + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +Using NetFlow on routers with high traffic levels may lead to +high CPU usage and may affect the router's performance. In such cases, +consider using sFlow instead. + +</div> + +In order for flow accounting information to be collected and displayed for an +interface, the interface must be configured for flow accounting. + +<div class="cfgcmd"> + +set system flow-accounting interface \<interface\> + +Configure and enable collection of flow information for the interface +identified by <span class="title-ref">\<interface\></span>. + +You can configure multiple interfaces which whould participate in flow +accounting. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Will be recorded only packets/flows on **incoming** direction in +configured interfaces by default. + +</div> + +By default, recorded flows will be saved internally and can be listed with the +CLI command. You may disable using the local in-memory table with the command: + +<div class="cfgcmd"> + +set system flow-accounting disable-imt + +If you need to sample also egress traffic, you may want to +configure egress flow-accounting: + +</div> + +<div class="cfgcmd"> + +set system flow-accounting enable-egress + +Internally, in flow-accounting processes exist a buffer for data exchanging +between core process and plugins (each export target is a separated plugin). +If you have high traffic levels or noted some problems with missed records +or stopping exporting, you may try to increase a default buffer size (10 +MiB) with the next command: + +</div> + +<div class="cfgcmd"> + +set system flow-accounting buffer-size \<buffer size\> + +In case, if you need to catch some logs from flow-accounting daemon, you may +configure logging facility: + +</div> + +<div class="cfgcmd"> + +set system flow-accounting syslog-facility \<facility\> + +TBD + +</div> + +### Flow Export + +In addition to displaying flow accounting information locally, one can also +exported them to a collection server. + +#### NetFlow + +<div class="cfgcmd"> + +set system flow-accounting netflow version \<version\> + +There are multiple versions available for the NetFlow data. The <span class="title-ref">\<version\></span> +used in the exported flow data can be configured here. The following +versions are supported: + +- **5** - Most common version, but restricted to IPv4 flows only +- **9** - NetFlow version 9 (default) +- **10** - `IPFIX (IP Flow Information Export)` as per `3917` + +</div> + +<div class="cfgcmd"> + +set system flow-accounting netflow server \<address\> + +Configure address of NetFlow collector. NetFlow server at <span class="title-ref">\<address\></span> can +be both listening on an IPv4 or IPv6 address. + +</div> + +<div class="cfgcmd"> + +set system flow-accounting netflow source-ip \<address\> + +IPv4 or IPv6 source address of NetFlow packets + +</div> + +<div class="cfgcmd"> + +set system flow-accounting netflow engine-id \<id\> + +NetFlow engine-id which will appear in NetFlow data. The range is 0 to 255. + +</div> + +<div class="cfgcmd"> + +set system flow-accounting netflow sampling-rate \<rate\> + +Use this command to configure the sampling rate for flow accounting. The +system samples one in every <span class="title-ref">\<rate\></span> packets, where <span class="title-ref">\<rate\></span> is the value +configured for the sampling-rate option. The advantage of sampling every n +packets, where n \> 1, allows you to decrease the amount of processing +resources required for flow accounting. The disadvantage of not sampling +every packet is that the statistics produced are estimates of actual data +flows. + +Per default every packet is sampled (that is, the sampling rate is 1). + +</div> + +<div class="cfgcmd"> + +set system flow-accounting netflow timeout expiry-interval +\<interval\> + +Specifies the interval at which Netflow data will be sent to a collector. As +per default, Netflow data will be sent every 60 seconds. + +You may also additionally configure timeouts for different types of +connections. + +</div> + +<div class="cfgcmd"> + +set system flow-accounting netflow max-flows \<n\> + +If you want to change the maximum number of flows, which are tracking +simultaneously, you may do this with this command (default 8192). + +</div> + +#### sFlow + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Using <span class="title-ref">system sflow</span> is recommended in favor of +<span class="title-ref">system flow-accounting</span>. See [sflow](sflow.html) + +</div> + +<div class="cfgcmd"> + +set system flow-accounting sflow server \<address\> + +Configure address of sFlow collector. sFlow server at <span class="title-ref">\<address\></span> can +be an IPv4 or IPv6 address. But you cannot export to both IPv4 and +IPv6 collectors at the same time! + +</div> + +<div class="cfgcmd"> + +set system flow-accounting sflow sampling-rate \<rate\> + +Enable sampling of packets, which will be transmitted to sFlow collectors. + +</div> + +<div class="cfgcmd"> + +set system flow-accounting sflow agent-address \<address\> + +Configure a sFlow agent address. It can be IPv4 or IPv6 address, but you +must set the same protocol, which is used for sFlow collector addresses. By +default, using router-id from BGP or OSPF protocol, or the primary IP +address from the first interface. + +</div> + +### Example: + +NetFlow v5 example: + +``` none +set system flow-accounting netflow engine-id 100 +set system flow-accounting netflow version 5 +set system flow-accounting netflow server 192.168.2.10 port 2055 +``` + +## Operation + +Once flow accounting is configured on an interfaces it provides the ability to +display captured network traffic information for all configured interfaces. + +<div class="opcmd"> + +show flow-accounting interface \<interface\> + +Show flow accounting information for given <span class="title-ref">\<interface\></span>. + +``` none +vyos@vyos:~$ show flow-accounting interface eth0 +IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES +---------- ----------------- ----------------- ------------------------ --------------- ---------- ---------- ---------- ----- --------- ------- ------- +eth0 00:53:01:a8:28:ac ff:ff:ff:ff:ff:ff 192.0.2.2 255.255.255.255 5678 5678 udp 0 1 1 178 +eth0 00:53:01:b2:2f:34 33:33:ff:00:00:00 fe80::253:01ff:feb2:2f34 ff02::1:ff00:0 0 0 ipv6-icmp 0 2 1 144 +eth0 00:53:01:1a:b4:53 33:33:ff:00:00:00 fe80::253:01ff:fe1a:b453 ff02::1:ff00:0 0 0 ipv6-icmp 0 1 1 72 +eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 39 1 2064 +eth0 00:53:01:c8:33:af ff:ff:ff:ff:ff:ff 192.0.2.3 255.255.255.255 5678 5678 udp 0 1 1 154 +eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 146 1 9444 +eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 27 1 4455 +``` + +</div> + +<div class="opcmd"> + +show flow-accounting interface \<interface\> host \<address\> + +Show flow accounting information for given <span class="title-ref">\<interface\></span> for a specific host +only. + +``` none +vyos@vyos:~$ show flow-accounting interface eth0 host 192.0.2.14 +IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES +---------- ----------------- ----------------- ----------- ---------- ---------- ---------- ---------- ----- --------- ------- ------- +eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 197 2 12940 +eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 94 1 4924 +eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 36 1 5877 +``` + +</div> diff --git a/docs/configuration/system/md-frr.md b/docs/configuration/system/md-frr.md new file mode 100644 index 00000000..7116d1de --- /dev/null +++ b/docs/configuration/system/md-frr.md @@ -0,0 +1,50 @@ +# FRR + +VyOS uses \[FRRouting\](<https://frrouting.org/>) as the control plane for dynamic +and static routing. The routing daemon behavior can be adjusted during runtime, +but require either a restart of the routing daemon, or a reboot of the system. + +<div class="cfgcmd"> + +set system frr bmp + +Enable `BMP (BGP Monitoring Protocol)` support + +</div> + +<div class="cfgcmd"> + +set system frr descriptors \<numer\> + +This allows the operator to control the number of open file descriptors +each daemon is allowed to start with. If the operator plans to run bgp with +several thousands of peers then this is where we would modify FRR to allow +this to happen. + +</div> + +<div class="cfgcmd"> + +set system frr irdp + +Enable ICMP Router Discovery Protocol support + +</div> + +<div class="cfgcmd"> + +set system frr snmp \<daemon\> + +Enable SNMP support for an individual routing daemon. + +Supported daemons: + +- bgpd +- isisd +- ldpd +- ospf6d +- ospfd +- ripd +- zebra + +</div> diff --git a/docs/configuration/system/md-host-name.md b/docs/configuration/system/md-host-name.md new file mode 100644 index 00000000..ebb83a5f --- /dev/null +++ b/docs/configuration/system/md-host-name.md @@ -0,0 +1,86 @@ +# Host Information + +This section describes the system's host information and how to configure them, +it covers the following topics: + +- Host name +- Domain +- IP address +- Aliases + +## Hostname + +A hostname is the label (name) assigned to a network device (a host) on a +network and is used to distinguish one device from another on specific networks +or over the internet. On the other hand this will be the name which appears on +the command line prompt. + +<div class="cfgcmd"> + +set system host-name \<hostname\> + +The hostname can be up to 63 characters. A hostname +must start and end with a letter or digit, and have as interior characters +only letters, digits, or a hyphen. + +The default hostname used is <span class="title-ref">vyos</span>. + +</div> + +## Domain Name + +A domain name is the label (name) assigned to a computer network and is thus +unique. VyOS appends the domain name as a suffix to any unqualified name. For +example, if you set the domain name <span class="title-ref">example.com</span>, and you would ping the +unqualified name of <span class="title-ref">crux</span>, then VyOS qualifies the name to <span class="title-ref">crux.example.com</span>. + +<div class="cfgcmd"> + +set system domain-name \<domain\> + +Configure system domain name. A domain name must start and end with a letter +or digit, and have as interior characters only letters, digits, or a hyphen. + +</div> + +## Static Hostname Mapping + +How an IP address is assigned to an interface in `ethernet-interface`. +This section shows how to statically map an IP address to a hostname for local +(meaning on this VyOS instance) name resolution. This is the VyOS equivalent to +<span class="title-ref">/etc/hosts</span> file entries. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Do *not* manually edit <span class="title-ref">/etc/hosts</span>. This file will automatically be +regenerated on boot based on the settings in this section, which means you'll +lose all your manual edits. Instead, configure static host mappings as follows. + +</div> + +<div class="cfgcmd"> + +set system static-host-mapping host-name \<hostname\> inet \<address\> + +Create a static hostname mapping which will always resolve the name +<span class="title-ref">\<hostname\></span> to IP address <span class="title-ref">\<address\></span>. + +</div> + +<div class="cfgcmd"> + +set system static-host-mapping host-name \<hostname\> alias \<alias\> + +Create named <span class="title-ref">\<alias\></span> for the configured static mapping for <span class="title-ref">\<hostname\></span>. +Thus the address configured as `set system static-host-mapping +host-name <hostname> inet <address>` can be reached via multiple names. + +Multiple aliases can be specified per host-name. + +</div> diff --git a/docs/configuration/system/md-index.md b/docs/configuration/system/md-index.md new file mode 100644 index 00000000..ea77a2c6 --- /dev/null +++ b/docs/configuration/system/md-index.md @@ -0,0 +1,31 @@ +# System + +<div class="toctree" maxdepth="1" includehidden=""> + +acceleration +conntrack +console +flow-accounting +frr +host-name +ip +ipv6 +lcd +login +name-server +option +proxy +sflow +syslog +sysctl +task-scheduler +time-zone +updates + +</div> + +<div class="toctree" maxdepth="1" includehidden=""> + +default-route + +</div> diff --git a/docs/configuration/system/md-ip.md b/docs/configuration/system/md-ip.md new file mode 100644 index 00000000..cbdc53c4 --- /dev/null +++ b/docs/configuration/system/md-ip.md @@ -0,0 +1,132 @@ +# IP + +## System configuration commands + +<div class="cfgcmd"> + +set system ip disable-forwarding + +Use this command to disable IPv4 forwarding on all interfaces. + +</div> + +<div class="cfgcmd"> + +set system ip disable-directed-broadcast + +Use this command to disable IPv4 directed broadcast forwarding on all +interfaces. + +If set, IPv4 directed broadcast forwarding will be completely disabled +regardless of whether per-interface directed broadcast forwarding is +enabled or not. + +</div> + +<div class="cfgcmd"> + +set system ip arp table-size \<number\> + +Use this command to define the maximum number of entries to keep in +the ARP cache (1024, 2048, 4096, 8192, 16384, 32768). + +</div> + +<div class="cfgcmd"> + +set system ip multipath layer4-hashing + +Use this command to use Layer 4 information for IPv4 ECMP hashing. + +</div> + +### Zebra/Kernel route filtering + +Zebra supports prefix-lists and Route Mapss to match routes received from +other FRR components. The permit/deny facilities provided by these commands +can be used to filter which routes zebra will install in the kernel. + +<div class="cfgcmd"> + +set system ip protocol \<protocol\> route-map \<route-map\> + +Apply a route-map filter to routes for the specified protocol. The following +protocols can be used: any, babel, bgp, connected, eigrp, isis, kernel, +ospf, rip, static, table + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you choose any as the option that will cause all protocols that +are sending routes to zebra. + +</div> + +</div> + +### Nexthop Tracking + +Nexthop tracking resolve nexthops via the default route by default. This is enabled +by default for a traditional profile of FRR which we use. It and can be disabled if +you do not wan't to e.g. allow BGP to peer across the default route. + +<div class="cfgcmd"> + +set system ip nht no-resolve-via-default + +Do not allow IPv4 nexthop tracking to resolve via the default route. This +parameter is configured per-VRF, so the command is also available in the VRF +subnode. + +</div> + +## Operational commands + +### show commands + +See below the different parameters available for the IPv4 **show** command: + +``` none +vyos@vyos:~$ show ip +Possible completions: + access-list Show all IP access-lists + as-path-access-list + Show all as-path-access-lists + bgp Show Border Gateway Protocol (BGP) information + community-list + Show IP community-lists + extcommunity-list + Show extended IP community-lists + forwarding Show IP forwarding status + groups Show IP multicast group membership + igmp Show IGMP (Internet Group Management Protocol) information + large-community-list + Show IP large-community-lists + multicast Show IP multicast + ospf Show IPv4 Open Shortest Path First (OSPF) routing information + pim Show PIM (Protocol Independent Multicast) information + ports Show IP ports in use by various system services + prefix-list Show all IP prefix-lists + protocol Show IP route-maps per protocol + rip Show Routing Information Protocol (RIP) information + route Show IP routes +``` + +### reset commands + +And the different IPv4 **reset** commands available: + +``` none +vyos@vyos:~$ reset ip +Possible completions: + arp Reset Address Resolution Protocol (ARP) cache + bgp Clear Border Gateway Protocol (BGP) statistics or status + igmp IGMP clear commands + multicast IP multicast routing table + route Reset IP route +``` diff --git a/docs/configuration/system/md-ipv6.md b/docs/configuration/system/md-ipv6.md new file mode 100644 index 00000000..47b775e6 --- /dev/null +++ b/docs/configuration/system/md-ipv6.md @@ -0,0 +1,278 @@ +# IPv6 + +## System configuration commands + +<div class="cfgcmd"> + +set system ipv6 disable-forwarding + +Use this command to disable IPv6 forwarding on all interfaces. + +</div> + +<div class="cfgcmd"> + +set system ipv6 neighbor table-size \<number\> + +Use this command to define the maximum number of entries to keep in +the Neighbor cache (1024, 2048, 4096, 8192, 16384, 32768). + +</div> + +<div class="cfgcmd"> + +set system ipv6 strict-dad + +Use this command to disable IPv6 operation on interface when +Duplicate Address Detection fails on Link-Local address. + +</div> + +<div class="cfgcmd"> + +set system ipv6 multipath layer4-hashing + +Use this command to user Layer 4 information for ECMP hashing. + +</div> + +### Zebra/Kernel route filtering + +Zebra supports prefix-lists and Route Mapss to match routes received from +other FRR components. The permit/deny facilities provided by these commands +can be used to filter which routes zebra will install in the kernel. + +<div class="cfgcmd"> + +set system ipv6 protocol \<protocol\> route-map \<route-map\> + +Apply a route-map filter to routes for the specified protocol. The following +protocols can be used: any, babel, bgp, connected, isis, kernel, ospfv3, +ripng, static, table + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you choose any as the option that will cause all protocols that +are sending routes to zebra. + +</div> + +</div> + +### Nexthop Tracking + +Nexthop tracking resolve nexthops via the default route by default. This is enabled +by default for a traditional profile of FRR which we use. It and can be disabled if +you do not wan't to e.g. allow BGP to peer across the default route. + +<div class="cfgcmd"> + +set system ipv6 nht no-resolve-via-default + +Do not allow IPv6 nexthop tracking to resolve via the default route. This +parameter is configured per-VRF, so the command is also available in the VRF +subnode. + +</div> + +## Operational commands + +### Show commands + +<div class="opcmd"> + +show ipv6 neighbors + +Use this command to show IPv6 Neighbor Discovery Protocol information. + +</div> + +<div class="opcmd"> + +show ipv6 groups + +Use this command to show IPv6 multicast group membership. + +</div> + +<div class="opcmd"> + +show ipv6 forwarding + +Use this command to show IPv6 forwarding status. + +</div> + +<div class="opcmd"> + +show ipv6 route + +Use this command to show IPv6 routes. + +Check the many parameters available for the <span class="title-ref">show ipv6 route</span> command: + +``` none +vyos@vyos:~$ show ipv6 route +Possible completions: + <Enter> Execute the current command + <X:X::X:X> Show IPv6 routes of given address or prefix + <X:X::X:X/M> + bgp Show IPv6 BGP routes + cache Show kernel IPv6 route cache + connected Show IPv6 connected routes + forward Show kernel IPv6 route table + isis Show IPv6 ISIS routes + kernel Show IPv6 kernel routes + ospfv3 Show IPv6 OSPF6 routes + ripng Show IPv6 RIPNG routes + static Show IPv6 static routes + summary Show IPv6 routes summary + table Show IP routes in policy table + vrf Show IPv6 routes in VRF +``` + +</div> + +<div class="opcmd"> + +show ipv6 prefix-list + +Use this command to show all IPv6 prefix lists + +There are different parameters for getting prefix-list information: + +``` none +vyos@vyos:~$ show ipv6 prefix-list +Possible completions: + <Enter> Execute the current command + <WORD> Show specified IPv6 prefix-list + detail Show detail of IPv6 prefix-lists + summary Show summary of IPv6 prefix-lists +``` + +</div> + +<div class="opcmd"> + +show ipv6 access-list + +Use this command to show all IPv6 access lists + +You can also specify which IPv6 access-list should be shown: + +``` none +vyos@vyos:~$ show ipv6 access-list +Possible completions: + <Enter> Execute the current command + <text> Show specified IPv6 access-list +``` + +</div> + +<div class="opcmd"> + +show ipv6 bgp + +Use this command to show IPv6 Border Gateway Protocol information. + +In addition, you can specify many other parameters to get BGP +information: + +``` none +vyos@vyos:~$ show ipv6 bgp +Possible completions: + <Enter> Execute the current command + <X:X::X:X> Show BGP information for given address or prefix + <X:X::X:X/M> + community Show routes matching the communities + community-list + Show routes matching the community-list + filter-list Show routes conforming to the filter-list + large-community + Show routes matching the large-community-list + large-community-list + neighbors Show detailed information on TCP and BGP neighbor connections + prefix-list Show routes matching the prefix-list + regexp Show routes matching the AS path regular expression + route-map Show BGP routes matching the specified route map + summary Show summary of BGP neighbor status +``` + +</div> + +<div class="opcmd"> + +show ipv6 ospfv3 + +Use this command to get information about OSPFv3. + +You can get more specific OSPFv3 information by using the parameters +shown below: + +``` none +vyos@vyos:~$ show ipv6 ospfv3 +Possible completions: + <Enter> Execute the current command + area Show OSPFv3 spf-tree information + border-routers + Show OSPFv3 border-router (ABR and ASBR) information + database Show OSPFv3 Link state database information + interface Show OSPFv3 interface information + linkstate Show OSPFv3 linkstate routing information + neighbor Show OSPFv3 neighbor information + redistribute Show OSPFv3 redistribute External information + route Show OSPFv3 routing table information +``` + +</div> + +<div class="opcmd"> + +show ipv6 ripng + +Use this command to get information about the RIPNG protocol + +</div> + +<div class="opcmd"> + +show ipv6 ripng status + +Use this command to show the status of the RIPNG protocol + +</div> + +### Reset commands + +<div class="opcmd"> + +reset bgp ipv6 \<address\> + +Use this command to clear Border Gateway Protocol statistics or +status. + +</div> + +<div class="opcmd"> + +reset ipv6 neighbors \<address | interface\> + +Use this command to reset IPv6 Neighbor Discovery Protocol cache for +an address or interface. + +</div> + +<div class="opcmd"> + +reset ipv6 route cache + +Use this command to flush the kernel IPv6 route cache. +An address can be added to flush it only for that route. + +</div> diff --git a/docs/configuration/system/md-lcd.md b/docs/configuration/system/md-lcd.md new file mode 100644 index 00000000..b5a50b3c --- /dev/null +++ b/docs/configuration/system/md-lcd.md @@ -0,0 +1,52 @@ +# System Display (LCD) + +The system LCD `LCD (Liquid-crystal display)` option is for users running +VyOS on hardware that features an LCD display. This is typically a small display +built in an 19 inch rack-mountable appliance. Those displays are used to show +runtime data. + +To configure your LCD display you must first identify the used hardware, and +connectivity of the display to your system. This can be any serial port +(<span class="title-ref">ttySxx</span>) or serial via USB or even old parallel port interfaces. + +## Configuration + +<div class="cfgcmd"> + +set system lcd device \<device\> + +This is the name of the physical interface used to connect to your LCD +display. Tab completion is supported and it will list you all available +serial interface. + +For serial via USB port information please refor to: `hardware_usb`. + +</div> + +<div class="cfgcmd"> + +set system lcd model \<model\> + +This is the LCD model used in your system. + +At the time of this writing the following displays are supported: + +- Crystalfontz CFA-533 +- Crystalfontz CFA-631 +- Crystalfontz CFA-633 +- Crystalfontz CFA-635 + +<div class="note"> + +<div class="title"> + +Note + +</div> + +We can't support all displays from the beginning. If your display +type is missing, please create a feature request via [Phabricator](). + +</div> + +</div> diff --git a/docs/configuration/system/md-login.md b/docs/configuration/system/md-login.md new file mode 100644 index 00000000..253e3673 --- /dev/null +++ b/docs/configuration/system/md-login.md @@ -0,0 +1,549 @@ +lastproofread +2022-10-15 + +# Login/User Management + +The default VyOS user account (<span class="title-ref">vyos</span>), as well as newly created user accounts, +have all capabilities to configure the system. All accounts have sudo +capabilities and therefore can operate as root on the system. + +Both local administered and remote administered `RADIUS (Remote +Authentication Dial-In User Service)` accounts are supported. + +## Local + +<div class="cfgcmd"> + +set system login user \<name\> full-name "\<string\>" + +Create new system user with username <span class="title-ref">\<name\></span> and real-name specified by +<span class="title-ref">\<string\></span>. + +</div> + +<div class="cfgcmd"> + +set system login user \<name\> authentication plaintext-password +\<password\> + +Specify the plaintext password user by user <span class="title-ref">\<name\></span> on this system. The +plaintext password will be automatically transferred into a secure hashed +password and not saved anywhere in plaintext. + +</div> + +<div class="cfgcmd"> + +set system login user \<name\> authentication encrypted-password +\<password\> + +Setup encrypted password for given username. This is useful for +transferring a hashed password from system to system. + +</div> + +<div class="cfgcmd"> + +set system login user \<name\> disable + +Disable (lock) account. User will not be able to log in. + +</div> + +### Key Based Authentication + +It is highly recommended to use SSH key authentication. By default there is +only one user (`vyos`), and you can assign any number of keys to that user. +You can generate a ssh key with the `ssh-keygen` command on your local +machine, which will (by default) save it as `~/.ssh/id_rsa.pub`. + +Every SSH key comes in three parts: + +`ssh-rsa AAAAB3NzaC1yc2EAAAABAA...VBD5lKwEWB username@host.example.com` + +Only the type (`ssh-rsa`) and the key (`AAAB3N...`) are used. Note that the +key will usually be several hundred characters long, and you will need to copy +and paste it. Some terminal emulators may accidentally split this over several +lines. Be attentive when you paste it that it only pastes as a single line. +The third part is simply an identifier, and is for your own reference. + +<div class="seealso"> + +SSH `ssh_operation` + +</div> + +<div class="cfgcmd"> + +set system login user \<username\> authentication public-keys +\<identifier\> key \<key\> + +Assign the SSH public key portion <span class="title-ref">\<key\></span> identified by per-key +<span class="title-ref">\<identifier\></span> to the local user <span class="title-ref">\<username\></span>. + +</div> + +<div class="cfgcmd"> + +set system login user \<username\> authentication public-keys +\<identifier\> type \<type\> + +Every SSH public key portion referenced by <span class="title-ref">\<identifier\></span> requires the +configuration of the <span class="title-ref">\<type\></span> of public-key used. This type can be any of: + +- `ecdsa-sha2-nistp256` +- `ecdsa-sha2-nistp384` +- `ecdsa-sha2-nistp521` +- `ssh-dss` +- `ssh-ed25519` +- `ssh-rsa` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +You can assign multiple keys to the same user by using a unique +identifier per SSH key. + +</div> + +</div> + +<div class="cfgcmd"> + +set system login user \<username\> authentication public-keys +\<identifier\> options \<options\> + +Set the options for this public key. See the ssh `authorized_keys` man +page for details of what you can specify here. To place a `"` +character in the options field, use `"`, for example +`from="10.0.0.0/24"` to restrict where the user +may connect from when using this key. + +</div> + +### MFA/2FA authentication using OTP (one time passwords) + +It is possible to enhance authentication security by using the `2FA +(Two-factor authentication)`/`MFA (Multi-factor authentication)` feature +together with `OTP (One-Time-Pad)` on VyOS. `2FA (Two-factor +authentication)`/`MFA (Multi-factor authentication)` is configured +independently per each user. If an OTP key is configured for a user, 2FA/MFA +is automatically enabled for that particular user. If a user does not have an +OTP key configured, there is no 2FA/MFA check for that user. + +<div class="cfgcmd"> + +set system login user \<username\> authentication otp key \<key\> + +Enable OTP 2FA for user <span class="title-ref">username</span> with default settings, using the BASE32 +encoded 2FA/MFA key specified by <span class="title-ref">\<key\></span>. + +</div> + +#### Optional/default settings + +<div class="cfgcmd" defaultvalue=""> + +set system login user \<username\> authentication otp rate-limit \<limit\> + +Limit logins to <span class="title-ref">\<limit\></span> per every `rate-time` seconds. Rate limit +must be between 1 and 10 attempts. + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system login user \<username\> authentication otp rate-time \<seconds\> + +Limit logins to `rate-limit` attemps per every <span class="title-ref">\<seconds\></span>. Rate time must +be between 15 and 600 seconds. + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system login user \<username\> authentication otp window-size \<size\> + +Set window of concurrently valid codes. + +By default, a new token is generated every 30 seconds by the mobile +application. In order to compensate for possible time-skew between +the client and the server, an extra token before and after the current +time is allowed. This allows for a time skew of up to 30 seconds +between authentication server and client. + +For example, if problems with poor time synchronization are experienced, +the window can be increased from its default size of 3 permitted codes +(one previous code, the current code, the next code) to 17 permitted codes +(the 8 previous codes, the current code, and the 8 next codes). This will +permit for a time skew of up to 4 minutes between client and server. + +The window size must be between 1 and 21. + +</div> + +#### OTP-key generation + +The following command can be used to generate the OTP key as well +as the CLI commands to configure them: + +<div class="cfgcmd"> + +generate system login username \<username\> otp-key hotp-time +rate-limit \<1-10\> rate-time \<15-600\> window-size \<1-21\> + +</div> + +An example of key generation: + +``` none +vyos@vyos:~$ generate system login username otptester otp-key hotp-time rate-limit 2 rate-time 20 window-size 5 +# You can share it with the user, he just needs to scan the QR in his OTP app +# username: otptester +# OTP KEY: J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY +# OTP URL: otpauth://totp/otptester@vyos?secret=J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY&digits=6&period=30 +█████████████████████████████████████████████ +█████████████████████████████████████████████ +████ ▄▄▄▄▄ █▀█ █▄ ▀▄▀▄█▀▄ ▀█▀ █ ▄▄▄▄▄ ████ +████ █ █ █▀▀▀█ ▄▀ █▄▀ ▀▄ ▄ ▀ ▄█ █ █ ████ +████ █▄▄▄█ █▀ █▀▀██▄▄ █ █ ██ ▀▄▀ █ █▄▄▄█ ████ +████▄▄▄▄▄▄▄█▄▀ ▀▄█ █ ▀ █ █ █ █▄█▄█▄▄▄▄▄▄▄████ +████ ▄ █▄ ▄ ▀▄▀▀▀▀▄▀▄▀▄▄▄▀▀▄▄▄ █ █▄█ █████ +████▄▄ ██▀▄▄▄▀▀█▀ ▄ ▄▄▄ ▄▀ ▀ █ ▄ ▄ ██▄█ ████ +█████▄ ██▄▄▀█▄█▄█▄ ▀█▄▀▄ ▀█▀▄ █▄▄▄ ▄ ▄████ +████▀▀▄ ▄█▀▄▀ ▄█▀█▀▄▄▄▀█▄ ██▄▄▄ ▀█ █ ████ +████ ▄▀▄█▀▄▄█▀▀▄▀▀▀▀█ ▄▀▄▀ ▄█ ▀▄ ▄ ▄▀ █▄████ +████▄ ██ ▀▄▀▀ ▄█▀ ▄ ██ ▀█▄█ ▄█ ▄ ▀▄ ▄▄ ████ +████▄█▀▀▄ ▄▄ █▄█▄█▄ █▄▄▀▄▄▀▀▄▄██▀ ▄▀▄▄ ▀▄████ +████▀▄▀ ▄ ▄▀█ ▄ ▄█▀ █ ▀▄▄ ▄█▀ ▄▄ ▀▄▄ ████ +████ ▀███▄ █▄█▄▀▀▀▀▄ ▄█▄▄▀ ▀███ ▄▄█▄▄ ▄████ +████ ███▀ ▄▄▀▀██▀ ▄▀▄█▄▄▄ ██▄▄▀▄▀ ███▄ ▄████ +████▄████▄▄▄▀▄ █▄█▄▀▄▄▄▄██▀ ▄▀ ▄ ▄▄▄ █▄▄█████ +████ ▄▄▄▄▄ █▄▄▄ ▄█▀█▀▀▀▀█▀█▀ █▄█ █▄█ ▄█ ████ +████ █ █ █ ██▄▀▀▀▀▄▄▄▀ ▄▄▄ ▀ ▄ ▄ ▄▄████ +████ █▄▄▄█ █ ▀▀█▀ ▄▄█ █▄▄██▀▀█▀ █▄▀▄██▄█ ████ +████▄▄▄▄▄▄▄█▄█▄█▄█▄▄▄▄▄█▄▄▄█▄██████▄██▄▄▄████ +█████████████████████████████████████████████ +█████████████████████████████████████████████ +# To add this OTP key to configuration, run the following commands: +set system login user otptester authentication otp key 'J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY' +set system login user otptester authentication otp rate-limit '2' +set system login user otptester authentication otp rate-time '20' +set system login user otptester authentication otp window-size '5' +``` + +#### Display OTP key for user + +To display the configured OTP user key, use the command: + +<div class="cfgcmd"> + +sh system login authentication user \<username\> otp +\<full[|key-b32|](##SUBST##|key-b32|)qrcode|uri\> + +</div> + +An example: + +``` none +vyos@vyos:~$ sh system login authentication user otptester otp full +# You can share it with the user, he just needs to scan the QR in his OTP app +# username: otptester +# OTP KEY: J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY +# OTP URL: otpauth://totp/otptester@vyos?secret=J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY&digits=6&period=30 +█████████████████████████████████████████████ +█████████████████████████████████████████████ +████ ▄▄▄▄▄ █▀█ █▄ ▀▄▀▄█▀▄ ▀█▀ █ ▄▄▄▄▄ ████ +████ █ █ █▀▀▀█ ▄▀ █▄▀ ▀▄ ▄ ▀ ▄█ █ █ ████ +████ █▄▄▄█ █▀ █▀▀██▄▄ █ █ ██ ▀▄▀ █ █▄▄▄█ ████ +████▄▄▄▄▄▄▄█▄▀ ▀▄█ █ ▀ █ █ █ █▄█▄█▄▄▄▄▄▄▄████ +████ ▄ █▄ ▄ ▀▄▀▀▀▀▄▀▄▀▄▄▄▀▀▄▄▄ █ █▄█ █████ +████▄▄ ██▀▄▄▄▀▀█▀ ▄ ▄▄▄ ▄▀ ▀ █ ▄ ▄ ██▄█ ████ +█████▄ ██▄▄▀█▄█▄█▄ ▀█▄▀▄ ▀█▀▄ █▄▄▄ ▄ ▄████ +████▀▀▄ ▄█▀▄▀ ▄█▀█▀▄▄▄▀█▄ ██▄▄▄ ▀█ █ ████ +████ ▄▀▄█▀▄▄█▀▀▄▀▀▀▀█ ▄▀▄▀ ▄█ ▀▄ ▄ ▄▀ █▄████ +████▄ ██ ▀▄▀▀ ▄█▀ ▄ ██ ▀█▄█ ▄█ ▄ ▀▄ ▄▄ ████ +████▄█▀▀▄ ▄▄ █▄█▄█▄ █▄▄▀▄▄▀▀▄▄██▀ ▄▀▄▄ ▀▄████ +████▀▄▀ ▄ ▄▀█ ▄ ▄█▀ █ ▀▄▄ ▄█▀ ▄▄ ▀▄▄ ████ +████ ▀███▄ █▄█▄▀▀▀▀▄ ▄█▄▄▀ ▀███ ▄▄█▄▄ ▄████ +████ ███▀ ▄▄▀▀██▀ ▄▀▄█▄▄▄ ██▄▄▀▄▀ ███▄ ▄████ +████▄████▄▄▄▀▄ █▄█▄▀▄▄▄▄██▀ ▄▀ ▄ ▄▄▄ █▄▄█████ +████ ▄▄▄▄▄ █▄▄▄ ▄█▀█▀▀▀▀█▀█▀ █▄█ █▄█ ▄█ ████ +████ █ █ █ ██▄▀▀▀▀▄▄▄▀ ▄▄▄ ▀ ▄ ▄ ▄▄████ +████ █▄▄▄█ █ ▀▀█▀ ▄▄█ █▄▄██▀▀█▀ █▄▀▄██▄█ ████ +████▄▄▄▄▄▄▄█▄█▄█▄█▄▄▄▄▄█▄▄▄█▄██████▄██▄▄▄████ +█████████████████████████████████████████████ +█████████████████████████████████████████████ +# To add this OTP key to configuration, run the following commands: +set system login user otptester authentication otp key 'J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY' +set system login user otptester authentication otp rate-limit '2' +set system login user otptester authentication otp rate-time '20' +set system login user otptester authentication otp window-size '5' +``` + +Once a user has 2FA/OTP configured against their account, they must login +using their password with the OTP code appended to it. +For example: If the users password is vyosrocks and the OTP code is 817454 +then they would enter their password as vyosrocks817454 + +## RADIUS + +In large deployments it is not reasonable to configure each user individually +on every system. VyOS supports using `RADIUS (Remote Authentication +Dial-In User Service)` servers as backend for user authentication. + +### Configuration + +<div class="cfgcmd"> + +set system login radius server \<address\> key \<secret\> + +Specify the IP <span class="title-ref">\<address\></span> of the RADIUS server user with the pre-shared-secret +given in <span class="title-ref">\<secret\></span>. + +Multiple servers can be specified. + +</div> + +<div class="cfgcmd"> + +set system login radius server \<address\> port \<port\> + +Configure the discrete port under which the RADIUS server can be reached. + +This defaults to 1812. + +</div> + +<div class="cfgcmd"> + +set system login radius server \<address\> disable + +Temporary disable this RADIUS server. It won't be queried. + +</div> + +<div class="cfgcmd"> + +set system login radius server \<address\> timeout \<timeout\> + +Setup the <span class="title-ref">\<timeout\></span> in seconds when querying the RADIUS server. + +</div> + +<div class="cfgcmd"> + +set system login radius source-address \<address\> + +RADIUS servers could be hardened by only allowing certain IP addresses to +connect. As of this the source address of each RADIUS query can be +configured. + +If unset, incoming connections to the RADIUS server will use the nearest +interface address pointing towards the server - making it error prone on +e.g. OSPF networks when a link fails and a backup route is taken. + +</div> + +<div class="cfgcmd"> + +set system login radius vrf \<name\> + +Source all connections to the RADIUS servers from given VRF <span class="title-ref">\<name\></span>. + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +If you want to have admin users to authenticate via RADIUS it is +essential to sent the `Cisco-AV-Pair shell:priv-lvl=15` attribute. Without +the attribute you will only get regular, non privilegued, system users. + +</div> + +## TACACS+ + +In addition to `RADIUS (Remote Authentication Dial-In User Service)`, +`TACACS (Terminal Access Controller Access Control System)` can also be +found in large deployments. +VyOS only supports <span class="title-ref">Authentication</span> via <span class="title-ref">TACACS+</span> servers but does not support <span class="title-ref">Authorization</span> or <span class="title-ref">Accounting</span> yet + +TACACS is defined in `8907`. + +### Configuration + +<div class="cfgcmd"> + +set system login tacas server \<address\> key \<secret\> + +Specify the IP <span class="title-ref">\<address\></span> of the TACACS server user with the pre-shared-secret +given in <span class="title-ref">\<secret\></span>. + +Multiple servers can be specified. + +</div> + +<div class="cfgcmd"> + +set system login tacas server \<address\> port \<port\> + +Configure the discrete port under which the TACACS server can be reached. + +This defaults to 49. + +</div> + +<div class="cfgcmd"> + +set system login tacas server \<address\> disable + +Temporary disable this TACACS server. It won't be queried. + +</div> + +<div class="cfgcmd"> + +set system login tacas server \<address\> timeout \<timeout\> + +Setup the <span class="title-ref">\<timeout\></span> in seconds when querying the TACACS server. + +</div> + +<div class="cfgcmd"> + +set system login tacas source-address \<address\> + +TACACS servers could be hardened by only allowing certain IP addresses to +connect. As of this the source address of each TACACS query can be +configured. + +If unset, incoming connections to the TACACS server will use the nearest +interface address pointing towards the server - making it error prone on +e.g. OSPF networks when a link fails and a backup route is taken. + +</div> + +<div class="cfgcmd"> + +set system login tacas vrf \<name\> + +Source all connections to the TACACS servers from given VRF <span class="title-ref">\<name\></span>. + +</div> + +## Login Banner + +You are able to set post-login or pre-login banner messages to display certain +information for this system. + +<div class="cfgcmd"> + +set system login banner pre-login \<message\> + +Configure <span class="title-ref">\<message\></span> which is shown during SSH connect and before a user is +logged in. + +</div> + +<div class="cfgcmd"> + +set system login banner post-login \<message\> + +Configure <span class="title-ref">\<message\></span> which is shown after user has logged in to the system. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +To create a new line in your login message you need to escape the new +line character by using `\\n`. + +</div> + +## Limits + +Login limits + +<div class="cfgcmd"> + +set system login max-login-session \<number\> + +Set a limit on the maximum number of concurrent logged-in users on +the system. + +This option must be used with `timeout` option. + +</div> + +<div class="cfgcmd"> + +set system login timeout \<timeout\> + +Configure session timeout after which the user will be logged out. + +</div> + +## Example + +In the following example, both <span class="title-ref">User1</span> and <span class="title-ref">User2</span> will be able to SSH into +VyOS as user `vyos` using their very own keys. <span class="title-ref">User1</span> is restricted to only +be able to connect from a single IP address. In addition if password base login +is wanted for the `vyos` user a 2FA/MFA keycode is required in addition to +the password. + +``` none +set system login user vyos authentication public-keys 'User1' key "AAAAB3Nz...KwEW" +set system login user vyos authentication public-keys 'User1' type ssh-rsa +set system login user vyos authentication public-keys 'User1' options "from="192.168.0.100"" + +set system login user vyos authentication public-keys 'User2' key "AAAAQ39x...fbV3" +set system login user vyos authentication public-keys 'User2' type ssh-rsa + +set system login user vyos authentication otp key OHZ3OJ7U2N25BK4G7SOFFJTZDTCFUUE2 +set system login user vyos authentication plaintext-password vyos +``` + +### TACACS Example + +We use a vontainer providing the TACACS serve rin this example. + +Load the container image in op-mode. + +``` none +add container image lfkeitel/tacacs_plus:latest +``` + +``` none +set container network tac-test prefix '100.64.0.0/24' + +set container name tacacs1 image 'lfkeitel/tacacs_plus:latest' +set container name tacacs1 network tac-test address '100.64.0.11' + +set container name tacacs2 image 'lfkeitel/tacacs_plus:latest' +set container name tacacs2 network tac-test address '100.64.0.12' + +set system login tacacs server 100.64.0.11 key 'tac_plus_key' +set system login tacacs server 100.64.0.12 key 'tac_plus_key' + +commit +``` + +You can now SSH into your system using admin/admin as a default user supplied +from the `lfkeitel/tacacs_plus:latest` container. diff --git a/docs/configuration/system/md-name-server.md b/docs/configuration/system/md-name-server.md new file mode 100644 index 00000000..ea544b16 --- /dev/null +++ b/docs/configuration/system/md-name-server.md @@ -0,0 +1,81 @@ +# System DNS + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +If you are configuring a VRF for management purposes, there is +currently no way to force system DNS traffic via a specific VRF. + +</div> + +This section describes configuring DNS on the system, namely: + +> - DNS name servers +> - Domain search order + +## DNS name servers + +<div class="cfgcmd"> + +set system name-server \<address\> + +Use this command to specify a DNS server for the system to be used +for DNS lookups. More than one DNS server can be added, configuring +one at a time. Both IPv4 and IPv6 addresses are supported. + +</div> + +### Example + +In this example, some *OpenNIC* servers are used, two IPv4 addresses +and two IPv6 addresses: + +``` none +set system name-server 176.9.37.132 +set system name-server 195.10.195.195 +set system name-server 2a01:4f8:161:3441::1 +set system name-server 2a00:f826:8:2::195 +``` + +## Domain search order + +In order for the system to use and complete unqualified host names, a +list can be defined which will be used for domain searches. + +<div class="cfgcmd"> + +set system domain-search \<domain\> + +Use this command to define domains, one at a time, so that the system +uses them to complete unqualified host names. Maximum: 6 entries. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Domain names can include letters, numbers, hyphens and periods +with a maximum length of 253 characters. + +</div> + +### Example + +The system is configured to attempt domain completion in the following +order: vyos.io (first), vyos.net (second) and vyos.network (last): + +``` none +set system domain-search vyos.io +set system domain-search vyos.net +set system domain-search vyos.network +``` diff --git a/docs/configuration/system/md-option.md b/docs/configuration/system/md-option.md new file mode 100644 index 00000000..8ad69d76 --- /dev/null +++ b/docs/configuration/system/md-option.md @@ -0,0 +1,262 @@ +# Option + +This chapter describe the possibilities of advanced system behavior. + +## General + +<div class="cfgcmd"> + +set system option ctrl-alt-delete \<ignore | reboot | poweroff\> + +Action which will be run once the ctrl-alt-del keystroke is received. + +</div> + +<div class="cfgcmd"> + +set system option reboot-on-panic + +Automatically reboot system on kernel panic after 60 seconds. + +</div> + +<div class="cfgcmd"> + +set system option startup-beep + +Play an audible beep to the system speaker when system is ready. + +</div> + +<div class="cfgcmd"> + +set system option root-partition-auto-resize + +Enables the root partition auto-extension and resizes to the maximum +available space on system boot. + +</div> + +### Kernel + +<div class="cfgcmd"> + +set system option kernel disable-mitigations + +Disable all optional CPU mitigations. This improves system performance, +but it may also expose users to several CPU vulnerabilities. + +This will add the following option to the Kernel commandline: + +- `mitigations=off` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Setting will only become active with the next reboot! + +</div> + +</div> + +<div class="cfgcmd"> + +set system option kernel disable-power-saving + +This will add the following two options to the Kernel commandline: + +- `intel_idle.max_cstate=0` Disable intel_idle and fall back on acpi_idle +- `processor.max_cstate=1` Limit processor to maximum C-state 1 + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Setting will only become active with the next reboot! + +</div> + +</div> + +<div class="cfgcmd"> + +set system option kernel amd-pstate-driver \<mode\> + +Enables and configures p-state driver for modern AMD Ryzen and Epyc CPUs. + +The available modes are: + +- `active` This is the low-level firmware control mode based on the profile + set and the system governor has no effect. +- `passive` The driver allows the system governor to manage CPU frequency + while providing available performance states. +- `guided` The driver allows to set desired performance levels and the firmware + selects a performance level in this range and fitting to the current workload. + +This will add the following two options to the Kernel commandline: + +- `initcall_blacklist=acpi_cpufreq_init` Disable default ACPI CPU frequency scale +- `amd_pstate={mode}` Sets the p-state mode + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Setting will only become active with the next reboot! + +</div> + +<div class="seealso"> + +<https://docs.kernel.org/admin-guide/pm/amd-pstate.html> + +</div> + +</div> + +<div class="cfgcmd"> + +set system option kernel quiet + +Suppress most kernel messages during boot. This is useful for systems with +embedded serial console interfaces to speed up the boot process. + +</div> + +## HTTP client + +<div class="cfgcmd"> + +set system option http-client source-address \<address\> + +Several commands utilize cURL to initiate transfers. Configure the local +source IPv4/IPv6 address used for all cURL operations. + +</div> + +<div class="cfgcmd"> + +set system option http-client source-interface \<interface\> + +Several commands utilize curl to initiate transfers. Configure the local +source interface used for all CURL operations. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +<span class="title-ref">source-address</span> and <span class="title-ref">source-interface</span> can not be used at the same +time. + +</div> + +## SSH client + +<div class="cfgcmd"> + +set system option ssh-client source-address \<address\> + +Use the specified address on the local machine as the source address of the +connection. Only useful on systems with more than one address. + +</div> + +<div class="cfgcmd"> + +set system option ssh-client source-interface \<interface\> + +Use the address of the specified interface on the local machine as the +source address of the connection. + +</div> + +## Keyboard Layout + +When starting a VyOS live system (the installation CD) the configured keyboard +layout defaults to US. As this might not suite everyones use case you can adjust +the used keyboard layout on the system console. + +<div class="cfgcmd"> + +set system option keyboard-layout \<us | fr | de | fi | no | dk\> + +Change system keyboard layout to given language. + +Defaults to `us`. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Changing the keymap only has an effect on the system console, using +SSH or Serial remote access to the device is not affected as the keyboard +layout here corresponds to your access system. + +</div> + +</div> + +## Performance + +As more and more routers run on Hypervisors, expecially with a `NOS +(Network Operating System)` as VyOS, it makes fewer and fewer sense to use +static resource bindings like `smp-affinity` as present in VyOS 1.2 and +earlier to pin certain interrupt handlers to specific CPUs. + +We now utilize <span class="title-ref">tuned</span> for dynamic resource balancing based on profiles. + +<div class="seealso"> + +<https://access.redhat.com/sites/default/files/attachments/201501-perf-brief-low-latency-tuning-rhel7-v2.1.pdf> + +</div> + +<div class="cfgcmd"> + +set system option performance \< throughput | latency \> + +Configure one of the predefined system performance profiles. + +- `throughput`: A server profile focused on improving network throughput. + This profile favors performance over power savings by setting + `intel_pstate` and `max_perf_pct=100` and increasing kernel network + buffer sizes. + + It enables transparent huge pages, and uses cpupower to set the performance + cpufreq governor. It also sets `kernel.sched_min_granularity_ns` to 10 us, + `kernel.sched_wakeup_granularity_ns` to 15 uss, and `vm.dirty_ratio` to + 40%. + +- `latency`: A server profile focused on lowering network latency. + This profile favors performance over power savings by setting + `intel_pstate` and `min_perf_pct=100`. + + It disables transparent huge pages, and automatic NUMA balancing. It also + uses cpupower to set the performance cpufreq governor, and requests a + cpu_dma_latency value of 1. It also sets busy_read and busy_poll times to + 50 us, and tcp_fastopen to 3. + +</div> diff --git a/docs/configuration/system/md-proxy.md b/docs/configuration/system/md-proxy.md new file mode 100644 index 00000000..911392ad --- /dev/null +++ b/docs/configuration/system/md-proxy.md @@ -0,0 +1,40 @@ +# System Proxy + +Some IT environments require the use of a proxy to connect to the Internet. +Without this configuration VyOS updates could not be installed directly by +using the `add system image` command (`update_vyos`). + +<div class="cfgcmd"> + +set system proxy url \<url\> + +Set proxy for all connections initiated by VyOS, including HTTP, HTTPS, and +FTP (anonymous ftp). + +</div> + +<div class="cfgcmd"> + +set system proxy port \<port\> + +Configure proxy port if it does not listen to the default port 80. + +</div> + +<div class="cfgcmd"> + +set system proxy username \<username\> + +Some proxys require/support the "basic" HTTP authentication scheme as per +`7617`, thus a username can be configured. + +</div> + +<div class="cfgcmd"> + +set system proxy password \<password\> + +Some proxys require/support the "basic" HTTP authentication scheme as per +`7617`, thus a password can be configured. + +</div> diff --git a/docs/configuration/system/md-sflow.md b/docs/configuration/system/md-sflow.md new file mode 100644 index 00000000..b64de63f --- /dev/null +++ b/docs/configuration/system/md-sflow.md @@ -0,0 +1,81 @@ +# sFlow + +VyOS supports sFlow accounting for both IPv4 and IPv6 traffic. The system acts as a flow exporter, and you are free to use it with any compatible collector. + +sFlow is a technology that enables monitoring of network traffic by sending sampled packets to a collector device. + +The sFlow accounting based on hsflowd <https://sflow.net/> + +## Configuration + +<div class="cfgcmd"> + +set system sflow agent-address \<address\> + +Configure sFlow agent IPv4 or IPv6 address + +</div> + +<div class="cfgcmd"> + +set system sflow agent-interface \<interface\> + +Configure agent IP address associated with this interface. + +</div> + +<div class="cfgcmd"> + +set system sflow drop-monitor-limit \<limit\> + +Dropped packets reported on DROPMON Netlink channel by Linux kernel are exported via the standard sFlow v5 extension for reporting dropped packets + +</div> + +<div class="cfgcmd"> + +set system sflow interface \<interface\> + +Configure and enable collection of flow information for the interface identified by \<interface\>. + +You can configure multiple interfaces which whould participate in sflow accounting. + +</div> + +<div class="cfgcmd"> + +set system sflow polling \<sec\> + +Configure schedule counter-polling in seconds (default: 30) + +</div> + +<div class="cfgcmd"> + +set system sflow sampling-rate \<rate\> + +Use this command to configure the sampling rate for sFlow accounting (default: 1000) + +</div> + +<div class="cfgcmd"> + +set system sflow server \<address\> port \<port\> + +Configure address of sFlow collector. sFlow server at \<address\> can be both listening on an IPv4 or IPv6 address. + +</div> + +## Example + +``` none +set system sflow agent-address '192.0.2.14' +set system sflow agent-interface 'eth0' +set system sflow drop-monitor-limit '50' +set system sflow interface 'eth0' +set system sflow interface 'eth1' +set system sflow polling '30' +set system sflow sampling-rate '1000' +set system sflow server 192.0.2.1 port '6343' +set system sflow server 203.0.113.23 port '6343' +``` diff --git a/docs/configuration/system/md-sysctl.md b/docs/configuration/system/md-sysctl.md new file mode 100644 index 00000000..2786ceea --- /dev/null +++ b/docs/configuration/system/md-sysctl.md @@ -0,0 +1,12 @@ +# Sysctl + +This chapeter describes how to configure kernel parameters at runtime. + +`sysctl` is used to modify kernel parameters at runtime. The parameters +available are those listed under /proc/sys/. + +<div class="cfgcmd"> + +set system sysctl parameter \<parameter\> value \<value\> + +</div> diff --git a/docs/configuration/system/md-syslog.md b/docs/configuration/system/md-syslog.md new file mode 100644 index 00000000..fc4d5eef --- /dev/null +++ b/docs/configuration/system/md-syslog.md @@ -0,0 +1,606 @@ +# Syslog + +Per default VyOSs has minimal syslog logging enabled which is stored and +rotated locally. Errors will be always logged to a local file, which includes +<span class="title-ref">local7</span> error messages, emergency messages will be sent to the console, too. + +To configure syslog, you need to switch into configuration mode. + +## Logging + +Syslog supports logging to multiple targets, those targets could be a plain +file on your VyOS installation itself, a serial console or a remote syslog +server which is reached via `IP (Internet Protocol)` UDP/TCP. + +### Console + +<div class="cfgcmd"> + +set system syslog console facility \<keyword\> level \<keyword\> + +Log syslog messages to `/dev/console`, for an explanation on +`syslog_facilities` keywords and `syslog_severity_level` keywords +see tables below. + +</div> + +### Custom File + +<div class="cfgcmd"> + +set system syslog file \<filename\> facility \<keyword\> level \<keyword\> + +Log syslog messages to file specified via <span class="title-ref">\<filename\></span>, for an explanation on +`syslog_facilities` keywords and `syslog_severity_level` keywords +see tables below. + +</div> + +<div class="cfgcmd"> + +set system syslog file \<filename\> archive size \<size\> + +Syslog will write <span class="title-ref">\<size\></span> kilobytes into the file specified by <span class="title-ref">\<filename\></span>. +After this limit has been reached, the custom file is "rotated" by logrotate +and a new custom file is created. + +</div> + +<div class="cfgcmd"> + +set system syslog file \<filename\> archive file \<number\> + +Syslog uses logrotate to rotate logiles after a number of gives bytes. +We keep as many as <span class="title-ref">\<number\></span> rotated file before they are deleted on the +system. + +</div> + +### Remote Host + +Logging to a remote host leaves the local logging configuration intact, it +can be configured in parallel to a custom file or console logging. You can log +to multiple hosts at the same time, using either TCP or UDP. The default is +sending the messages via port 514/UDP. + +<div class="cfgcmd"> + +set system syslog host \<address\> facility \<keyword\> level \<keyword\> + +Log syslog messages to remote host specified by <span class="title-ref">\<address\></span>. The address +can be specified by either FQDN or IP address. For an explanation on +`syslog_facilities` keywords and `syslog_severity_level` +keywords see tables below. + +</div> + +<div class="cfgcmd"> + +set system syslog host \<address\> facility \<keyword\> protocol +\<udp|tcp\> + +Configure protocol used for communication to remote syslog host. This can be +either UDP or TCP. + +</div> + +<div class="cfgcmd"> + +set system syslog vrf \<name\> + +Specify name of the `VRF (Virtual Routing and Forwarding)` instance. + +</div> + +#### `TLS (Transport Layer Security)`-encrypted remote logging + +VyOS supports `TLS (Transport Layer Security)`-encrypted remote logging +over TCP to ensure secure transmission of syslog data to remote syslog servers. + +**Prerequisites**: Before configuring `TLS (Transport Layer +Security)`-encrypted remote logging, ensure you have: + +- A valid remote syslog server address. + +- Valid `CA (Certificate Authority)` and client certificates uploaded + to the local `PKI (Public Key Infrastructure)` storage. + +- The **remote syslog transport protocol** is set to **TCP**: + + ``` none + set system syslog remote <address> protocol tcp + ``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +`TLS (Transport Layer Security)`-encrypted remote logging is +**not supported** over **UDP**. + +</div> + +<div class="cfgcmd"> + +set system syslog remote \<address\> tls + +Enable TLS-encrypted remote logging. + +</div> + +<div class="cfgcmd"> + +set system syslog remote \<address\> tls ca-certificate \<ca_name\> + +**Configure the** `CA (Certificate Authority)` **certificate.** + +The syslog client uses the `CA (Certificate Authority)` certificate to +verify the identity of the remote syslog server. + +The `CA (Certificate Authority)` certificate is required for **all** +authentication modes except `anon`. + +</div> + +<div class="cfgcmd"> + +set system syslog remote \<address\> tls certificate \<cert_name\> + +**Configure the client certificate.** + +The remote syslog server uses the client certificate to verify the identity +of the syslog client. + +The client certificate is required if the remote syslog server enforces +client certificate verification. + +</div> + +<div class="cfgcmd"> + +set system syslog remote \<address\> tls auth-mode \<anon | fingerprint +| certvalid | name\> + +**Configure the authentication mode.** + +The authentication mode defines how the syslog client verifies the syslog +server's identity. + +The following authentication modes are available: + +- `anon` **(default)**: Allows encrypted connections without verifying the syslog + server's identity. This mode is **not recommended**, as it is vulnerable to + `MITM (Man-in-the-Middle)` attacks. + +- `fingerprint`: Verifies the server’s certificate fingerprint against the + value preconfigured with: + + ``` none + set system syslog remote <address> tls permitted-peer <peer> + ``` + +- `certvalid`: Verifies the server certificate is signed by a trusted + `CA (Certificate Authority)`, skipping `CN (Common Name)` check. + +- `name`: Verifies that: + + - The server’s certificate is signed by a trusted `CA (Certificate + Authority)`. + - The `CN (Common Name)` in the certificate matches the value + preconfigured with: + + ``` none + set system syslog remote <address> tls permitted-peer <peer> + ``` + + This is a **recommended** secure mode for production environments. + +</div> + +<div class="cfgcmd"> + +set system syslog remote \<address\> tls permitted-peer \<peer\> + +**Configure the peer certificate identifiers.** + +The certificate identifier format depends on the authentication mode: + +- `fingerprint`: Enter the expected certificate fingerprints (SHA-1 or + SHA-256). +- `name`: Enter the expected certificate `CNs (Common Names)`. + +For `anon` and `certvalid` authentication modes, certificate identifiers +are not required. + +</div> + +#### Examples: + +``` none +# Example of 'anon' authentication mode +set system syslog host 10.10.2.3 facility all level debug +set system syslog host 10.10.2.3 port 6514 +set system syslog host 10.10.2.3 protocol tcp +set system syslog host 10.10.2.3 tls auth-mode anon +# or just use 'set system syslog host 10.10.2.3 tls' + +# Example of 'certvalid' authentication mode +set system syslog host elk.example.com facility all level debug +set system syslog host elk.example.com port 6514 +set system syslog host elk.example.com protocol tcp +set system syslog host elk.example.com tls ca-certificate my-ca +set system syslog host elk.example.com tls auth-mode certvalid + +# Example of 'fingerprint' authentication mode +set system syslog host syslog.example.com facility all level debug +set system syslog host syslog.example.com port 6514 +set system syslog host syslog.example.com protocol tcp +set system syslog host syslog.example.com tls ca-certificate my-ca +set system syslog host syslog.example.com tls auth-mode fingerprint +set system syslog host syslog.example.com tls permitted-peer 'SHA1:10:C4:26:...' + +# Example of 'name' authentication mode +set system syslog host graylog.example.com facility all level debug +set system syslog host graylog.example.com port 6514 +set system syslog host graylog.example.com protocol tcp +set system syslog host graylog.example.com tls ca-certificate my-ca +set system syslog host graylog.example.com tls certificate syslog-client +set system syslog host graylog.example.com tls auth-mode name +set system syslog host graylog.example.com tls permitted-peer 'graylog.example.com' +``` + +#### Security Notes + +- Always prefer `auth-mode name` for secure deployments, as it ensures + both CA trust and server hostname validation. +- `anon` mode should only be used for testing, because it does not + authenticate the server. +- Ensure private keys are stored and managed exclusively in the + `PKI system </configuration/pki/index>`. + +### Local User Account + +<div class="cfgcmd"> + +set system syslog user \<username\> facility \<keyword\> level \<keyword\> + +If logging to a local user account is configured, all defined log messages +are display on the console if the local user is logged in, if the user is not +logged in, no messages are being displayed. For an explanation on +`syslog_facilities` keywords and `syslog_severity_level` keywords +see tables below. + +</div> + +## Facilities + +List of facilities used by syslog. Most facilities names are self explanatory. +Facilities local0 - local7 common usage is f.e. as network logs facilities for +nodes and network equipment. Generally it depends on the situation how to +classify logs and put them to facilities. See facilities more as a tool rather +than a directive to follow. + +Facilities can be adjusted to meet the needs of the user: + +<table style="width:99%;"> +<colgroup> +<col style="width: 14%" /> +<col style="width: 14%" /> +<col style="width: 69%" /> +</colgroup> +<thead> +<tr> +<th>Facility +Code</th> +<th>Keyword</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td></td> +<td>all</td> +<td>All facilities</td> +</tr> +<tr> +<td>0</td> +<td>kern</td> +<td>Kernel messages</td> +</tr> +<tr> +<td>1</td> +<td>user</td> +<td>User-level messages</td> +</tr> +<tr> +<td>2</td> +<td>mail</td> +<td>Mail system</td> +</tr> +<tr> +<td>3</td> +<td>daemon</td> +<td>System daemons</td> +</tr> +<tr> +<td>4</td> +<td>auth</td> +<td>Security/authentication messages</td> +</tr> +<tr> +<td>5</td> +<td>syslog</td> +<td>Messages generated internally by syslogd</td> +</tr> +<tr> +<td>6</td> +<td>lpr</td> +<td>Line printer subsystem</td> +</tr> +<tr> +<td>7</td> +<td>news</td> +<td>Network news subsystem</td> +</tr> +<tr> +<td>8</td> +<td>uucp</td> +<td>UUCP subsystem</td> +</tr> +<tr> +<td>9</td> +<td>cron</td> +<td>Clock daemon</td> +</tr> +<tr> +<td>10</td> +<td>security</td> +<td>Security/authentication messages</td> +</tr> +<tr> +<td>11</td> +<td>ftp</td> +<td>FTP daemon</td> +</tr> +<tr> +<td>12</td> +<td>ntp</td> +<td>NTP subsystem</td> +</tr> +<tr> +<td>13</td> +<td>logaudit</td> +<td>Log audit</td> +</tr> +<tr> +<td>14</td> +<td>logalert</td> +<td>Log alert</td> +</tr> +<tr> +<td>15</td> +<td>clock</td> +<td>clock daemon (note 2)</td> +</tr> +<tr> +<td>16</td> +<td>local0</td> +<td>local use 0 (local0)</td> +</tr> +<tr> +<td>17</td> +<td>local1</td> +<td>local use 1 (local1)</td> +</tr> +<tr> +<td>18</td> +<td>local2</td> +<td>local use 2 (local2)</td> +</tr> +<tr> +<td>19</td> +<td>local3</td> +<td>local use 3 (local3)</td> +</tr> +<tr> +<td>20</td> +<td>local4</td> +<td>local use 4 (local4)</td> +</tr> +<tr> +<td>21</td> +<td>local5</td> +<td>local use 5 (local5)</td> +</tr> +<tr> +<td>22</td> +<td>local6</td> +<td><blockquote> +<p>use 6 (local6)</p> +</blockquote></td> +</tr> +<tr> +<td>23</td> +<td>local7</td> +<td>local use 7 (local7)</td> +</tr> +</tbody> +</table> + +## Severity Level + +<table style="width:98%;"> +<colgroup> +<col style="width: 10%" /> +<col style="width: 20%" /> +<col style="width: 12%" /> +<col style="width: 55%" /> +</colgroup> +<thead> +<tr> +<th>Value</th> +<th>Severity</th> +<th>Keyword</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td></td> +<td></td> +<td>all</td> +<td>Log everything</td> +</tr> +<tr> +<td>0</td> +<td>Emergency</td> +<td>emerg</td> +<td>System is unusable - a panic condition</td> +</tr> +<tr> +<td>1</td> +<td>Alert</td> +<td>alert</td> +<td>Action must be taken immediately - A +condition that should be corrected +immediately, such as a corrupted system +database.</td> +</tr> +<tr> +<td>2</td> +<td>Critical</td> +<td>crit</td> +<td>Critical conditions - e.g. hard drive +errors.</td> +</tr> +<tr> +<td>3</td> +<td>Error</td> +<td>err</td> +<td>Error conditions</td> +</tr> +<tr> +<td>4</td> +<td>Warning</td> +<td>warning</td> +<td>Warning conditions</td> +</tr> +<tr> +<td>5</td> +<td>Notice</td> +<td>notice</td> +<td>Normal but significant conditions - +conditions that are not error conditions, +but that may require special handling.</td> +</tr> +<tr> +<td>6</td> +<td>Informational</td> +<td>info</td> +<td>Informational messages</td> +</tr> +<tr> +<td>7</td> +<td>Debug</td> +<td>debug</td> +<td>Debug-level messages - Messages that +contain information normally of use only +when debugging a program.</td> +</tr> +</tbody> +</table> + +## Display Logs + +<div class="opcmd"> + +show log \[all | authorization | cluster | conntrack-sync | ...\] + +Display log files of given category on the console. Use tab completion to get +a list of available categories. Thos categories could be: all, authorization, +cluster, conntrack-sync, dhcp, directory, dns, file, firewall, https, image +lldp, nat, openvpn, snmp, tail, vpn, vrrp + +</div> + +If no option is specified, this defaults to <span class="title-ref">all</span>. + +<div class="opcmd"> + +show log image \<name\> +\[all | authorization | directory | file \<file name\> | tail \<lines\>\] + +Log messages from a specified image can be displayed on the console. Details +of allowed parameters: + +<table> +<colgroup> +<col style="width: 25%" /> +<col style="width: 75%" /> +</colgroup> +<tbody> +<tr> +<td>all</td> +<td>Display contents of all master log files of the specified image</td> +</tr> +<tr> +<td>authorization</td> +<td>Display all authorization attempts of the specified image</td> +</tr> +<tr> +<td>directory</td> +<td>Display list of all user-defined log files of the specified image</td> +</tr> +<tr> +<td>file <file name></td> +<td>Display contents of a specified user-defined log file of the specified +image</td> +</tr> +<tr> +<td>tail</td> +<td>Display last lines of the system log of the specified image</td> +</tr> +<tr> +<td><lines></td> +<td>Number of lines to be displayed, default 10</td> +</tr> +</tbody> +</table> + +</div> + +When no options/parameters are used, the contents of the main syslog file are +displayed. + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +Use `show log | strip-private` if you want to hide private data +when sharing your logs. + +</div> + +## Delete Logs + +<div class="opcmd"> + +delete log file \<text\> + +</div> + +Deletes the specified user-defined file \<text\> in the /var/log/user directory + +Note that deleting the log file does not stop the system from logging events. +If you use this command while the system is logging events, old log events +will be deleted, but events after the delete operation will be recorded in +the new file. To delete the file altogether, first delete logging to the +file using system syslog `custom-file` command, and then delete the file. diff --git a/docs/configuration/system/md-task-scheduler.md b/docs/configuration/system/md-task-scheduler.md new file mode 100644 index 00000000..9a43b430 --- /dev/null +++ b/docs/configuration/system/md-task-scheduler.md @@ -0,0 +1,70 @@ +# Task Scheduler + +The task scheduler allows you to execute tasks on a given schedule. It makes +use of UNIX [cron](https://en.wikipedia.org/wiki/Cron). + +<div class="note"> + +<div class="title"> + +Note + +</div> + +All scripts excecuted this way are executed as root user - this may +be dangerous. Together with `command-scripting` this can be used for +automating (re-)configuration. + +</div> + +<div class="cfgcmd"> + +set system task-scheduler task \<task\> interval \<interval\> + +Specify the time interval when <span class="title-ref">\<task\></span> should be executed. The interval +is specified as number with one of the following suffixes: + +- `none` - Execution interval in minutes +- `m` - Execution interval in minutes +- `h` - Execution interval in hours +- `d` - Execution interval in days + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If suffix is omitted, minutes are implied. + +</div> + +</div> + +<div class="cfgcmd"> + +set system task-scheduler task \<task\> crontab-spec \<spec\> + +Set execution time in common [cron](https://en.wikipedia.org/wiki/Cron) time format. A cron <span class="title-ref">\<spec\></span> of +`30 */6 * * *` would execute the <span class="title-ref">\<task\></span> at minute 30 past every 6th hour. + +</div> + +<div class="cfgcmd"> + +set system task-scheduler task \<task\> executable path \<path\> + +Specify absolute <span class="title-ref">\<path\></span> to script which will be run when <span class="title-ref">\<task\></span> is +executed. + +</div> + +<div class="cfgcmd"> + +set system task-scheduler task \<task\> executable arguments \<args\> + +Arguments which will be passed to the executable. + +</div> diff --git a/docs/configuration/system/md-time-zone.md b/docs/configuration/system/md-time-zone.md new file mode 100644 index 00000000..20f24b41 --- /dev/null +++ b/docs/configuration/system/md-time-zone.md @@ -0,0 +1,18 @@ +# Time Zone + +Time Zone setting is very important as e.g all your logfile entries will be +based on the configured zone. Without proper time zone configuration it will +be very difficult to compare logfiles from different systems. + +<div class="cfgcmd"> + +set system time-zone \<timezone\> + +Specify the systems <span class="title-ref">\<timezone\></span> as the Region/Location that best defines +your location. For example, specifying US/Pacific sets the time zone to US +Pacific time. + +Command completion can be used to list available time zones. The adjustment +for daylight time will take place automatically based on the time of year. + +</div> diff --git a/docs/configuration/system/md-updates.md b/docs/configuration/system/md-updates.md new file mode 100644 index 00000000..4e0460ac --- /dev/null +++ b/docs/configuration/system/md-updates.md @@ -0,0 +1,39 @@ +# Updates + +VyOS supports online checking for updates + +## Configuration + +<div class="cfgcmd"> + +set system update-check auto-check + +Configure auto-checking for new images + +</div> + +<div class="cfgcmd"> + +set system update-check url \<url\> + +Configure a URL that contains information about images. + +</div> + +## Example + +``` none +set system update-check auto-check +set system update-check url 'https://raw.githubusercontent.com/vyos/vyos-rolling-nightly-builds/main/version.json' +``` + +Check: + +``` none +vyos@r4:~$ show system updates +Current version: 1.5-rolling-202312220023 + +Update available: 1.5-rolling-202312250024 +Update URL: https://github.com/vyos/vyos-rolling-nightly-builds/releases/download/1.5-rolling-202312250024/1.5-rolling-202312250024-amd64.iso +vyos@r4:~$ +``` diff --git a/docs/configuration/trafficpolicy/md-index.md b/docs/configuration/trafficpolicy/md-index.md new file mode 100644 index 00000000..de67ee11 --- /dev/null +++ b/docs/configuration/trafficpolicy/md-index.md @@ -0,0 +1,1738 @@ +# Traffic Policy + +## QoS + +The generic name of Quality of Service or Traffic Control involves +things like shaping traffic, scheduling or dropping packets, which +are the kind of things you may want to play with when you have, for +instance, a bandwidth bottleneck in a link and you want to somehow +prioritize some type of traffic over another. + +[tc](https://en.wikipedia.org/wiki/Tc_(Linux)) is a powerful tool for Traffic Control found at the Linux kernel. +However, its configuration is often considered a cumbersome task. +Fortunately, VyOS eases the job through its CLI, while using `tc` as +backend. + +### How to make it work + +In order to have VyOS Traffic Control working you need to follow 2 +steps: + +> 1. **Create a traffic policy**. +> 2. **Apply the traffic policy to an interface ingress or egress**. + +But before learning to configure your policy, we will warn you +about the different units you can use and also show you what *classes* +are and how they work, as some policies may require you to configure +them. + +### Units + +When configuring your traffic policy, you will have to set data rate +values, watch out the units you are managing, it is easy to get confused +with the different prefixes and suffixes you can use. VyOS will always +show you the different units you can use. + +#### Prefixes + +They can be **decimal** prefixes. + +> ``` none +> kbit (10^3) kilobit per second +> mbit (10^6) megabit per second +> gbit (10^9) gigabit per second +> tbit (10^12) terabit per second +> +> kbps (8*10^3) kilobyte per second +> mbps (8*10^6) megabyte per second +> gbps (8*10^9) gigabyte per second +> tbps (8*10^12) terabyte per second +> ``` + +Or **binary** prefixes. + +> ``` none +> kibit (2^10 = 1024) kibibit per second +> mibit (2^20 = 1024^2) mebibit per second +> gibit (2^30 = 1024^3) gibibit per second +> tbit (2^40 = 1024^4) tebibit per second +> +> kibps (1024*8) kibibyte (KiB) per second +> mibps (1024^2*8) mebibyte (MiB) per second +> gibps (1024^3*8) gibibyte (GiB) per second +> tibps (1024^4*8) tebibyte (TiB) per second +> ``` + +#### Suffixes + +A *bit* is written as **bit**, + +> ``` none +> kbit (kilobits per second) +> mbit (megabits per second) +> gbit (gigabits per second) +> tbit (terabits per second) +> ``` + +while a *byte* is written as a single **b**. + +> ``` none +> kbps (kilobytes per second) +> mbps (megabytes per second) +> gbps (gigabytes per second) +> ``` + +### Classes + +In the `creating_a_traffic_policy` section you will see that +some of the policies use *classes*. Those policies let you distribute +traffic into different classes according to different parameters you can +choose. So, a class is just a specific type of traffic you select. + +The ultimate goal of classifying traffic is to give each class a +different treatment. + +#### Matching traffic + +In order to define which traffic goes into which class, you define +filters (that is, the matching criteria). Packets go through these matching +rules (as in the rules of a firewall) and, if a packet matches the filter, it +is assigned to that class. + +In VyOS, a class is identified by a number you can choose when +configuring it. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The meaning of the Class ID is not the same for every type of +policy. Normally policies just need a meaningless number to identify +a class (Class ID), but that does not apply to every policy. +The number of a class in a Priority Queue it does not only +identify it, it also defines its priority. + +</div> + +``` none +set qos policy <policy> <policy-name> class <class-ID> match <class-matching-rule-name> +``` + +In the command above, we set the type of policy we are going to +work with and the name we choose for it; a class (so that we can +differentiate some traffic) and an identifiable number for that class; +then we configure a matching rule (or filter) and a name for it. + +A class can have multiple match filters: + +``` none +set qos policy shaper MY-SHAPER class 30 match HTTP +set qos policy shaper MY-SHAPER class 30 match HTTPs +``` + +A match filter can contain multiple criteria and will match traffic if +all those criteria are true. + +For example: + +``` none +set qos policy shaper MY-SHAPER class 30 match HTTP ip protocol tcp +set qos policy shaper MY-SHAPER class 30 match HTTP ip source port 80 +``` + +This will match TCP traffic with source port 80. + +There are many parameters you will be able to use in order to match the +traffic you want for a class: + +> - **Ethernet (protocol, destination address or source address)** +> - **Interface name** +> - **IPv4 (DSCP value, maximum packet length, protocol, source address,** +> **destination address, source port, destination port or TCP flags)** +> - **IPv6 (DSCP value, maximum payload length, protocol, source address,** +> **destination address, source port, destination port or TCP flags)** +> - **Firewall mark** +> - **VLAN ID** + +When configuring your filter, you can use the `Tab` key to see the many +different parameters you can configure. + +``` none +vyos@vyos# set qos policy shaper MY-SHAPER class 30 match MY-FIRST-FILTER +Possible completions: + description Description + > ether Ethernet header match + interface Interface to use + > ip Match IP protocol header + > ipv6 Match IPV6 protocol header + mark Match on mark applied by firewall + vif Virtual Local Area Network (VLAN) ID for this match +``` + +As shown in the example above, one of the possibilities to match packets +is based on marks done by the firewall, +[that can give you a great deal of flexibility](https://blog.vyos.io/using-the-policy-route-and-packet-marking-for-custom-qos-matches). + +You can also write a description for a filter: + +``` none +set qos policy shaper MY-SHAPER class 30 match MY-FIRST-FILTER description "My filter description" +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +An IPv4 TCP filter will only match packets with an IPv4 header +length of 20 bytes (which is the majority of IPv4 packets anyway). + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +IPv6 TCP filters will only match IPv6 packets with no header +extension, see <https://en.wikipedia.org/wiki/IPv6_packet#Extension_headers> + +</div> + +#### Traffic Match Group + +In some case where we need to have an organization of our matching selection, +in order to be more flexible and organize with our filter definition. We can +apply traffic match groups, allowing us to create distinct filter groups within +our policy and define various parameters for each group: + +``` none +set qos traffic-match-group <group_name> match <match_name> +Possible completions: + description Description + > ip Match IP protocol header + > ipv6 Match IPv6 protocol header + mark Match on mark applied by firewall + vif Virtual Local Area Network (VLAN) ID for this match +``` + +inherit matches from another group + +``` none +set qos traffic-match-group <group_name> match-group <match_group_name> +``` + +A match group can contain multiple criteria and inherit them in the same policy. + +For example: + +``` none +set qos traffic-match-group Mission-Critical match AF31 ip dscp 'AF31' +set qos traffic-match-group Mission-Critical match AF32 ip dscp 'AF42' +set qos traffic-match-group Mission-Critical match CS3 ip dscp 'CS3' +set qos traffic-match-group Streaming-Video match AF11 ip dscp 'AF11' +set qos traffic-match-group Streaming-Video match AF41 ip dscp 'AF41' +set qos traffic-match-group Streaming-Video match AF43 ip dscp 'AF43' +set qos policy shaper VyOS-HTB class 10 bandwidth '30%' +set qos policy shaper VyOS-HTB class 10 description 'Multimedia' +set qos policy shaper VyOS-HTB class 10 match CS4 ip dscp 'CS4' +set qos policy shaper VyOS-HTB class 10 match-group 'Streaming-Video' +set qos policy shaper VyOS-HTB class 10 priority '1' +set qos policy shaper VyOS-HTB class 10 queue-type 'fair-queue' +set qos policy shaper VyOS-HTB class 20 description 'MC' +set qos policy shaper VyOS-HTB class 20 match-group 'Mission-Critical' +set qos policy shaper VyOS-HTB class 20 priority '2' +set qos policy shaper VyOS-HTB class 20 queue-type 'fair-queue' +set qos policy shaper VyOS-HTB default bandwidth '20%' +set qos policy shaper VyOS-HTB default queue-type 'fq-codel' +``` + +In this example, we can observe that different DSCP criteria are defined based +on our QoS configuration within the same policy group. + +#### Default + +Often you will also have to configure your *default* traffic in the same +way you do with a class. *Default* can be considered a class as it +behaves like that. It contains any traffic that did not match any +of the defined classes, so it is like an open class, a class without +matching filters. + +#### Class treatment + +Once a class has a filter configured, you will also have to define what +you want to do with the traffic of that class, what specific +Traffic-Control treatment you want to give it. You will have different +possibilities depending on the Traffic Policy you are configuring. + +``` none +vyos@vyos# set qos policy shaper MY-SHAPER class 30 +Possible completions: + bandwidth Available bandwidth for this policy (default: auto) + burst Burst size for this class (default: 15k) + ceiling Bandwidth limit for this class + codel-quantum + Deficit in the fair queuing algorithm (default 1514) + description Description + flows Number of flows into which the incoming packets are classified(default 1024) + interval Interval used to measure the delay (default 100) ++> match Class matching rule name + priority Priority for rule evaluation + queue-limit Maximum queue size + queue-type Queue type for default traffic (default: fq-codel) + set-dscp Change the Differentiated Services (DiffServ) field in the IP header + target Acceptable minimum standing/persistent queue delay (default: 5) +``` + +For instance, with `set qos policy shaper MY-SHAPER +class 30 set-dscp EF` you would be modifying the DSCP field value of packets in +that class to Expedite Forwarding. + +> DSCP values as per `2474` and `4595`: +> +> <table style="width:88%;"> +> <colgroup> +> <col style="width: 13%" /> +> <col style="width: 18%" /> +> <col style="width: 12%" /> +> <col style="width: 43%" /> +> </colgroup> +> <thead> +> <tr> +> <th>Binary +> value</th> +> <th>Configured +> value</th> +> <th><blockquote> +> <p>Drop +> rate</p> +> </blockquote></th> +> <th>Description</th> +> </tr> +> </thead> +> <tbody> +> <tr> +> <td>101110</td> +> <td><blockquote> +> <p>46</p> +> </blockquote></td> +> <td><blockquote> +> <ul> +> <li></li> +> </ul> +> </blockquote></td> +> <td>Expedited forwarding (EF)</td> +> </tr> +> <tr> +> <td>000000</td> +> <td><blockquote> +> <p>0</p> +> </blockquote></td> +> <td><blockquote> +> <ul> +> <li></li> +> </ul> +> </blockquote></td> +> <td>Best effort traffic, default</td> +> </tr> +> <tr> +> <td>001010</td> +> <td><blockquote> +> <p>10</p> +> </blockquote></td> +> <td>Low</td> +> <td>Assured Forwarding(AF) 11</td> +> </tr> +> <tr> +> <td>001100</td> +> <td><blockquote> +> <p>12</p> +> </blockquote></td> +> <td>Medium</td> +> <td>Assured Forwarding(AF) 12</td> +> </tr> +> <tr> +> <td>001110</td> +> <td><blockquote> +> <p>14</p> +> </blockquote></td> +> <td>High</td> +> <td>Assured Forwarding(AF) 13</td> +> </tr> +> <tr> +> <td>010010</td> +> <td><blockquote> +> <p>18</p> +> </blockquote></td> +> <td>Low</td> +> <td>Assured Forwarding(AF) 21</td> +> </tr> +> <tr> +> <td>010100</td> +> <td><blockquote> +> <p>20</p> +> </blockquote></td> +> <td>Medium</td> +> <td>Assured Forwarding(AF) 22</td> +> </tr> +> <tr> +> <td>010110</td> +> <td><blockquote> +> <p>22</p> +> </blockquote></td> +> <td>High</td> +> <td>Assured Forwarding(AF) 23</td> +> </tr> +> <tr> +> <td>011010</td> +> <td><blockquote> +> <p>26</p> +> </blockquote></td> +> <td>Low</td> +> <td>Assured Forwarding(AF) 31</td> +> </tr> +> <tr> +> <td>011100</td> +> <td><blockquote> +> <p>28</p> +> </blockquote></td> +> <td>Medium</td> +> <td>Assured Forwarding(AF) 32</td> +> </tr> +> <tr> +> <td>011110</td> +> <td><blockquote> +> <p>30</p> +> </blockquote></td> +> <td>High</td> +> <td>Assured Forwarding(AF) 33</td> +> </tr> +> <tr> +> <td>100010</td> +> <td><blockquote> +> <p>34</p> +> </blockquote></td> +> <td>Low</td> +> <td>Assured Forwarding(AF) 41</td> +> </tr> +> <tr> +> <td>100100</td> +> <td><blockquote> +> <p>36</p> +> </blockquote></td> +> <td>Medium</td> +> <td>Assured Forwarding(AF) 42</td> +> </tr> +> <tr> +> <td>100110</td> +> <td><blockquote> +> <p>38</p> +> </blockquote></td> +> <td>High</td> +> <td>Assured Forwarding(AF) 43</td> +> </tr> +> </tbody> +> </table> + +#### Embedding one policy into another one + +Often we need to embed one policy into another one. It is possible to do +so on classful policies, by attaching a new policy into a class. For +instance, you might want to apply different policies to the different +classes of a Round-Robin policy you have configured. + +A common example is the case of some policies which, in order to be +effective, they need to be applied to an interface that is directly +connected where the bottleneck is. If your router is not +directly connected to the bottleneck, but some hop before it, you can +emulate the bottleneck by embedding your non-shaping policy into a +classful shaping one so that it takes effect. + +You can configure a policy into a class through the `queue-type` +setting. + +``` none +set qos policy shaper FQ-SHAPER bandwidth 4gbit +set qos policy shaper FQ-SHAPER default bandwidth 100% +set qos policy shaper FQ-SHAPER default queue-type fq-codel +``` + +As shown in the last command of the example above, the <span class="title-ref">queue-type</span> +setting allows these combinations. You will be able to use it +in many policies. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Some policies already include other embedded policies inside. +That is the case of [Shaper](#shaper): each of its classes use fair-queue +unless you change it. + +</div> + +### Creating a traffic policy + +VyOS lets you control traffic in many different ways, here we will cover +every possibility. You can configure as many policies as you want, but +you will only be able to apply one policy per interface and direction +(inbound or outbound). + +Some policies can be combined, you will be able to [embed](#embed) a different +policy that will be applied to a class of the main policy. + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +**If you are looking for a policy for your outbound traffic** +but you don't know which one you need and you don't want to go +through every possible policy shown here, **our bet is that highly +likely you are looking for a** [Shaper](#shaper) **policy and you want to** +`set its queues <embed>` **as FQ-CoDel**. + +</div> + +#### Drop Tail + +**Queueing discipline:** PFIFO (Packet First In First Out).\ +**Applies to:** Outbound traffic. + +This the simplest queue possible you can apply to your traffic. Traffic +must go through a finite queue before it is actually sent. You must +define how many packets that queue can contain. + +When a packet is to be sent, it will have to go through that queue, so +the packet will be placed at the tail of it. When the packet completely +goes through it, it will be dequeued emptying its place in the queue and +being eventually handed to the NIC to be actually sent out. + +Despite the Drop-Tail policy does not slow down packets, if many packets +are to be sent, they could get dropped when trying to get enqueued at +the tail. This can happen if the queue has still not been able to +release enough packets from its head. + +This is the policy that requieres the lowest resources for the same +amount of traffic. But **very likely you do not need it as you cannot +get much from it. Sometimes it is used just to enable logging.** + +<div class="cfgcmd"> + +set qos policy drop-tail \<policy-name\> queue-limit +\<number-of-packets\> + +Use this command to configure a drop-tail policy (PFIFO). Choose a +unique name for this policy and the size of the queue by setting the +number of packets it can contain (maximum 4294967295). + +</div> + +#### Fair Queue + +**Queueing discipline:** SFQ (Stochastic Fairness Queuing).\ +**Applies to:** Outbound traffic. + +Fair Queue is a work-conserving scheduler which schedules the +transmission of packets based on flows, that is, it balances traffic +distributing it through different sub-queues in order to ensure +fairness so that each flow is able to send data in turn, preventing any +single one from drowning out the rest. + +<div class="cfgcmd"> + +set qos policy fair-queue \<policy-name\> + +Use this command to create a Fair-Queue policy and give it a name. +It is based on the Stochastic Fairness Queueing and can be applied to +outbound traffic. + +</div> + +In order to separate traffic, Fair Queue uses a classifier based on +source address, destination address and source port. The algorithm +enqueues packets to hash buckets based on those tree parameters. +Each of these buckets should represent a unique flow. Because multiple +flows may get hashed to the same bucket, the hashing algorithm is +perturbed at configurable intervals so that the unfairness lasts only +for a short while. Perturbation may however cause some inadvertent +packet reordering to occur. An advisable value could be 10 seconds. + +One of the uses of Fair Queue might be the mitigation of Denial of +Service attacks. + +<div class="cfgcmd"> + +set qos policy fair-queue \<policy-name\> hash-interval \<seconds\> + +Use this command to define a Fair-Queue policy, based on the +Stochastic Fairness Queueing, and set the number of seconds at which +a new queue algorithm perturbation will occur (maximum 4294967295). + +</div> + +When dequeuing, each hash-bucket with data is queried in a round robin +fashion. You can configure the length of the queue. + +<div class="cfgcmd"> + +set qos policy fair-queue \<policy-name\> queue-limit \<limit\> + +Use this command to define a Fair-Queue policy, based on the +Stochastic Fairness Queueing, and set the number of maximum packets +allowed to wait in the queue. Any other packet will be dropped. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Fair Queue is a non-shaping (work-conserving) policy, so it +will only be useful if your outgoing interface is really full. If it +is not, VyOS will not own the queue and Fair Queue will have no +effect. If there is bandwidth available on the physical link, you can +[embed](#embed) Fair-Queue into a classful shaping policy to make sure it owns +the queue. + +</div> + +#### FQ-CoDel + +**Queueing discipline** Fair/Flow Queue CoDel.\ +**Applies to:** Outbound Traffic. + +The FQ-CoDel policy distributes the traffic into 1024 FIFO queues and +tries to provide good service between all of them. It also tries to keep +the length of all the queues short. + +FQ-CoDel fights bufferbloat and reduces latency without the need of +complex configurations. It has become the new default Queueing +Discipline for the interfaces of some GNU/Linux distributions. + +It uses a stochastic model to classify incoming packets into +different flows and is used to provide a fair share of the bandwidth to +all the flows using the queue. Each flow is managed by the CoDel +queuing discipline. Reordering within a flow is avoided since Codel +internally uses a FIFO queue. + +FQ-CoDel is based on a modified Deficit Round Robin ([DRR](#DRR)) queue +scheduler with the CoDel Active Queue Management (AQM) algorithm +operating on each queue. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +FQ-Codel is a non-shaping (work-conserving) policy, so it +will only be useful if your outgoing interface is really full. If it +is not, VyOS will not own the queue and FQ-Codel will have no +effect. If there is bandwidth available on the physical link, you can +[embed](#embed) FQ-Codel into a classful shaping policy to make sure it owns +the queue. If you are not sure if you need to embed your FQ-CoDel +policy into a Shaper, do it. + +</div> + +FQ-CoDel is tuned to run ok with its default parameters at 10Gbit +speeds. It might work ok too at other speeds without configuring +anything, but here we will explain some cases when you might want to +tune its parameters. + +When running it at 1Gbit and lower, you may want to reduce the +<span class="title-ref">queue-limit</span> to 1000 packets or less. In rates like 10Mbit, you may +want to set it to 600 packets. + +If you are using FQ-CoDel embedded into [Shaper](#shaper) and you have large rates +(100Mbit and above), you may consider increasing <span class="title-ref">quantum</span> to 8000 or +higher so that the scheduler saves CPU. + +On low rates (below 40Mbit) you may want to tune <span class="title-ref">quantum</span> down to +something like 300 bytes. + +At very low rates (below 3Mbit), besides tuning <span class="title-ref">quantum</span> (300 keeps +being ok) you may also want to increase <span class="title-ref">target</span> to something like 15ms +and increase <span class="title-ref">interval</span> to something around 150 ms. + +<div class="cfgcmd"> + +set qos policy fq-codel \<policy name\> codel-quantum \<bytes\> + +Use this command to configure an fq-codel policy, set its name and +the maximum number of bytes (default: 1514) to be dequeued from a +queue at once. + +</div> + +<div class="cfgcmd"> + +set qos policy fq-codel \<policy name\> flows \<number-of-flows\> + +Use this command to configure an fq-codel policy, set its name and +the number of sub-queues (default: 1024) into which packets are +classified. + +</div> + +<div class="cfgcmd"> + +set qos policy fq-codel \<policy name\> interval \<miliseconds\> + +Use this command to configure an fq-codel policy, set its name and +the time period used by the control loop of CoDel to detect when a +persistent queue is developing, ensuring that the measured minimum +delay does not become too stale (default: 100ms). + +</div> + +<div class="cfgcmd"> + +set qos policy fq-codel \<policy-name\> queue-limit +\<number-of-packets\> + +Use this command to configure an fq-codel policy, set its name, and +define a hard limit on the real queue size. When this limit is +reached, new packets are dropped (default: 10240 packets). + +</div> + +<div class="cfgcmd"> + +set qos policy fq-codel \<policy-name\> target \<miliseconds\> + +Use this command to configure an fq-codel policy, set its name, and +define the acceptable minimum standing/persistent queue delay. This +minimum delay is identified by tracking the local minimum queue delay +that packets experience (default: 5ms). + +</div> + +##### Example + +A simple example of an FQ-CoDel policy working inside a Shaper one. + +``` none +set qos policy shaper FQ-CODEL-SHAPER bandwidth 2gbit +set qos policy shaper FQ-CODEL-SHAPER default bandwidth 100% +set qos policy shaper FQ-CODEL-SHAPER default queue-type fq-codel +``` + +#### Limiter + +**Queueing discipline:** Ingress policer.\ +**Applies to:** Inbound traffic. + +Limiter is one of those policies that uses [classes](#classes) (Ingress qdisc is +actually a classless policy but filters do work in it). + +The limiter performs basic ingress policing of traffic flows. Multiple +classes of traffic can be defined and traffic limits can be applied to +each class. Although the policer uses a token bucket mechanism +internally, it does not have the capability to delay a packet as a +shaping mechanism does. Traffic exceeding the defined bandwidth limits +is directly dropped. A maximum allowed burst can be configured too. + +You can configure classes (up to 4090) with different settings and a +default policy which will be applied to any traffic not matching any of +the configured classes. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +In the case you want to apply some kind of **shaping** to your +**inbound** traffic, check the [ingress-shaping](#ingress-shaping) section. + +</div> + +<div class="cfgcmd"> + +set qos policy limiter \<policy-name\> class \<class ID\> match +\<match-name\> description \<description\> + +Use this command to configure an Ingress Policer, defining its name, +a class identifier (1-4090), a class matching rule name and its +description. + +</div> + +Once the matching rules are set for a class, you can start configuring +how you want matching traffic to behave. + +<div class="cfgcmd"> + +set qos policy limiter \<policy-name\> class \<class-ID\> bandwidth +\<rate\> + +Use this command to configure an Ingress Policer, defining its name, +a class identifier (1-4090) and the maximum allowed bandwidth for +this class. + +</div> + +<div class="cfgcmd"> + +set qos policy limiter \<policy-name\> class \<class-ID\> burst +\<burst-size\> + +Use this command to configure an Ingress Policer, defining its name, +a class identifier (1-4090) and the burst size in bytes for this +class (default: 15). + +</div> + +<div class="cfgcmd"> + +set qos policy limiter \<policy-name\> default bandwidth \<rate\> + +Use this command to configure an Ingress Policer, defining its name +and the maximum allowed bandwidth for its default policy. + +</div> + +<div class="cfgcmd"> + +set qos policy limiter \<policy-name\> default burst \<burst-size\> + +Use this command to configure an Ingress Policer, defining its name +and the burst size in bytes (default: 15) for its default policy. + +</div> + +<div class="cfgcmd"> + +set qos policy limiter \<policy-name\> class \<class ID\> priority +\<value\> + +Use this command to configure an Ingress Policer, defining its name, +a class identifier (1-4090), and the priority (0-20, default 20) in +which the rule is evaluated (the lower the number, the higher the +priority). + +</div> + +#### Network Emulator + +**Queueing discipline:** netem (Network Emulator) + TBF (Token Bucket Filter).\ +**Applies to:** Outbound traffic. + +VyOS Network Emulator policy emulates the conditions you can suffer in a +real network. You will be able to configure things like rate, burst, +delay, packet loss, packet corruption or packet reordering. + +This could be helpful if you want to test how an application behaves +under certain network conditions. + +<div class="cfgcmd"> + +set qos policy network-emulator \<policy-name\> bandwidth \<rate\> + +Use this command to configure the maximum rate at which traffic will +be shaped in a Network Emulator policy. Define the name of the policy +and the rate. + +</div> + +<div class="cfgcmd"> + +set qos policy network-emulator \<policy-name\> burst \<burst-size\> + +Use this command to configure the burst size of the traffic in a +Network Emulator policy. Define the name of the Network Emulator +policy and its traffic burst size (it will be configured through the +Token Bucket Filter qdisc). Default:15kb. It will only take effect if +you have configured its bandwidth too. + +</div> + +<div class="cfgcmd"> + +set qos policy network-emulator \<policy-name\> delay +\<delay\> + +Use this command to configure a Network Emulator policy defining its +name and the fixed amount of time you want to add to all packet going +out of the interface. The latency will be added through the +Token Bucket Filter qdisc. It will only take effect if you have +configured its bandwidth too. You can use secs, ms and us. Default: +50ms. + +</div> + +<div class="cfgcmd"> + +set qos policy network-emulator \<policy-name\> corruption +\<percent\> + +Use this command to emulate noise in a Network Emulator policy. Set +the policy name and the percentage of corrupted packets you want. A +random error will be introduced in a random position for the chosen +percent of packets. + +</div> + +<div class="cfgcmd"> + +set qos policy network-emulator \<policy-name\> loss +\<percent\> + +Use this command to emulate packet-loss conditions in a Network +Emulator policy. Set the policy name and the percentage of loss +packets your traffic will suffer. + +</div> + +<div class="cfgcmd"> + +set traffic-policy network-emulator \<policy-name\> reordering +\<percent\> + +Use this command to emulate packet-reordering conditions in a Network +Emulator policy. Set the policy name and the percentage of reordered +packets your traffic will suffer. + +</div> + +<div class="cfgcmd"> + +set traffic-policy network-emulator \<policy-name\> queue-limit +\<limit\> + +Use this command to define the length of the queue of your Network +Emulator policy. Set the policy name and the maximum number of +packets (1-4294967295) the queue may hold queued at a time. + +</div> + +#### Priority Queue + +**Queueing discipline:** PRIO.\ +**Applies to:** Outbound traffic. + +The Priority Queue is a classful scheduling policy. It does not delay +packets (Priority Queue is not a shaping policy), it simply dequeues +packets according to their priority. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Priority Queue, as other non-shaping policies, is only useful +if your outgoing interface is really full. If it is not, VyOS will +not own the queue and Priority Queue will have no effect. If there is +bandwidth available on the physical link, you can [embed](#embed) Priority +Queue into a classful shaping policy to make sure it owns the queue. +In that case packets can be prioritized based on DSCP. + +</div> + +Up to seven queues -defined as [classes](#classes) with different priorities- can +be configured. Packets are placed into queues based on associated match +criteria. Packets are transmitted from the queues in priority order. If +classes with a higher priority are being filled with packets +continuously, packets from lower priority classes will only be +transmitted after traffic volume from higher priority classes decreases. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +In Priority Queue we do not define clases with a meaningless +class ID number but with a class priority number (1-7). The lower the +number, the higher the priority. + +</div> + +As with other policies, you can define different type of matching rules +for your classes: + +``` none +vyos@vyos# set qos policy priority-queue MY-PRIO class 3 match MY-MATCH-RULE +Possible completions: + description Description + > ether Ethernet header match + interface Interface to use + > ip Match IP protocol header + > ipv6 Match IPV6 protocol header + mark Match on mark applied by firewall + vif Virtual Local Area Network (VLAN) ID for this match +``` + +As with other policies, you can [embed](#embed) other policies into the classes +(and default) of your Priority Queue policy through the `queue-type` +setting: + +``` none +vyos@vyos# set qos policy priority-queue MY-PRIO class 3 queue-type +Possible completions: + drop-tail First-In-First-Out (FIFO) (default) + fq-codel Fair Queue Codel + fair-queue Stochastic Fair Queue (SFQ) + priority Priority queueing + random-detect + Random Early Detection (RED) +``` + +<div class="cfgcmd"> + +set qos policy priority-queue \<policy-name\> class \<class-ID\> +queue-limit \<limit\> + +Use this command to configure a Priority Queue policy, set its name, +set a class with a priority from 1 to 7 and define a hard limit on +the real queue size. When this limit is reached, new packets are +dropped. + +</div> + +#### Random-Detect + +**Queueing discipline:** Generalized Random Early Drop.\ +**Applies to:** Outbound traffic. + +A simple Random Early Detection (RED) policy would start randomly +dropping packets from a queue before it reaches its queue limit thus +avoiding congestion. That is good for TCP connections as the gradual +dropping of packets acts as a signal for the sender to decrease its +transmission rate. + +In contrast to simple RED, VyOS' Random-Detect uses a Generalized Random +Early Detect policy that provides different virtual queues based on the +IP Precedence value so that some virtual queues can drop more packets +than others. + +This is achieved by using the first three bits of the ToS (Type of +Service) field to categorize data streams and, in accordance with the +defined precedence parameters, a decision is made. + +IP precedence as defined in `791`: + +> <table style="width:50%;"> +> <colgroup> +> <col style="width: 18%" /> +> <col style="width: 31%" /> +> </colgroup> +> <thead> +> <tr> +> <th>Precedence</th> +> <th><blockquote> +> <p>Priority</p> +> </blockquote></th> +> </tr> +> </thead> +> <tbody> +> <tr> +> <td><blockquote> +> <p>7</p> +> </blockquote></td> +> <td>Network Control</td> +> </tr> +> <tr> +> <td><blockquote> +> <p>6</p> +> </blockquote></td> +> <td>Internetwork Control</td> +> </tr> +> <tr> +> <td><blockquote> +> <p>5</p> +> </blockquote></td> +> <td>CRITIC/ECP</td> +> </tr> +> <tr> +> <td><blockquote> +> <p>4</p> +> </blockquote></td> +> <td>Flash Override</td> +> </tr> +> <tr> +> <td><blockquote> +> <p>3</p> +> </blockquote></td> +> <td>Flash</td> +> </tr> +> <tr> +> <td><blockquote> +> <p>2</p> +> </blockquote></td> +> <td>Immediate</td> +> </tr> +> <tr> +> <td><blockquote> +> <p>1</p> +> </blockquote></td> +> <td>Priority</td> +> </tr> +> <tr> +> <td><blockquote> +> <p>0</p> +> </blockquote></td> +> <td>Routine</td> +> </tr> +> </tbody> +> </table> + +Random-Detect could be useful for heavy traffic. One use of this +algorithm might be to prevent a backbone overload. But only for TCP +(because dropped packets could be retransmitted), not for UDP. + +<div class="cfgcmd"> + +set qos policy random-detect \<policy-name\> bandwidth \<bandwidth\> + +Use this command to configure a Random-Detect policy, set its name +and set the available bandwidth for this policy. It is used for +calculating the average queue size after some idle time. It should be +set to the bandwidth of your interface. Random Detect is not a +shaping policy, this command will not shape. + +</div> + +<div class="cfgcmd"> + +set qos policy random-detect \<policy-name\> precedence +\<IP-precedence-value\> average-packet \<bytes\> + +Use this command to configure a Random-Detect policy and set its +name, then state the IP Precedence for the virtual queue you are +configuring and what the size of its average-packet should be +(in bytes, default: 1024). + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +When configuring a Random-Detect policy: **the higher the +precedence number, the higher the priority**. + +</div> + +<div class="cfgcmd"> + +set qos policy random-detect \<policy-name\> precedence +\<IP-precedence-value\> mark-probability \<value\> + +Use this command to configure a Random-Detect policy and set its +name, then state the IP Precedence for the virtual queue you are +configuring and what its mark (drop) probability will be. Set the +probability by giving the N value of the fraction 1/N (default: 10). + +</div> + +<div class="cfgcmd"> + +set qos policy random-detect \<policy-name\> precedence +\<IP-precedence-value\> maximum-threshold \<packets\> + +Use this command to configure a Random-Detect policy and set its +name, then state the IP Precedence for the virtual queue you are +configuring and what its maximum threshold for random detection will +be (from 0 to 4096 packets, default: 18). At this size, the marking +(drop) probability is maximal. + +</div> + +<div class="cfgcmd"> + +set qos policy random-detect \<policy-name\> precedence +\<IP-precedence-value\> minimum-threshold \<packets\> + +Use this command to configure a Random-Detect policy and set its +name, then state the IP Precedence for the virtual queue you are +configuring and what its minimum threshold for random detection will +be (from 0 to 4096 packets). If this value is exceeded, packets +start being eligible for being dropped. + +</div> + +The default values for the minimum-threshold depend on IP precedence: + +> <table style="width:51%;"> +> <colgroup> +> <col style="width: 18%" /> +> <col style="width: 33%" /> +> </colgroup> +> <thead> +> <tr> +> <th>Precedence</th> +> <th>default min-threshold</th> +> </tr> +> </thead> +> <tbody> +> <tr> +> <td><blockquote> +> <p>7</p> +> </blockquote></td> +> <td><blockquote> +> <p>16</p> +> </blockquote></td> +> </tr> +> <tr> +> <td><blockquote> +> <p>6</p> +> </blockquote></td> +> <td><blockquote> +> <p>15</p> +> </blockquote></td> +> </tr> +> <tr> +> <td><blockquote> +> <p>5</p> +> </blockquote></td> +> <td><blockquote> +> <p>14</p> +> </blockquote></td> +> </tr> +> <tr> +> <td><blockquote> +> <p>4</p> +> </blockquote></td> +> <td><blockquote> +> <p>13</p> +> </blockquote></td> +> </tr> +> <tr> +> <td><blockquote> +> <p>3</p> +> </blockquote></td> +> <td><blockquote> +> <p>12</p> +> </blockquote></td> +> </tr> +> <tr> +> <td><blockquote> +> <p>2</p> +> </blockquote></td> +> <td><blockquote> +> <p>11</p> +> </blockquote></td> +> </tr> +> <tr> +> <td><blockquote> +> <p>1</p> +> </blockquote></td> +> <td><blockquote> +> <p>10</p> +> </blockquote></td> +> </tr> +> <tr> +> <td><blockquote> +> <p>0</p> +> </blockquote></td> +> <td><blockquote> +> <p>9</p> +> </blockquote></td> +> </tr> +> </tbody> +> </table> + +<div class="cfgcmd"> + +set qos policy random-detect \<policy-name\> precedence +\<IP-precedence-value\> queue-limit \<packets\> + +Use this command to configure a Random-Detect policy and set its +name, then name the IP Precedence for the virtual queue you are +configuring and what the maximum size of its queue will be (from 1 to +1-4294967295 packets). Packets are dropped when the current queue +length reaches this value. + +</div> + +If the average queue size is lower than the **min-threshold**, an +arriving packet will be placed in the queue. + +In the case the average queue size is between **min-threshold** and +**max-threshold**, then an arriving packet would be either dropped or +placed in the queue, it will depend on the defined **mark-probability**. + +If the current queue size is larger than **queue-limit**, +then packets will be dropped. The average queue size depends on its +former average size and its current one. + +If **max-threshold** is set but **min-threshold is not, then**min-threshold\*\* is scaled to 50% of **max-threshold**. + +In principle, values must be +`min-threshold` \< `max-threshold` \< `queue-limit`. + +#### Rate Control + +**Queueing discipline:** Tocken Bucket Filter.\ +**Applies to:** Outbound traffic. + +Rate-Control is a classless policy that limits the packet flow to a set +rate. It is a pure shaper, it does not schedule traffic. Traffic is +filtered based on the expenditure of tokens. Tokens roughly correspond +to bytes. + +Short bursts can be allowed to exceed the limit. On creation, the +Rate-Control traffic is stocked with tokens which correspond to the +amount of traffic that can be burst in one go. Tokens arrive at a steady +rate, until the bucket is full. + +<div class="cfgcmd"> + +set qos policy rate-control \<policy-name\> bandwidth \<rate\> + +Use this command to configure a Rate-Control policy, set its name +and the rate limit you want to have. + +</div> + +<div class="cfgcmd"> + +set qos policy rate-control \<policy-name\> burst \<burst-size\> + +Use this command to configure a Rate-Control policy, set its name +and the size of the bucket in bytes which will be available for +burst. + +</div> + +As a reference: for 10mbit/s on Intel, you might need at least 10kbyte +buffer if you want to reach your configured rate. + +A very small buffer will soon start dropping packets. + +<div class="cfgcmd"> + +set qos policy rate-control \<policy-name\> latency + +Use this command to configure a Rate-Control policy, set its name +and the maximum amount of time a packet can be queued (default: 50 +ms). + +</div> + +Rate-Control is a CPU-friendly policy. You might consider using it when +you just simply want to slow traffic down. + +#### Round Robin + +**Queueing discipline:** Deficit Round Robin.\ +**Applies to:** Outbound traffic. + +The round-robin policy is a classful scheduler that divides traffic in +different [classes](#classes) you can configure (up to 4096). You can [embed](#embed) a +new policy into each of those classes (default included). + +Each class is assigned a deficit counter (the number of bytes that a +flow is allowed to transmit when it is its turn) initialized to quantum. +Quantum is a parameter you configure which acts like a credit of fix +bytes the counter receives on each round. Then the Round-Robin policy +starts moving its Round Robin pointer through the queues. If the deficit +counter is greater than the packet's size at the head of the queue, this +packet will be sent and the value of the counter will be decremented by +the packet size. Then, the size of the next packet will be compared to +the counter value again, repeating the process. Once the queue is empty +or the value of the counter is insufficient, the Round-Robin pointer +will move to the next queue. If the queue is empty, the value of the +deficit counter is reset to 0. + +At every round, the deficit counter adds the quantum so that even large +packets will have their opportunity to be dequeued. + +<div class="cfgcmd"> + +set qos policy round-robin \<policy name\> class +\<class-ID\> quantum \<packets\> + +Use this command to configure a Round-Robin policy, set its name, set +a class ID, and the quantum for that class. The deficit counter will +add that value each round. + +</div> + +<div class="cfgcmd"> + +set qos policy round-robin \<policy name\> class +\<class ID\> queue-limit \<packets\> + +Use this command to configure a Round-Robin policy, set its name, set +a class ID, and the queue size in packets. + +</div> + +As with other policies, Round-Robin can [embed](#embed) another policy into a +class through the `queue-type` setting. + +``` none +vyos@vyos# set qos policy round-robin DRR class 10 queue-type +Possible completions: + drop-tail First-In-First-Out (FIFO) (default) + fq-codel Fair Queue Codel + fair-queue Stochastic Fair Queue (SFQ) + priority Priority queueing based + random-detect + Random Early Detection (RED) +``` + +#### Shaper + +**Queueing discipline:** Hierarchical Token Bucket.\ +**Applies to:** Outbound traffic. + +The Shaper policy does not guarantee a low delay, but it does guarantee +bandwidth to different traffic classes and also lets you decide how to +allocate more traffic once the guarantees are met. + +Each class can have a guaranteed part of the total bandwidth defined for +the whole policy, so all those shares together should not be higher +than the policy's whole bandwidth. + +If guaranteed traffic for a class is met and there is room for more +traffic, the ceiling parameter can be used to set how much more +bandwidth could be used. If guaranteed traffic is met and there are +several classes willing to use their ceilings, the priority parameter +will establish the order in which that additional traffic will be +allocated. Priority can be any number from 0 to 7. The lower the number, +the higher the priority. + +<div class="cfgcmd"> + +set qos policy shaper \<policy-name\> bandwidth \<rate\> + +Use this command to configure a Shaper policy, set its name +and the maximum bandwidth for all combined traffic. + +</div> + +<div class="cfgcmd"> + +set qos policy shaper \<policy-name\> class \<class-ID\> bandwidth +\<rate\> + +Use this command to configure a Shaper policy, set its name, define +a class and set the guaranteed traffic you want to allocate to that +class. + +</div> + +<div class="cfgcmd"> + +set qos policy shaper \<policy-name\> class \<class-ID\> burst +\<bytes\> + +Use this command to configure a Shaper policy, set its name, define +a class and set the size of the [tocken bucket](https://en.wikipedia.org/wiki/Token_bucket) in bytes, which will +be available to be sent at ceiling speed (default: 15Kb). + +</div> + +<div class="cfgcmd"> + +set qos policy shaper \<policy-name\> class \<class-ID\> ceiling +\<bandwidth\> + +Use this command to configure a Shaper policy, set its name, define +a class and set the maximum speed possible for this class. The +default ceiling value is the bandwidth value. + +</div> + +<div class="cfgcmd"> + +set qos policy shaper \<policy-name\> class \<class-ID\> priority +\<0-7\> + +Use this command to configure a Shaper policy, set its name, define +a class and set the priority for usage of available bandwidth once +guarantees have been met. The lower the priority number, the higher +the priority. The default priority value is 0, the highest priority. + +</div> + +As with other policies, Shaper can [embed](#embed) other policies into its +classes through the `queue-type` setting and then configure their +parameters. + +``` none +vyos@vyos# set qos policy shaper HTB class 10 queue-type +Possible completions: + fq-codel Fair Queue Codel (default) + fair-queue Stochastic Fair Queue (SFQ) + drop-tail First-In-First-Out (FIFO) + priority Priority queueing + random-detect + Random Early Detection (RED) +``` + +``` none +vyos@vyos# set qos policy shaper HTB class 10 +Possible completions: + bandwidth Available bandwidth for this policy (default: auto) + burst Burst size for this class (default: 15k) + ceiling Bandwidth limit for this class + codel-quantum + Deficit in the fair queuing algorithm (default 1514) + description Description + flows Number of flows into which the incoming packets are classified (default 1024) + interval Interval used to measure the delay (default 100) ++> match Class matching rule name + priority Priority for rule evaluation + queue-limit Maximum queue size (packets) + queue-type Queue type for default traffic (default: fq-codel) + set-dscp Change the Differentiated Services (DiffServ) field in the IP header + target Acceptable minimum standing/persistent queue delay (default: 5) +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you configure a class for **VoIP traffic**, don't give it any +*ceiling*, otherwise new VoIP calls could start when the link is +available and get suddenly dropped when other classes start using +their assigned *bandwidth* share. + +</div> + +##### Example + +A simple example of Shaper using priorities. + +``` none +set qos policy shaper MY-HTB bandwidth '50mbit' +set qos policy shaper MY-HTB class 10 bandwidth '20%' +set qos policy shaper MY-HTB class 10 match DSCP ip dscp 'EF' +set qos policy shaper MY-HTB class 10 queue-type 'fq-codel' +set qos policy shaper MY-HTB class 20 bandwidth '10%' +set qos policy shaper MY-HTB class 20 ceiling '50%' +set qos policy shaper MY-HTB class 20 match PORT666 ip destination port '666' +set qos policy shaper MY-HTB class 20 priority '3' +set qos policy shaper MY-HTB class 20 queue-type 'fair-queue' +set qos policy shaper MY-HTB class 30 bandwidth '10%' +set qos policy shaper MY-HTB class 30 ceiling '50%' +set qos policy shaper MY-HTB class 30 match ADDRESS30 ip source address '192.168.30.0/24' +set qos policy shaper MY-HTB class 30 priority '5' +set qos policy shaper MY-HTB class 30 queue-type 'fair-queue' +set qos policy shaper MY-HTB default bandwidth '10%' +set qos policy shaper MY-HTB default ceiling '100%' +set qos policy shaper MY-HTB default priority '7' +set qos policy shaper MY-HTB default queue-type 'fair-queue' +``` + +#### CAKE + +**Queueing discipline:** Deficit mode.\ +**Applies to:** Outbound traffic. + +[Common Applications Kept Enhanced](https://www.bufferbloat.net/projects/codel/wiki/Cake/) (CAKE) is a comprehensive queue management +system, implemented as a queue discipline (qdisc) for the Linux kernel. It is +designed to replace and improve upon the complex hierarchy of simple qdiscs +presently required to effectively tackle the bufferbloat problem at the network +edge. + +<div class="cfgcmd"> + +set qos policy cake \<text\> bandwidth \<value\> + +Set the shaper bandwidth, either as an explicit bitrate or a percentage +of the interface bandwidth. + +</div> + +<div class="cfgcmd"> + +set qos policy cake \<text\> description + +Set a description for the shaper. + +</div> + +<div class="cfgcmd"> + +set qos policy cake \<text\> flow-isolation blind + +Disables flow isolation, all traffic passes through a single queue. + +</div> + +<div class="cfgcmd"> + +set qos policy cake \<text\> flow-isolation dst-host + +Flows are defined only by destination address. + +</div> + +<div class="cfgcmd"> + +set qos policy cake \<text\> flow-isolation dual-dst-host + +Flows are defined by the 5-tuple. Fairness is applied first over destination +addresses, then over individual flows. + +</div> + +<div class="cfgcmd"> + +set qos policy cake \<text\> flow-isolation dual-src-host + +Flows are defined by the 5-tuple. Fairness is applied first over source +addresses, then over individual flows. + +</div> + +<div class="cfgcmd"> + +set qos policy cake \<text\> flow-isolation flow + +Flows are defined by the entire 5-tuple (source IP address, source port, +destination IP address, destination port, transport protocol). + +</div> + +<div class="cfgcmd"> + +set qos policy cake \<text\> flow-isolation host + +Flows are defined by source-destination host pairs. + +</div> + +<div class="cfgcmd"> + +set qos policy cake \<text\> flow-isolation nat + +Perform NAT lookup before applying flow-isolation rules. + +</div> + +<div class="cfgcmd"> + +set qos policy cake \<text\> flow-isolation src-host + +Flows are defined only by source address. + +</div> + +<div class="cfgcmd"> + +set qos policy cake \<text\> flow-isolation triple-isolate + +**(Default)** Flows are defined by the 5-tuple, fairness is applied over source and +destination addresses and also over individual flows. + +</div> + +<div class="cfgcmd"> + +set qos policy cake \<text\> rtt + +Defines the round-trip time used for active queue management (AQM) in +milliseconds. The default value is 100. + +</div> + +### Applying a traffic policy + +Once a traffic-policy is created, you can apply it to an interface: + +``` none +set qos interface eth0 egress WAN-OUT +``` + +You can only apply one policy per interface and direction, but you could +reuse a policy on different interfaces and directions: + +``` none +set qos interface eth0 ingress WAN-IN +set qos interface eth0 egress WAN-OUT +set qos interface eth1 ingress LAN-IN +set qos interface eth1 egress LAN-OUT +set qos interface eth2 ingress LAN-IN +set qos interface eth2 egress LAN-OUT +set qos interface eth3 ingress TWO-WAY-POLICY +set qos interface eth3 egress TWO-WAY-POLICY +set qos interface eth4 ingress TWO-WAY-POLICY +set qos interface eth4 egress TWO-WAY-POLICY +``` + +### The case of ingress shaping + +**Applies to:** Inbound traffic. + +For the ingress traffic of an interface, there is only one policy you +can directly apply, a **Limiter** policy. You cannot apply a shaping +policy directly to the ingress traffic of any interface because shaping +only works for outbound traffic. + +This workaround lets you apply a shaping policy to the ingress traffic +by first redirecting it to an in-between virtual interface +([Intermediate Functional Block](https://www.linuxfoundation.org/collaborate/workgroups/networking/ifb)). There, in that virtual interface, +you will be able to apply any of the policies that work for outbound +traffic, for instance, a shaping one. + +That is how it is possible to do the so-called "ingress shaping". + +``` none +set qos policy shaper MY-INGRESS-SHAPING bandwidth 1000kbit +set qos policy shaper MY-INGRESS-SHAPING default bandwidth 1000kbit +set qos policy shaper MY-INGRESS-SHAPING default queue-type fair-queue + +set qos interface ifb0 egress MY-INGRESS-SHAPING +set interfaces ethernet eth0 redirect ifb0 +``` + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +Do not configure IFB as the first step. First create everything else +of your traffic-policy, and then you can configure IFB. +Otherwise you might get the `RTNETLINK answer: File exists` error, +which can be solved with `sudo ip link delete ifb0`. + +</div> diff --git a/docs/configuration/vpn/ipsec/md-index.md b/docs/configuration/vpn/ipsec/md-index.md new file mode 100644 index 00000000..f8ef0e17 --- /dev/null +++ b/docs/configuration/vpn/ipsec/md-index.md @@ -0,0 +1,15 @@ +# IPsec + +<div class="toctree" maxdepth="1" includehidden=""> + +ipsec_general +site2site_ipsec +troubleshooting_ipsec + +</div> + +pages to sort + +<div class="toctree" maxdepth="1" includehidden=""> + +</div> diff --git a/docs/configuration/vpn/ipsec/md-ipsec_general.md b/docs/configuration/vpn/ipsec/md-ipsec_general.md new file mode 100644 index 00000000..1fbb5974 --- /dev/null +++ b/docs/configuration/vpn/ipsec/md-ipsec_general.md @@ -0,0 +1,399 @@ +# IPsec General Information + +## Information about IPsec + +IPsec is the framework used to secure data. +IPsec accomplishes these goals by providing authentication, +encryption of IP network packets, key exchange, and key management. +VyOS uses strongSwan for its IPsec implementation. + +**Authentication Header (AH)** is defined in `4302`. It creates +a hash using the IP header and data payload, and prepends it to the +packet. This hash is used to validate that the data has not been +changed during transfer over the network. + +**Encapsulating Security Payload (ESP)** is defined in `4303`. +It provides encryption and authentication of the data. + +There are two IPsec modes: +**IPsec Transport Mode**: +In transport mode, an IPSec header (AH or ESP) is inserted +between the IP header and the upper layer protocol header. + +**IPsec Tunnel Mode:** +In tunnel mode, the original IP packet is encapsulated in +another IP datagram, and an IPsec header (AH or ESP) is +inserted between the outer and inner headers. + +<figure> +<img src="/_static/images/ESP_AH.webp" alt="AH and ESP in Transport Mode and Tunnel Mode" /> +</figure> + +## IKE (Internet Key Exchange) + +The default IPsec method for secure key negotiation is the Internet Key +Exchange (IKE) protocol. IKE is designed to provide mutual authentication +of systems, as well as to establish a shared secret key to create IPsec +security associations. A security association (SA) includes all relevant +attributes of the connection, including the cryptographic algorithm used, +the IPsec mode, the encryption key, and other parameters related to the +transmission of data over the VPN connection. + +### IKEv1 + +IKEv1 is the older version and is still used today. Nowadays, most +manufacturers recommend using IKEv2 protocol. + +IKEv1 is described in the next RFCs: `2409` (IKE), `3407` +(IPsec DOI), `3947` (NAT-T), `3948` (UDP Encapsulation +of ESP Packets), `3706` (DPD) + +IKEv1 operates in two phases to establish these IKE and IPsec SAs: +- **Phase 1** provides mutual authentication of the IKE peers and + establishment of the session key. This phase creates an IKE SA (a + security association for IKE) using a DH exchange, cookies, and an + ID exchange. Once an IKE SA is established, all IKE communication + between the initiator and responder is protected with encryption + and an integrity check that is authenticated. The purpose of IKE + phase 1 is to facilitate a secure channel between the peers so that + phase 2 negotiations can occur securely. IKE phase 1 offers two modes: + Main and Aggressive. + + > - **Main Mode** is used for site-to-site VPN connections. + > - **Aggressive Mode** is used for remote access VPN connections. + +- **Phase 2** provides for the negotiation and establishment of the + IPsec SAs using ESP or AH to protect IP data traffic. + +### IKEv2 + +IKEv2 is described in `7296`. The biggest difference between IKEv1 and +IKEv2 is that IKEv2 is much simpler and more reliable than IKEv1 because +fewer messages are exchanged during the establishment of the VPN and +additional security capabilities are available. + +### IKE Authentication + +VyOS supports 3 authentication methods. +- **Pre-shared keys**: In this method, both peers of the IPsec + tunnel must have the same preshared keys. +- **Digital certificates**: PKI is used in this method. +- **RSA-keys**: If the RSA-keys method is used in your IKE policy, + you need to make sure each peer has the other peer’s public keys. + +## DPD (Dead Peer Detection) + +This is a mechanism used to detect when a VPN peer is no longer active. +This mechanism has different algorithms in IKEv1 and IKEv2 in VyOS. +DPD Requests are sent as ISAKMP R-U-THERE messages and DPD Responses +are sent as ISAKMP R-U-THERE-ACK messages. In IKEv1, DPD sends messages +every configured interval. The remote peer is considered unreachable +if no response to these packets is received within the DPD timeout. +In IKEv2, DPD sends messages every configured interval. If one request +does not receive a response, strongSwan executes its retransmission algorithm with +its timers. <https://docs.strongswan.org/docs/5.9/config/retransmission.html> + +## Configuration IKE + +### IKE (Internet Key Exchange) Attributes + +VyOS IKE group has the next options: + +<div class="cfgcmd"> + +set vpn ipsec ike-group \<name\> close-action \<action\> + +Defines the action to take if the remote peer unexpectedly +closes a CHILD_SA: + +- **none** - Set action to none (default), + +\* **trap** - Installs a trap policy (IPsec policy without Security +Association) for the CHILD_SA and traffic matching these policies +will trigger acquire events that cause the daemon to establish the +required IKE/IPsec SAs. + +- **start** - Tries to immediately re-create the CHILD_SA. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec ike-group \<name\> ikev2-reauth + +Whether rekeying of an IKE_SA should also reauthenticate +the peer. In IKEv1, reauthentication is always done. +Setting this parameter enables remote host re-authentication +during an IKE rekey. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec ike-group \<name\> key-exchange + +Which protocol should be used to initialize the connection +If not set both protocols are handled and connections will +use IKEv2 when initiating, but accept any protocol version +when responding: + +- **ikev1** - Use IKEv1 for Key Exchange. +- **ikev2** - Use IKEv2 for Key Exchange. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec ike-group \<name\> lifetime + +IKE lifetime in seconds \<0-86400\> (default 28800). + +</div> + +<div class="cfgcmd"> + +set vpn ipsec ike-group \<name\> mode + +IKEv1 Phase 1 Mode Selection: + +\* **main** - Use Main mode for Key Exchanges in the IKEv1 Protocol +(Recommended Default). + +\* **aggressive** - Use Aggressive mode for Key Exchanges in the IKEv1 +protocol aggressive mode is much more insecure compared to Main mode. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec ike-group \<name\> proposal \<number\> dh-group \<dh-group number\> + +Diffie-Hellman algorithm group. Default value is **2**. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec ike-group \<name\> proposal \<number\> encryption \<encryption\> + +Encryption algorithm. Default value is **aes128**. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec ike-group \<name\> proposal \<number\> hash \<hash\> + +Hash algorithm. Default value is **sha1**. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec ike-group \<name\> proposal \<number\> prf \<prf\> + +Pseudo-random function. + +</div> + +### DPD (Dead Peer Detection) Configuration + +<div class="cfgcmd"> + +set vpn ipsec ike-group \<name\> dead-peer-detection action \<action\> + +Action to perform for this CHILD_SA on DPD timeout. + +- **trap** - Installs a trap policy (IPsec policy without Security + Association), which will catch matching traffic and tries to + re-negotiate the tunnel on-demand. +- **clear** - Closes the CHILD_SA and does not take further action + (default). +- **restart** - Immediately tries to re-negotiate the CHILD_SA + under a fresh IKE_SA. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec ike-group \<name\> dead-peer-detection interval \<interval\> + +Keep-alive interval in seconds \<2-86400\> (default 30). + +</div> + +<div class="cfgcmd"> + +set vpn ipsec ike-group \<name\> dead-peer-detection timeout \<timeout\> + +Keep-alive timeout in seconds \<2-86400\> (default 120) **IKEv1 only** + +</div> + +### ESP (Encapsulating Security Payload) Attributes + +In VyOS, ESP attributes are specified through ESP groups. +Multiple proposals can be specified in a single group. + +VyOS ESP group has the next options: + +<div class="cfgcmd"> + +set vpn ipsec esp-group \<name\> compression + +Enables the IPComp(IP Payload Compression) protocol which allows +compressing the content of IP packets. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec esp-group \<name\> disable-rekey + +Do not locally initiate a re-key of the SA, remote peer must +re-key before expiration. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec esp-group \<name\> life-bytes \<bytes\> + +ESP life in bytes \<1024-26843545600000\>. Number of bytes +transmitted over an IPsec SA before it expires. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec esp-group \<name\> life-packets \<packets\> + +ESP life in packets \<1000-26843545600000\>. +Number of packets transmitted over an IPsec SA before it expires. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec esp-group \<name\> lifetime \<timeout\> + +ESP lifetime in seconds \<30-86400\> (default 3600). +How long a particular instance of a connection (a set of +encryption/authentication keys for user packets) should last, +from successful negotiation to expiry. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec esp-group \<name\> mode \<mode\> + +The type of the connection: + +- **tunnel** - Tunnel mode (default). +- **transport** - Transport mode. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec esp-group \<name\> pfs \< dh-group\> + +Whether Perfect Forward Secrecy of keys is desired on the +connection's keying channel and defines a Diffie-Hellman group for +PFS: + +- **enable** - Inherit Diffie-Hellman group from IKE group (default). +- **disable** - Disable PFS. +- **\<dh-group\>** - Defines a Diffie-Hellman group for PFS. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec esp-group \<name\> proposal \<number\> encryption \<encryption\> + +Encryption algorithm. Default value is **aes128**. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec esp-group \<name\> proposal \<number\> hash \<hash\> + +Hash algorithm. Default value is **sha1**. + +</div> + +### Global IPsec Settings + +<div class="cfgcmd"> + +set vpn ipsec interface \<name\> + +Interface name to restrict outbound IPsec policies. There is a possibility +to specify multiple interfaces. If an interfaces are not specified, IPsec +policies apply to all interfaces. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec log level \<number\> + +Level of logging. Default value is **0**. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec log subsystem \<name\> + +Subsystem of the daemon. + +</div> + +### Options + +<div class="cfgcmd"> + +set vpn ipsec options disable-route-autoinstall + +Do not automatically install routes to remote +networks. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec options flexvpn + +Allows FlexVPN vendor ID payload (IKEv2 only). Send the Cisco +FlexVPN vendor ID payload (IKEv2 only), which is required in order to make +Cisco brand devices allow negotiating a local traffic selector (from +strongSwan's point of view) that is not the assigned virtual IP address if +such an address is requested by strongSwan. Sending the Cisco FlexVPN +vendor ID prevents the peer from narrowing the initiator's local traffic +selector and allows it to e.g. negotiate a TS of 0.0.0.0/0 == 0.0.0.0/0 +instead. This has been tested with a "tunnel mode ipsec ipv4" Cisco +template but should also work for GRE encapsulation. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec options interface \<name\> + +Interface Name to use. The name of the interface on which +virtual IP addresses should be installed. If not specified the addresses +will be installed on the outbound interface. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec options virtual-ip + +Allows the installation of virtual-ip addresses. + +</div> diff --git a/docs/configuration/vpn/ipsec/md-remoteaccess_ipsec.md b/docs/configuration/vpn/ipsec/md-remoteaccess_ipsec.md new file mode 100644 index 00000000..356ae23a --- /dev/null +++ b/docs/configuration/vpn/ipsec/md-remoteaccess_ipsec.md @@ -0,0 +1,185 @@ +# IPSec IKEv2 Remote Access VPN + +Internet Key Exchange version 2 (IKEv2) is a tunneling protocol, based on IPsec, +that establishes a secure VPN communication between VPN devices, and defines +negotiation and authentication processes for IPsec security associations (SAs). +It is often known as IKEv2/IPSec or IPSec IKEv2 remote-access — or road-warriors +as others call it. + +Key exchange and payload encryption is done using IKE and ESP proposals as known +from IKEv1 but the connections are faster to establish, more reliable, and also +support roaming from IP to IP (called MOBIKE which makes sure your connection +does not drop when changing networks from e.g. WIFI to LTE and back). +Authentication can be achieved with X.509 certificates. + +## Setting up certificates: + +First of all, we need to create a CA root certificate and server certificate +on the server side. + +``` none +vyos@vpn.vyos.net# run generate pki ca install ca_root +Enter private key type: [rsa, dsa, ec] (Default: rsa) +Enter private key bits: (Default: 2048) +Enter country code: (Default: GB) +Enter state: (Default: Some-State) +Enter locality: (Default: Some-City) +Enter organization name: (Default: VyOS) +Enter common name: (Default: vyos.io) +Enter how many days certificate will be valid: (Default: 1825) +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] N +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +[edit] + + +vyos@vpn.vyos.net# comp +[pki ca] ++ ca_root { ++ certificate "MIIDnTCCAoWgAwI…." ++ private { ++ key "MIIEvAIBADANBgkqhkiG9….” + +vyos@vpn.vyos.net# run generate pki certificate sign ca_root install server_cert +Do you already have a certificate request? [y/N] N +Enter private key type: [rsa, dsa, ec] (Default: rsa) +Enter private key bits: (Default: 2048) +Enter country code: (Default: GB) +Enter state: (Default: Some-State) +Enter locality: (Default: Some-City) +Enter organization name: (Default: VyOS) +Enter common name: (Default: vyos.io) vpn.vyos.net +Do you want to configure Subject Alternative Names? [y/N] N +Enter how many days certificate will be valid: (Default: 365) +Enter certificate type: (client, server) (Default: server) +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] N +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. + +vyos@vpn.vyos.net# comp +[pki certificate] ++ server_cert { ++ certificate "MIIDuzCCAqOgAwIBAgIUaSrCPWx………" ++ private { ++ key "MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBK….." ++ } ++ } +``` + +Once the command is completed, it will add the certificate to the configuration +session, to the pki subtree. You can then review the proposed changes and +commit them. + +## Setting up IPSec: + +After the PKI certs are all set up we can start configuring our IPSec/IKE +proposals used for key-exchange end data encryption. The used encryption ciphers +and integrity algorithms vary from operating system to operating system. The +ones used in this example are validated to work on Windows 10. + +``` none +set vpn ipsec esp-group ESP-RW lifetime '3600' +set vpn ipsec esp-group ESP-RW pfs 'disable' +set vpn ipsec esp-group ESP-RW proposal 10 encryption 'aes128gcm128' +set vpn ipsec esp-group ESP-RW proposal 10 hash 'sha256' + +set vpn ipsec ike-group IKE-RW key-exchange 'ikev2' +set vpn ipsec ike-group IKE-RW lifetime '7200' +set vpn ipsec ike-group IKE-RW proposal 10 dh-group '14' +set vpn ipsec ike-group IKE-RW proposal 10 encryption 'aes128gcm128' +set vpn ipsec ike-group IKE-RW proposal 10 hash 'sha256' +``` + +Every connection/remote-access pool we configure also needs a pool where we +can draw our client IP addresses from. We provide one IPv4 and IPv6 pool. +Authorized clients will receive an IPv4 address from the configured IPv4 prefix +and an IPv6 address from the IPv6 prefix. We can also send some DNS nameservers +down to our clients used on their connection. + +``` none +set vpn ipsec remote-access pool ra-rw-ipv4 name-server '192.0.2.1' +set vpn ipsec remote-access pool ra-rw-ipv4 prefix '192.0.2.128/25' + +set vpn ipsec remote-access pool ra-rw-ipv6 name-server '2001:db8:1000::1' +set vpn ipsec remote-access pool ra-rw-ipv6 prefix '2001:db8:2000::/64' +``` + +## Setting up tunnel: + +``` none +set vpn ipsec remote-access connection rw authentication local-id '192.0.2.1' +set vpn ipsec remote-access connection rw authentication server-mode 'x509' +set vpn ipsec remote-access connection rw authentication x509 ca-certificate 'ca_root' +set vpn ipsec remote-access connection rw authentication x509 certificate 'server_cert' +set vpn ipsec remote-access connection rw esp-group 'ESP-RW' +set vpn ipsec remote-access connection rw ike-group 'IKE-RW' +set vpn ipsec remote-access connection rw local-address '192.0.2.1' +set vpn ipsec remote-access connection rw pool 'ra-rw-ipv4' +set vpn ipsec remote-access connection rw pool 'ra-rw-ipv6' +``` + +VyOS also supports two different modes of authentication, local and RADIUS. +To create a new local user named "vyos" with a password of "vyos" use the +following commands. + +``` none +set vpn ipsec remote-access connection rw authentication client-mode 'eap-mschapv2' +set vpn ipsec remote-access connection rw authentication local-users username vyos password 'vyos' +``` + +Some client operating systems like to see the servers certificate. The following +option causes the server to voluntarily send its certificate, even if it wasn't +requested. + +``` none +set vpn ipsec remote-access connection rw authentication always-send-cert +``` + +## Client Configuration + +Most operating systems include native client support for IPsec IKEv2 VPN +connections, and others typically have an app or add-on package which adds the +capability. +This section covers IPsec IKEv2 client configuration for Windows 10. + +VyOS provides a command to generate a connection profile used by Windows clients +that will connect to the "rw" connection on our VyOS server. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Windows expects the server name to be also used in the server's +certificate common name, so it's best to use this DNS name for your VPN +connection. + +</div> + +``` none +vyos@vpn.vyos.net:~$ generate ipsec profile windows-remote-access rw remote vpn.vyos.net + + +==== <snip> ==== +Add-VpnConnection -Name "VyOS IKEv2 VPN" -ServerAddress "vpn.vyos.net" -TunnelType "Ikev2" + +Set-VpnConnectionIPsecConfiguration -ConnectionName "VyOS IKEv2 VPN" -AuthenticationTransformConstants GCMAES128 -CipherTransformConstants +GCMAES128 -EncryptionMethod GCMAES128 -IntegrityCheckMethod SHA256128 -PfsGroup None -DHGroup "Group14" -PassThru -Force +==== </snip> ==== +``` + +Add the commands from Snippet in the Windows side via PowerShell. +Also import the root CA cert to the Windows “Trusted Root Certification +Authorities” and establish the connection. + +## Verification: + +``` none +vyos@vpn.vyos.net:~$ show vpn ipsec remote-access summary + Connection ID Username Protocol State Uptime Tunnel IP Remote Host Remote ID IKE Proposal IPSec Proposal +--------------- ---------- ---------- ------- -------- ----------- ------------- ----------- ------------------------------------------ ------------------ + 5 vyos IKEv2 UP 37s 192.0.2.129 10.0.0.2 10.0.0.2 AES_GCM_16-128/PRF_HMAC_SHA2_256/MODP_2048 ESP:AES_GCM_16-128 +``` diff --git a/docs/configuration/vpn/ipsec/md-site2site_ipsec.md b/docs/configuration/vpn/ipsec/md-site2site_ipsec.md new file mode 100644 index 00000000..451ea1be --- /dev/null +++ b/docs/configuration/vpn/ipsec/md-site2site_ipsec.md @@ -0,0 +1,944 @@ +# IPsec Site-to-Site VPN + +## IPsec Site-to-Site VPN Types + +VyOS supports two types of IPsec VPN: Policy-based IPsec VPN and Route-based +IPsec VPN. + +### Policy-based VPN + +Policy-based VPN is based on static configured policies. Each policy creates +individual IPSec SA. Traffic matches these SAs encrypted and directed to the +remote peer. + +### Route-Based VPN + +Route-based VPN is based on secure traffic passing over Virtual Tunnel +Interfaces (VTIs). This type of IPsec VPNs allows using routing protocols. + +## Configuration Site-to-Site VPN + +### Requirements and Prerequisites for Site-to-Site VPN + +**Negotiated parameters that need to match** + +Phase 1 +- IKE version +- Authentication +- Encryption +- Hashing +- PRF +- Lifetime + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Strongswan recommends to use the same lifetime value on both peers + +</div> + +Phase 2 +- Encryption +- Hashing +- PFS +- Mode (tunnel or transport) +- Lifetime + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Strongswan recommends to use the same lifetime value on both peers + +</div> + +- Remote and Local networks in SA must be compatible on both peers + +### Configuration Steps for Site-to-Site VPN + +The next example shows the configuration one of the router participating in +IPsec VPN. + +Tunnel information: +- Phase 1: + - encryption: AES256 + - hash: SHA256 + - PRF: SHA256 + - DH: 14 + - lifetime: 28800 + +- Phase 2: + - IPsec mode: tunnel + - encryption: AES256 + - hash: SHA256 + - PFS: inherited from DH Phase 1 + - lifetime: 3600 + +- If Policy based VPN is used + - Remote network is 192.168.50.0/24. Local network is 192.168.10.0/24 + +- If Route based VPN is used + - IP of the VTI interface is 10.0.0.1/30 + +<div class="note"> + +<div class="title"> + +Note + +</div> + +We do not recommend using policy-based vpn and route-based vpn configurations to the same peer. + +</div> + +**1. Configure ike-group (IKE Phase 1)** + +``` none +set vpn ipsec ike-group IKE close-action 'start' +set vpn ipsec ike-group IKE key-exchange 'ikev1' +set vpn ipsec ike-group IKE lifetime '28800' +set vpn ipsec ike-group IKE proposal 10 dh-group '14' +set vpn ipsec ike-group IKE proposal 10 encryption 'aes256' +set vpn ipsec ike-group IKE proposal 10 hash 'sha256' +set vpn ipsec ike-group IKE proposal 10 prf 'prfsha256' +``` + +**2. Configure ESP-group (IKE Phase 2)** + +``` none +set vpn ipsec esp-group ESP lifetime '3600' +set vpn ipsec esp-group ESP mode 'tunnel' +set vpn ipsec esp-group ESP pfs 'enable' +set vpn ipsec esp-group ESP proposal 10 encryption 'aes256' +set vpn ipsec esp-group ESP proposal 10 hash 'sha256' +``` + +**3. Specify interface facing to the protected destination.** + +``` none +set vpn ipsec interface eth0 +``` + +**4. Configure PSK keys and authentication ids for this key if authentication type is PSK** + +``` none +set vpn ipsec authentication psk PSK-KEY id '192.168.0.2' +set vpn ipsec authentication psk PSK-KEY id '192.168.5.2' +set vpn ipsec authentication psk PSK-KEY secret 'vyos' +``` + +To set base64 secret encode plaintext password to base64 and set secret-type + +``` none +echo -n "vyos" | base64 +dnlvcw== +``` + +``` none +set vpn ipsec authentication psk PSK-KEY secret 'dnlvcw==' +set vpn ipsec authentication psk PSK-KEY secret-type base64 +``` + +**5. Configure peer and apply IKE-group and esp-group to peer.** + +``` none +set vpn ipsec site-to-site peer PEER1 authentication local-id '192.168.0.2' +set vpn ipsec site-to-site peer PEER1 authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer PEER1 authentication remote-id '192.168.5.2' +set vpn ipsec site-to-site peer PEER1 connection-type 'initiate' +set vpn ipsec site-to-site peer PEER1 default-esp-group 'ESP' +set vpn ipsec site-to-site peer PEER1 ike-group 'IKE' +set vpn ipsec site-to-site peer PEER1 local-address '192.168.0.2' +set vpn ipsec site-to-site peer PEER1 remote-address '192.168.5.2' + +Peer selects the key from step 4 according to local-id/remote-id pair. +``` + +**6. Depends to vpn type (route-based vpn or policy-based vpn).** + +> **6.1 For Policy-based VPN configure SAs using tunnel command specifying remote and local networks.** +> +> > ``` none +> > set vpn ipsec site-to-site peer PEER1 tunnel 1 local prefix '192.168.10.0/24' +> > set vpn ipsec site-to-site peer PEER1 tunnel 1 remote prefix '192.168.50.0/24' +> > ``` +> +> **6.2 For Route-based VPN create VTI interface, set IP address to this interface and bind this interface to the vpn peer.** +> +> > ``` none +> > set interfaces vti vti1 address 10.0.0.1/30 +> > set vpn ipsec site-to-site peer PEER1 vti bind vti1 +> > set vpn ipsec options disable-route-autoinstall +> > ``` +> > +> > Create routing between local networks via VTI interface using dynamic or +> > static routing. +> > +> > ``` none +> > set protocol static route 192.168.50.0/24 next-hop 10.0.0.2 +> > ``` + +### Initiator and Responder Connection Types + +In Site-to-Site IPsec VPN it is recommended that one peer should be an +initiator and the other - the responder. The initiator actively establishes +the VPN tunnel. The responder passively waits for the remote peer to +establish the VPN tunnel. Depends on selected role it is recommended +select proper values for close-action and DPD action. + +The result of wrong value selection can be unstable work of the VPN. +- Duplicate CHILD SA creation. +- None of the VPN sides initiates the tunnel establishment. + +Below flow-chart could be a quick reference for the close-action +combination depending on how the peer is configured. + +<figure> +<img src="/_static/images/IPSec_close_action_settings.webp" /> +</figure> + +Similar combinations are applicable for the dead-peer-detection. + +### Detailed Configuration Commands + +#### PSK Key Authentication + +<div class="cfgcmd"> + +set vpn ipsec authentication psk \<name\> dhcp-interface + +ID for authentication generated from DHCP address +dynamically. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec authentication psk id \<id\> + +static ID's for authentication. In general local and remote +address `<x.x.x.x>`, `<h:h:h:h:h:h:h:h>` or `%any`. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec authentication psk secret \<secret\> + +A predefined shared secret used in configured mode +`pre-shared-secret`. Base64-encoded secrets are allowed if +<span class="title-ref">secret-type base64</span> is configured. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec authentication psk secret-type \<type\> + +Specifies the secret type: + +- **plaintext** - Plain text type (default value). +- **base64** - Base64 type. + +</div> + +#### Peer Configuration + +##### Peer Authentication Commands + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> authentication mode \<mode\> + +Mode for authentication between VyOS and remote peer: + +- **pre-shared-secret** - Use predefined shared secret phrase. +- **rsa** - Use simple shared RSA key. +- **x509** - Use certificates infrastructure for authentication. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> authentication local-id \<id\> + +ID for the local VyOS router. If defined, during the authentication +it will be send to remote peer. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> authentication remote-id \<id\> + +ID for remote peer, instead of using peer name or +address. Useful in case if the remote peer is behind NAT +or if `mode x509` is used. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> authentication rsa local-key \<key\> + +Name of PKI key-pair with local private key. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> authentication rsa remote-key \<key\> + +Name of PKI key-pair with remote public key. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> authentication rsa passphrase \<passphrase\> + +Local private key passphrase. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> authentication use-x509-id \<id\> + +Use local ID from x509 certificate. Cannot be used when +`id` is defined. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> authentication x509 ca-certificate \<name\> + +Name of CA certificate in PKI configuration. Using for authenticating +remote peer in x509 mode. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> authentication x509 certificate \<name\> + +Name of certificate in PKI configuration, which will be used +for authenticating local router on remote peer. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec authentication x509 passphrase \<passphrase\> + +Private key passphrase, if needed. + +</div> + +##### Global Peer Configuration Commands + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> connection-type \<type\> + +Operational mode defines how to handle this connection process. + +- **initiate** - does initial connection to remote peer immediately + after configuring and after boot. In this mode the connection will + not be restarted in case of disconnection, therefore should be used + only together with DPD or another session tracking methods. +- **respond** - does not try to initiate a connection to a remote + peer. In this mode, the IPsec session will be established only + after initiation from a remote peer. Could be useful when there + is no direct connectivity to the peer due to firewall or NAT in + the middle of the local and remote side. +- **none** - loads the connection only, which then can be manually + initiated or used as a responder configuration. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> default-esp-group \<name\> + +Name of ESP group to use by default for traffic encryption. +Might be overwritten by individual settings for tunnel or VTI +interface binding. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> description \<description\> + +Description for this peer. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> dhcp-interface \<interface\> + +Specify the interface which IP address, received from DHCP for IPSec +connection with this peer, will be used as `local-address`. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> force-udp-encapsulation + +Force encapsulation of ESP into UDP datagrams. Useful in case if +between local and remote side is firewall or NAT, which not +allows passing plain ESP packets between them. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> ike-group \<name\> + +Name of IKE group to use for key exchanges. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> local-address \<address\> + +Local IP address for IPsec connection with this peer. +If defined `any`, then an IP address which configured on interface with +default route will be used. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> remote-address \<address\> + +Remote IP address or hostname for IPsec connection. IPv4 or IPv6 +address is used when a peer has a public static IP address. Hostname +is a DNS name which could be used when a peer has a public IP +address and DNS name, but an IP address could be changed from time +to time. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> replay-window \<size\> + +IPsec replay window to configure for CHILD_SAs +(default: 32), a value of 0 disables IPsec replay protection. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> virtual-address \<address\> + +Defines a virtual IP address which is requested by the initiator and +one or several IPv4 and/or IPv6 addresses are assigned from multiple +pools by the responder. The wildcard addresses 0.0.0.0 and :: +request an arbitrary address, specific addresses may be defined. + +</div> + +##### CHILD SAs Configuration Commands + +###### Policy-Based CHILD SAs Configuration Commands + +Every configured tunnel under peer configuration is a new CHILD SA. + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> tunnel \<number\> disable + +Disable this tunnel. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> tunnel \<number\> esp-group \<name\> + +Specify ESP group for this CHILD SA. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> tunnel \<number\> priority \<number\> + +Priority for policy-based IPsec VPN tunnels (lowest value more +preferable). + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> tunnel \<number\> protocol \<name\> + +Define the protocol for match traffic, which should be encrypted and +send to this peer. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> tunnel \<number\> local prefix \<network\> + +IP network at the local side. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> tunnel \<number\> local port \<number\> + +Local port number. Have effect only when used together with +`prefix`. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> tunnel \<number\> remote prefix \<network\> + +IP network at the remote side. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> tunnel \<number\> remote port \<number\> + +Remote port number. Have effect only when used together with +`prefix`. + +</div> + +###### Route-Based CHILD SAs Configuration Commands + +To configure route-based VPN it is enough to create vti interface and +bind it to the peer. Any traffic, which will be send to VTI interface +will be encrypted and send to this peer. Using VTI makes IPsec +configuration much flexible and easier in complex situation, and +allows to dynamically add/delete remote networks, reachable via a +peer, as in this mode router don't need to create additional SA/policy +for each remote network. + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +When using site-to-site IPsec with VTI interfaces, +be sure to disable route autoinstall. + +</div> + +``` none +set vpn ipsec options disable-route-autoinstall +``` + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> vti bind \<interface\> + +VTI interface to bind to this peer. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> vti esp-group \<name\> + +ESP group for encrypt traffic, passed this VTI interface. + +</div> + +Traffic-selectors parameters for traffic that should pass via vti +interface. + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> vti traffic-selector local prefix \<network\> + +Local prefix for interesting traffic. + +</div> + +<div class="cfgcmd"> + +set vpn ipsec site-to-site peer \<name\> vti traffic-selector remote prefix \<network\> + +Remote prefix for interesting traffic. + +</div> + +### IPsec Op-mode Commands + +<div class="opcmd"> + +show vpn ike sa + +Shows active IKE SAs information. + +</div> + +<div class="opcmd"> + +show vpn ike secrets + +Shows configured authentication keys. + +</div> + +<div class="opcmd"> + +show vpn ike status + +Shows Strongswan daemon status. + +</div> + +<div class="opcmd"> + +show vpn ipsec connections + +Shows summary status of all configured IKE and IPsec SAs. + +</div> + +<div class="opcmd"> + +show vpn ipsec sa \[detail\] + +Shows active IPsec SAs information. + +</div> + +<div class="opcmd"> + +show vpn ipsec status + +Shows status of IPsec process. + +</div> + +<div class="opcmd"> + +show vpn ipsec policy + +Shows the in-kernel crypto policies. + +</div> + +<div class="opcmd"> + +show vpn ipsec state + +Shows the in-kernel crypto state. + +</div> + +<div class="opcmd"> + +show log ipsec + +Shows IPsec logs. + +</div> + +<div class="opcmd"> + +reset vpn ipsec site-to-site all + +Clear all ipsec connection and reinitiate them if VyOS is configured +as initiator. + +</div> + +<div class="opcmd"> + +reset vpn ipsec site-to-site peer \<name\> + +Clear all peer IKE SAs with IPsec SAs and reinitiate them if VyOS is +configured as initiator. + +</div> + +<div class="opcmd"> + +reset vpn ipsec site-to-site peer \<name\> tunnel \<number\> + +Clear scpecific IPsec SA and reinitiate it if VyOS is configured as +initiator. + +</div> + +<div class="opcmd"> + +reset vpn ipsec site-to-site peer \<name\> vti \<number\> + +Clear IPsec SA which is map to vti interface of this peer and +reinitiate it if VyOS is configured as initiator. + +</div> + +<div class="opcmd"> + +restart ipsec + +Restart Strongswan daemon. + +</div> + +## Examples: + +### Policy-Based VPN Example + +**PEER1:** + +- WAN interface on <span class="title-ref">eth0</span> +- <span class="title-ref">eth0</span> interface IP: <span class="title-ref">10.0.1.2/30</span> +- <span class="title-ref">dum0</span> interface IP: <span class="title-ref">192.168.0.1/24</span> (for testing purposes) +- Initiator + +**PEER2:** + +- WAN interface on <span class="title-ref">eth0</span> +- <span class="title-ref">eth0</span> interface IP: <span class="title-ref">10.0.2.2/30</span> +- <span class="title-ref">dum0</span> interface IP: <span class="title-ref">192.168.1.0/24</span> (for testing purposes) +- Responder + +``` none +# PEER1 +set interfaces dummy dum0 address '192.168.0.1/32' +set interfaces ethernet eth0 address '10.0.1.2/30' +set protocols static route 0.0.0.0/0 next-hop 10.0.1.1 +set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' +set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' +set vpn ipsec authentication psk AUTH-PSK secret 'test' +set vpn ipsec esp-group ESP-GRPOUP lifetime '3600' +set vpn ipsec esp-group ESP-GRPOUP proposal 10 encryption 'aes256' +set vpn ipsec esp-group ESP-GRPOUP proposal 10 hash 'sha1' +set vpn ipsec ike-group IKE-GROUP close-action 'start' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'restart' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '30' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection timeout '120' +set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev1' +set vpn ipsec ike-group IKE-GROUP lifetime '28800' +set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' +set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256' +set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' +set vpn ipsec interface 'eth0' +set vpn ipsec site-to-site peer PEER2 authentication local-id '10.0.1.2' +set vpn ipsec site-to-site peer PEER2 authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer PEER2 authentication remote-id '10.0.2.2' +set vpn ipsec site-to-site peer PEER2 connection-type 'initiate' +set vpn ipsec site-to-site peer PEER2 default-esp-group 'ESP-GRPOUP' +set vpn ipsec site-to-site peer PEER2 ike-group 'IKE-GROUP' +set vpn ipsec site-to-site peer PEER2 local-address '10.0.1.2' +set vpn ipsec site-to-site peer PEER2 remote-address '10.0.2.2' +set vpn ipsec site-to-site peer PEER2 tunnel 0 local prefix '192.168.0.0/24' +set vpn ipsec site-to-site peer PEER2 tunnel 0 remote prefix '192.168.1.0/24' + + +# PEER2 +set interfaces dummy dum0 address '192.168.1.1/32' +set interfaces ethernet eth0 address '10.0.2.2/30' +set protocols static route 0.0.0.0/0 next-hop 10.0.2.1 +set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' +set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' +set vpn ipsec authentication psk AUTH-PSK secret 'test' +set vpn ipsec esp-group ESP-GRPOUP lifetime '3600' +set vpn ipsec esp-group ESP-GRPOUP proposal 10 encryption 'aes256' +set vpn ipsec esp-group ESP-GRPOUP proposal 10 hash 'sha1' +set vpn ipsec ike-group IKE-GROUP close-action 'none' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'clear' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '30' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection timeout '120' +set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev1' +set vpn ipsec ike-group IKE-GROUP lifetime '28800' +set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' +set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256' +set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' +set vpn ipsec interface 'eth0' +set vpn ipsec site-to-site peer PEER1 authentication local-id '10.0.2.2' +set vpn ipsec site-to-site peer PEER1 authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer PEER1 authentication remote-id '10.0.1.2' +set vpn ipsec site-to-site peer PEER1 connection-type 'respond' +set vpn ipsec site-to-site peer PEER1 default-esp-group 'ESP-GRPOUP' +set vpn ipsec site-to-site peer PEER1 ike-group 'IKE-GROUP' +set vpn ipsec site-to-site peer PEER1 local-address '10.0.2.2' +set vpn ipsec site-to-site peer PEER1 remote-address '10.0.1.2' +set vpn ipsec site-to-site peer PEER1 tunnel 0 local prefix '192.168.1.0/24' +set vpn ipsec site-to-site peer PEER1 tunnel 0 remote prefix '192.168.0.0/24' +``` + +Show status of policy-based IPsec VPN setup: + +``` none +vyos@PEER2:~$ show vpn ike sa +Peer ID / IP Local ID / IP +------------ ------------- +10.0.1.2 10.0.1.2 10.0.2.2 10.0.2.2 + + State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time + ----- ------ ------- ---- --------- ----- ------ ------ + up IKEv1 AES_CBC_256 HMAC_SHA1_96 MODP_2048 no 1254 25633 + + +vyos@srv-gw0:~$ show vpn ipsec sa +Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal +-------------- ------- -------- -------------- ---------------- ---------------- ----------- ---------------------------------- +PEER1-tunnel-0 up 20m42s 0B/0B 0/0 10.0.1.2 10.0.1.2 AES_CBC_256/HMAC_SHA1_96/MODP_2048 + +vyos@PEER2:~$ show vpn ipsec connections +Connection State Type Remote address Local TS Remote TS Local id Remote id Proposal +-------------- ------- ------ ---------------- -------------- -------------- ---------- ----------- ---------------------------------- +PEER1 up IKEv1 10.0.1.2 - - 10.0.2.2 10.0.1.2 AES_CBC/256/HMAC_SHA1_96/MODP_2048 +PEER1-tunnel-0 up IPsec 10.0.1.2 192.168.1.0/24 192.168.0.0/24 10.0.2.2 10.0.1.2 AES_CBC/256/HMAC_SHA1_96/MODP_2048 +``` + +If there is SNAT rules on eth0, need to add exclude rule + +``` none +# PEER1 side +set nat source rule 10 destination address '192.168.1.0/24' +set nat source rule 10 'exclude' +set nat source rule 10 outbound-interface name 'eth0' +set nat source rule 10 source address '192.168.0.0/24' + +# PEER2 side +set nat source rule 10 destination address '192.168.0.0/24' +set nat source rule 10 'exclude' +set nat source rule 10 outbound-interface name 'eth0' +set nat source rule 10 source address '192.168.1.0/24' +``` + +### Route-Based VPN Example + +**PEER1:** + +- WAN interface on <span class="title-ref">eth0</span> +- <span class="title-ref">eth0</span> interface IP: <span class="title-ref">10.0.1.2/30</span> +- 'vti0' interface IP: <span class="title-ref">10.100.100.1/30</span> +- <span class="title-ref">dum0</span> interface IP: <span class="title-ref">192.168.0.1/24</span> (for testing purposes) +- Role: Initiator + +**PEER2:** + +- WAN interface on <span class="title-ref">eth0</span> +- <span class="title-ref">eth0</span> interface IP: <span class="title-ref">10.0.2.2/30</span> +- 'vti0' interface IP: <span class="title-ref">10.100.100.2/30</span> +- <span class="title-ref">dum0</span> interface IP: <span class="title-ref">192.168.1.0/24</span> (for testing purposes) +- Role: Responder + +``` none +# PEER1 +set interfaces dummy dum0 address '192.168.0.1/32' +set interfaces ethernet eth0 address '10.0.1.2/30' +set interfaces vti vti0 address '10.100.100.1/30' +set protocols static route 0.0.0.0/0 next-hop 10.0.1.1 +set protocols static route 192.168.1.0/24 next-hop 10.100.100.2 +set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' +set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' +set vpn ipsec authentication psk AUTH-PSK secret 'test' +set vpn ipsec esp-group ESP-GRPOUP lifetime '3600' +set vpn ipsec esp-group ESP-GRPOUP proposal 10 encryption 'aes256' +set vpn ipsec esp-group ESP-GRPOUP proposal 10 hash 'sha1' +set vpn ipsec ike-group IKE-GROUP close-action 'start' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'restart' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '30' +set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev2' +set vpn ipsec ike-group IKE-GROUP lifetime '28800' +set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' +set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256' +set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' +set vpn ipsec interface 'eth0' +set vpn ipsec options disable-route-autoinstall +set vpn ipsec site-to-site peer PEER2 authentication local-id '10.0.1.2' +set vpn ipsec site-to-site peer PEER2 authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer PEER2 authentication remote-id '10.0.2.2' +set vpn ipsec site-to-site peer PEER2 connection-type 'initiate' +set vpn ipsec site-to-site peer PEER2 default-esp-group 'ESP-GRPOUP' +set vpn ipsec site-to-site peer PEER2 ike-group 'IKE-GROUP' +set vpn ipsec site-to-site peer PEER2 local-address '10.0.1.2' +set vpn ipsec site-to-site peer PEER2 remote-address '10.0.2.2' +set vpn ipsec site-to-site peer PEER2 vti bind 'vti0' + + +# PEER2 +set interfaces dummy dum0 address '192.168.1.1/32' +set interfaces ethernet eth0 address '10.0.2.2/30' +set interfaces vti vti0 address '10.100.100.2/30' +set protocols static route 0.0.0.0/0 next-hop 10.0.2.1 +set protocols static route 192.168.0.0/24 next-hop 10.100.100.1 +set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' +set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' +set vpn ipsec authentication psk AUTH-PSK secret 'test' +set vpn ipsec esp-group ESP-GRPOUP lifetime '3600' +set vpn ipsec esp-group ESP-GRPOUP proposal 10 encryption 'aes256' +set vpn ipsec esp-group ESP-GRPOUP proposal 10 hash 'sha1' +set vpn ipsec ike-group IKE-GROUP close-action 'none' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'clear' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '30' +set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev2' +set vpn ipsec ike-group IKE-GROUP lifetime '28800' +set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' +set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256' +set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' +set vpn ipsec interface 'eth0' +set vpn ipsec options disable-route-autoinstall +set vpn ipsec site-to-site peer PEER1 authentication local-id '10.0.2.2' +set vpn ipsec site-to-site peer PEER1 authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer PEER1 authentication remote-id '10.0.1.2' +set vpn ipsec site-to-site peer PEER1 connection-type 'respond' +set vpn ipsec site-to-site peer PEER1 default-esp-group 'ESP-GRPOUP' +set vpn ipsec site-to-site peer PEER1 ike-group 'IKE-GROUP' +set vpn ipsec site-to-site peer PEER1 local-address '10.0.2.2' +set vpn ipsec site-to-site peer PEER1 remote-address '10.0.1.2' +set vpn ipsec site-to-site peer PEER1 vti bind 'vti0' +``` + +Show status of route-based IPsec VPN setup: + +``` none +vyos@PEER2:~$ show vpn ike sa +Peer ID / IP Local ID / IP +------------ ------------- +10.0.1.2 10.0.1.2 10.0.2.2 10.0.2.2 + + State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time + ----- ------ ------- ---- --------- ----- ------ ------ + up IKEv2 AES_CBC_256 HMAC_SHA1_96 MODP_2048 no 404 27650 + +vyos@PEER2:~$ show vpn ipsec sa +Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal +------------ ------- -------- -------------- ---------------- ---------------- ----------- ---------------------------------- +PEER1-vti up 3m28s 0B/0B 0/0 10.0.1.2 10.0.1.2 AES_CBC_256/HMAC_SHA1_96/MODP_2048 + +vyos@PEER2:~$ show vpn ipsec connections +Connection State Type Remote address Local TS Remote TS Local id Remote id Proposal +------------ ------- ------ ---------------- ---------- ----------- ---------- ----------- ---------------------------------- +PEER1 up IKEv2 10.0.1.2 - - 10.0.2.2 10.0.1.2 AES_CBC/256/HMAC_SHA1_96/MODP_2048 +PEER1-vti up IPsec 10.0.1.2 0.0.0.0/0 0.0.0.0/0 10.0.2.2 10.0.1.2 AES_CBC/256/HMAC_SHA1_96/MODP_2048 + ::/0 ::/0 +``` diff --git a/docs/configuration/vpn/ipsec/md-troubleshooting_ipsec.md b/docs/configuration/vpn/ipsec/md-troubleshooting_ipsec.md new file mode 100644 index 00000000..14161e7f --- /dev/null +++ b/docs/configuration/vpn/ipsec/md-troubleshooting_ipsec.md @@ -0,0 +1,303 @@ +# Troubleshooting Site-to-Site VPN IPsec + +## Introduction + +This document describes the methodology to monitor and troubleshoot +Site-to-Site VPN IPsec. + +Steps for troubleshooting problems with Site-to-Site VPN IPsec: +1. Ping the remote site through the tunnel using the source and + destination IPs included in the policy. +2. Check connectivity between the routers using the ping command + (if ICMP traffic is allowed). +3. Check the IKE SAs' statuses. +4. Check the IPsec SAs' statuses. +5. Check logs to view debug messages. + +## Checking IKE SA Status + +The next command shows IKE SAs' statuses. + +``` none +vyos@vyos:~$ show vpn ike sa + +Peer ID / IP Local ID / IP +------------ ------------- +192.168.1.2 192.168.1.2 192.168.0.1 192.168.0.1 + + State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time + ----- ------ ------- ---- --------- ----- ------ ------ + up IKEv2 AES_CBC_128 HMAC_SHA1_96 MODP_2048 no 162 27023 +``` + +This command shows the next information: +- IKE SA status. +- Selected IKE version. +- Selected Encryption, Hash and Diffie-Hellman Group. +- NAT-T. +- ID and IP of both peers. +- A-Time: established time, L-Time: time for next rekeying. + +## IPsec SA (CHILD SA) Status + +The next commands show IPsec SAs' statuses. + +``` none +vyos@vyos:~$ show vpn ipsec sa +Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal +------------- ------- -------- -------------- ---------------- ---------------- ----------- ---------------------------------- +PEER-tunnel-1 up 16m30s 168B/168B 2/2 192.168.1.2 192.168.1.2 AES_CBC_128/HMAC_SHA1_96/MODP_2048 +``` + +``` none +vyos@vyos:~$ show vpn ipsec sa detail +PEER: #1, ESTABLISHED, IKEv2, 101275ac719d5a1b_i* 68ea4ec3bed3bf0c_r + local '192.168.0.1' @ 192.168.0.1[4500] + remote '192.168.1.2' @ 192.168.1.2[4500] + AES_CBC-128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 + established 4054s ago, rekeying in 23131s + PEER-tunnel-1: #2, reqid 1, INSTALLED, TUNNEL, ESP:AES_CBC-128/HMAC_SHA1_96/MODP_2048 + installed 1065s ago, rekeying in 1998s, expires in 2535s + in c5821882, 168 bytes, 2 packets, 81s ago + out c433406a, 168 bytes, 2 packets, 81s ago + local 10.0.0.0/24 + remote 10.0.1.0/24 +``` + +These commands show the next information: +- IPsec SA status. +- Uptime and time for the next rekeing. +- Amount of transferred data. +- Remote and local ID and IP. +- Selected Encryption, Hash and Diffie-Hellman Group. +- Mode (tunnel or transport). +- Remote and local prefixes which are use for policy. + +There is a possibility to view the summarized information of SAs' status + +``` none +vyos@vyos:~$ show vpn ipsec connections +Connection State Type Remote address Local TS Remote TS Local id Remote id Proposal +------------- ------- ------ ---------------- ----------- ----------- ----------- ----------- ---------------------------------- +PEER up IKEv2 192.168.1.2 - - 192.168.0.1 192.168.1.2 AES_CBC/128/HMAC_SHA1_96/MODP_2048 +PEER-tunnel-1 up IPsec 192.168.1.2 10.0.0.0/24 10.0.1.0/24 192.168.0.1 192.168.1.2 AES_CBC/128/HMAC_SHA1_96/MODP_2048 +``` + +## Viewing Logs for Debugging + +If IKE SAs or IPsec SAs are down, need to debug IPsec connectivity +using logs `show log ipsec` + +The next example of the successful IPsec connection initialization. + +``` none +vyos@vyos:~$ show log ipsec +Jun 20 14:29:47 charon[2428]: 02[NET] <PEER|1> received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes) +Jun 20 14:29:47 charon[2428]: 02[ENC] <PEER|1> parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ] +Jun 20 14:29:47 charon-systemd[2428]: received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes) +Jun 20 14:29:47 charon[2428]: 02[CFG] <PEER|1> selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 +Jun 20 14:29:47 charon-systemd[2428]: parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ] +Jun 20 14:29:47 charon-systemd[2428]: selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 +Jun 20 14:29:47 charon[2428]: 02[IKE] <PEER|1> authentication of '192.168.0.1' (myself) with pre-shared key +Jun 20 14:29:47 charon-systemd[2428]: authentication of '192.168.0.1' (myself) with pre-shared key +Jun 20 14:29:47 charon[2428]: 02[IKE] <PEER|1> establishing CHILD_SA PEER-tunnel-1{1} +Jun 20 14:29:47 charon-systemd[2428]: establishing CHILD_SA PEER-tunnel-1{1} +Jun 20 14:29:47 charon[2428]: 02[ENC] <PEER|1> generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ] +Jun 20 14:29:47 charon-systemd[2428]: generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ] +Jun 20 14:29:47 charon[2428]: 02[NET] <PEER|1> sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes) +Jun 20 14:29:47 charon-systemd[2428]: sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes) +Jun 20 14:29:47 charon[2428]: 13[NET] <PEER|1> received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (220 bytes) +Jun 20 14:29:47 charon[2428]: 13[ENC] <PEER|1> parsed IKE_AUTH response 1 [ IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) ] +Jun 20 14:29:47 charon-systemd[2428]: received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (220 bytes) +Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> authentication of '192.168.1.2' with pre-shared key successful +Jun 20 14:29:47 charon-systemd[2428]: parsed IKE_AUTH response 1 [ IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) ] +Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> peer supports MOBIKE +Jun 20 14:29:47 charon-systemd[2428]: authentication of '192.168.1.2' with pre-shared key successful +Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2] +Jun 20 14:29:47 charon-systemd[2428]: peer supports MOBIKE +Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> scheduling rekeying in 27703s +Jun 20 14:29:47 charon-systemd[2428]: IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2] +Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> maximum IKE_SA lifetime 30583s +Jun 20 14:29:47 charon-systemd[2428]: scheduling rekeying in 27703s +Jun 20 14:29:47 charon[2428]: 13[CFG] <PEER|1> selected proposal: ESP:AES_CBC_128/HMAC_SHA1_96/NO_EXT_SEQ +Jun 20 14:29:47 charon-systemd[2428]: maximum IKE_SA lifetime 30583s +Jun 20 14:29:47 charon-systemd[2428]: selected proposal: ESP:AES_CBC_128/HMAC_SHA1_96/NO_EXT_SEQ +Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> CHILD_SA PEER-tunnel-1{1} established with SPIs cb94fb3f_i ca99c8a9_o and TS 10.0.0.0/24 === 10.0.1.0/24 +Jun 20 14:29:47 charon-systemd[2428]: CHILD_SA PEER-tunnel-1{1} established with SPIs cb94fb3f_i ca99c8a9_o and TS 10.0.0.0/24 === 10.0.1.0/24 +``` + +## Troubleshooting Examples + +### IKE PROPOSAL are Different + +In this situation, IKE SAs can be down or not active. + +``` none +vyos@vyos:~$ show vpn ike sa +``` + +The problem is in IKE phase (Phase 1). The next step is checking debug logs. + +Responder Side: + +``` none +Jun 23 07:36:33 charon[2440]: 01[CFG] <1> received proposals: IKE:AES_CBC_256/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 +Jun 23 07:36:33 charon-systemd[2440]: received proposals: IKE:AES_CBC_256/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 +Jun 23 07:36:33 charon[2440]: 01[CFG] <1> configured proposals: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 +Jun 23 07:36:33 charon-systemd[2440]: configured proposals: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 +Jun 23 07:36:33 charon[2440]: 01[IKE] <1> received proposals unacceptable +Jun 23 07:36:33 charon-systemd[2440]: received proposals unacceptable +Jun 23 07:36:33 charon[2440]: 01[ENC] <1> generating IKE_SA_INIT response 0 [ N(NO_PROP) ] +``` + +Initiator side: + +``` none +Jun 23 07:36:32 charon-systemd[2444]: parsed IKE_SA_INIT response 0 [ N(NO_PROP) ] +Jun 23 07:36:32 charon[2444]: 14[IKE] <PEER|1> received NO_PROPOSAL_CHOSEN notify error +Jun 23 07:36:32 charon-systemd[2444]: received NO_PROPOSAL_CHOSEN notify error +``` + +The notification **NO_PROPOSAL_CHOSEN** means that the proposal mismatch. +On the Responder side there is concrete information where is mismatch. +Encryption **AES_CBC_128** is configured in IKE policy on the responder +but **AES_CBC_256** is configured on the initiator side. + +### PSK Secret Mismatch + +In this situation, IKE SAs can be down or not active. + +``` none +vyos@vyos:~$ show vpn ike sa +``` + +The problem is in IKE phase (Phase 1). The next step is checking debug logs. + +Responder: + +``` none +Jun 23 08:07:26 charon-systemd[2440]: tried 1 shared key for '192.168.1.2' - '192.168.0.1', but MAC mismatched +Jun 23 08:07:26 charon[2440]: 13[ENC] <PEER|3> generating IKE_AUTH response 1 [ N(AUTH_FAILED) ] +``` + +Initiator side: + +``` none +Jun 23 08:07:24 charon[2436]: 12[ENC] <PEER|1> parsed IKE_AUTH response 1 [ N(AUTH_FAILED) ] +Jun 23 08:07:24 charon-systemd[2436]: parsed IKE_AUTH response 1 [ N(AUTH_FAILED) ] +Jun 23 08:07:24 charon[2436]: 12[IKE] <PEER|1> received AUTHENTICATION_FAILED notify error +Jun 23 08:07:24 charon-systemd[2436]: received AUTHENTICATION_FAILED notify error +``` + +The notification **AUTHENTICATION_FAILED** means that the authentication +is failed. There is a reason to check PSK on both side. + +### ESP Proposal Mismatch + +The output of **show** commands shows us that IKE SA is established but +IPSec SA is not. + +``` none +vyos@vyos:~$ show vpn ike sa +Peer ID / IP Local ID / IP +------------ ------------- +192.168.1.2 192.168.1.2 192.168.0.1 192.168.0.1 + + State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time + ----- ------ ------- ---- --------- ----- ------ ------ + up IKEv2 AES_CBC_128 HMAC_SHA1_96 MODP_2048 no 158 26817 +``` + +``` none +vyos@vyos:~$ show vpn ipsec sa +Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal +------------ ------- -------- -------------- ---------------- ---------------- ----------- ---------- +``` + +The next step is checking debug logs. + +Initiator side: + +``` none +Jun 23 08:16:10 charon[3789]: 13[NET] <PEER|1> received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes) +Jun 23 08:16:10 charon[3789]: 13[ENC] <PEER|1> parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ] +Jun 23 08:16:10 charon-systemd[3789]: received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes) +Jun 23 08:16:10 charon[3789]: 13[CFG] <PEER|1> selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 +Jun 23 08:16:10 charon-systemd[3789]: parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ] +Jun 23 08:16:10 charon-systemd[3789]: selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 +Jun 23 08:16:10 charon[3789]: 13[IKE] <PEER|1> authentication of '192.168.0.1' (myself) with pre-shared key +Jun 23 08:16:10 charon-systemd[3789]: authentication of '192.168.0.1' (myself) with pre-shared key +Jun 23 08:16:10 charon[3789]: 13[IKE] <PEER|1> establishing CHILD_SA PEER-tunnel-1{1} +Jun 23 08:16:10 charon-systemd[3789]: establishing CHILD_SA PEER-tunnel-1{1} +Jun 23 08:16:10 charon[3789]: 13[ENC] <PEER|1> generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ] +Jun 23 08:16:10 charon-systemd[3789]: generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ] +Jun 23 08:16:10 charon[3789]: 13[NET] <PEER|1> sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes) +Jun 23 08:16:10 charon-systemd[3789]: sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes) +Jun 23 08:16:10 charon[3789]: 09[NET] <PEER|1> received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (140 bytes) +Jun 23 08:16:10 charon-systemd[3789]: received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (140 bytes) +Jun 23 08:16:10 charon[3789]: 09[ENC] <PEER|1> parsed IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(NO_PROP) ] +Jun 23 08:16:10 charon-systemd[3789]: parsed IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(NO_PROP) ] +Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> authentication of '192.168.1.2' with pre-shared key successful +Jun 23 08:16:10 charon-systemd[3789]: authentication of '192.168.1.2' with pre-shared key successful +Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> peer supports MOBIKE +Jun 23 08:16:10 charon-systemd[3789]: peer supports MOBIKE +Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2] +Jun 23 08:16:10 charon-systemd[3789]: IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2] +Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> scheduling rekeying in 26975s +Jun 23 08:16:10 charon-systemd[3789]: scheduling rekeying in 26975s +Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> maximum IKE_SA lifetime 29855s +Jun 23 08:16:10 charon-systemd[3789]: maximum IKE_SA lifetime 29855s +Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> received NO_PROPOSAL_CHOSEN notify, no CHILD_SA built +Jun 23 08:16:10 charon-systemd[3789]: received NO_PROPOSAL_CHOSEN notify, no CHILD_SA built +Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> failed to establish CHILD_SA, keeping IKE_SA +Jun 23 08:16:10 charon-systemd[3789]: failed to establish CHILD_SA, keeping IKE_SA +``` + +There are messages: **NO_PROPOSAL_CHOSEN** and +**failed to establish CHILD_SA** which refers that the problem is in +the IPsec(ESP) proposal mismatch. + +The reason of this problem is showed on the responder side. + +``` none +Jun 23 08:16:12 charon[2440]: 01[CFG] <PEER|5> received proposals: ESP:AES_CBC_256/HMAC_SHA1_96/NO_EXT_SEQ +Jun 23 08:16:12 charon-systemd[2440]: received proposals: ESP:AES_CBC_256/HMAC_SHA1_96/NO_EXT_SEQ +Jun 23 08:16:12 charon[2440]: 01[CFG] <PEER|5> configured proposals: ESP:AES_CBC_128/HMAC_SHA1_96/MODP_2048/NO_EXT_SEQ +Jun 23 08:16:12 charon-systemd[2440]: configured proposals: ESP:AES_CBC_128/HMAC_SHA1_96/MODP_2048/NO_EXT_SEQ +Jun 23 08:16:12 charon[2440]: 01[IKE] <PEER|5> no acceptable proposal found +Jun 23 08:16:12 charon-systemd[2440]: no acceptable proposal found +Jun 23 08:16:12 charon[2440]: 01[IKE] <PEER|5> failed to establish CHILD_SA, keeping IKE_SA +``` + +Encryption **AES_CBC_128** is configured in IKE policy on the responder but **AES_CBC_256** +is configured on the initiator side. + +### Prefixes in Policies Mismatch + +As in previous situation, IKE SA is in up state but IPsec SA is not up. +According to logs we can see **TS_UNACCEPTABLE** notification. It means +that prefixes (traffic selectors) mismatch on both sides + +Initiator: + +``` none +Jun 23 14:13:17 charon[4996]: 11[IKE] <PEER|1> received TS_UNACCEPTABLE notify, no CHILD_SA built +Jun 23 14:13:17 charon-systemd[4996]: maximum IKE_SA lifetime 29437s +Jun 23 14:13:17 charon[4996]: 11[IKE] <PEER|1> failed to establish CHILD_SA, keeping IKE_SA +Jun 23 14:13:17 charon-systemd[4996]: received TS_UNACCEPTABLE notify, no CHILD_SA built +Jun 23 14:13:17 charon-systemd[4996]: failed to establish CHILD_SA, keeping IKE_SA +``` + +The reason of this problem is showed on the responder side. + +``` none +Jun 23 14:13:19 charon[2440]: 01[IKE] <PEER|7> traffic selectors 10.0.2.0/24 === 10.0.0.0/24 unacceptable +Jun 23 14:13:19 charon-systemd[2440]: traffic selectors 10.0.2.0/24 === 10.0.0.0/24 unacceptable +Jun 23 14:13:19 charon[2440]: 01[IKE] <PEER|7> failed to establish CHILD_SA, keeping IKE_SA +Jun 23 14:13:19 charon-systemd[2440]: failed to establish CHILD_SA, keeping IKE_SA +Jun 23 14:13:19 charon[2440]: 01[ENC] <PEER|7> generating IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(TS_UNACCEPT) ] +Jun 23 14:13:19 charon-systemd[2440]: generating IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(TS_UNACCEPT) ] +``` + +Traffic selectors **10.0.2.0/24 === 10.0.0.0/24** are unacceptable on the +responder side. diff --git a/docs/configuration/vpn/md-dmvpn.md b/docs/configuration/vpn/md-dmvpn.md new file mode 100644 index 00000000..c335d306 --- /dev/null +++ b/docs/configuration/vpn/md-dmvpn.md @@ -0,0 +1,406 @@ +# DMVPN + +`DMVPN (Dynamic Multipoint Virtual Private Network)` is a dynamic +`VPN (Virtual Private Network)` technology originally developed by Cisco. +While their implementation was somewhat proprietary, the underlying +technologies are actually standards based. The three technologies are: + +- `NHRP (Next Hop Resolution Protocol)` `2332` +- `mGRE (Multipoint Generic Routing Encapsulation)` `1702` +- `IPSec (IP Security)` - too many RFCs to list, but start with + `4301` + +NHRP provides the dynamic tunnel endpoint discovery mechanism (endpoint +registration, and endpoint discovery/lookup), mGRE provides the tunnel +encapsulation itself, and the IPSec protocols handle the key exchange, and +crypto mechanism. + +In short, DMVPN provides the capability for creating a dynamic-mesh VPN +network without having to pre-configure (static) all possible tunnel end-point +peers. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +DMVPN only automates the tunnel endpoint discovery and setup. A +complete solution also incorporates the use of a routing protocol. BGP is +particularly well suited for use with DMVPN. + +</div> + +<figure> +<img src="/_static/images/vpn_dmvpn_topology01.webp" alt="Baseline DMVPN topology" /> +<figcaption aria-hidden="true">Baseline DMVPN topology</figcaption> +</figure> + +## Configuration + +- Please refer to the `tunnel-interface` documentation for the individual + tunnel related options. +- Please refer to the `ipsec_general` documentation for individual IPSec + related options. + +<div class="cfgcmd"> + +set protocols nhrp tunnel \<tunnel\> cisco-authentication \<secret\> + +Enables Cisco style authentication on NHRP packets. This embeds the secret +plaintext password to the outgoing NHRP packets. Incoming NHRP packets on +this interface are discarded unless the secret password is present. Maximum +length of the secret is 8 characters. + +</div> + +<div class="cfgcmd"> + +set protocols nhrp tunnel \<tunnel\> dynamic-map \<address\> +nbma-domain-name \<fqdn\> + +Specifies that the `NBMA (Non-broadcast multiple-access network)` +addresses of the next hop servers are defined in the domain name +nbma-domain-name. For each A record opennhrp creates a dynamic NHS entry. + +Each dynamic NHS will get a peer entry with the configured network address +and the discovered NBMA address. + +The first registration request is sent to the protocol broadcast address, and +the server's real protocol address is dynamically detected from the first +registration reply. + +</div> + +<div class="cfgcmd"> + +set protocols nhrp tunnel \<tunnel\> holding-time \<timeout\> + +Specifies the holding time for NHRP Registration Requests and Resolution +Replies sent from this interface or shortcut-target. The holdtime is specified +in seconds and defaults to two hours. + +</div> + +<div class="cfgcmd"> + +set protocols nhrp tunnel \<tunnel\> map cisco + +If the statically mapped peer is running Cisco IOS, specify the cisco keyword. +It is used to fix statically the Registration Request ID so that a matching +Purge Request can be sent if NBMA address has changed. This is to work around +broken IOS which requires Purge Request ID to match the original Registration +Request ID. + +</div> + +<div class="cfgcmd"> + +set protocols nhrp tunnel \<tunnel\> map nbma-address \<address\> + +Creates static peer mapping of protocol-address to `NBMA (Non-broadcast +multiple-access network)` address. + +If the IP prefix mask is present, it directs opennhrp to use this peer as a +next hop server when sending Resolution Requests matching this subnet. + +This is also known as the HUBs IP address or FQDN. + +</div> + +<div class="cfgcmd"> + +set protocols nhrp tunnel \<tunnel\> map register + +The optional parameter register specifies that Registration Request should be +sent to this peer on startup. + +This option is required when running a DMVPN spoke. + +</div> + +<div class="cfgcmd"> + +set protocols nhrp tunnel \<tunnel\> multicast \<dynamic | nhs\> + +Determines how opennhrp daemon should soft switch the multicast traffic. +Currently, multicast traffic is captured by opennhrp daemon using a packet +socket, and resent back to proper destinations. This means that multicast +packet sending is CPU intensive. + +Specfying nhs makes all multicast packets to be repeated to each statically +configured next hop. + +Synamic instructs to forward to all peers which we have a direct connection +with. Alternatively, you can specify the directive multiple times for each +protocol-address the multicast traffic should be sent to. + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +It is very easy to misconfigure multicast repeating if you have +multiple NHSes. + +</div> + +</div> + +<div class="cfgcmd"> + +set protocols nhrp tunnel \<tunnel\> non-caching + +Disables caching of peer information from forwarded NHRP Resolution Reply +packets. This can be used to reduce memory consumption on big NBMA subnets. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Currently does not do much as caching is not implemented. + +</div> + +</div> + +<div class="cfgcmd"> + +set protocols nhrp tunnel \<tunnel\> redirect + +Enable sending of Cisco style NHRP Traffic Indication packets. If this is +enabled and opennhrp detects a forwarded packet, it will send a message to +the original sender of the packet instructing it to create a direct connection +with the destination. This is basically a protocol independent equivalent of +ICMP redirect. + +</div> + +<div class="cfgcmd"> + +set protocols nhrp tunnel \<tunnel\> shortcut + +Enable creation of shortcut routes. + +A received NHRP Traffic Indication will trigger the resolution and +establishment of a shortcut route. + +</div> + +<div class="cfgcmd"> + +set protocols nhrp tunnel \<tunnel\> shortcut-destination + +This instructs opennhrp to reply with authorative answers on NHRP Resolution +Requests destinied to addresses in this interface (instead of forwarding the +packets). This effectively allows the creation of shortcut routes to subnets +located on the interface. + +When specified, this should be the only keyword for the interface. + +</div> + +<div class="cfgcmd"> + +set protocols nhrp tunnel \<tunnel\> shortcut-target \<address\> + +Defines an off-NBMA network prefix for which the GRE interface will act as a +gateway. This an alternative to defining local interfaces with +shortcut-destination flag. + +</div> + +<div class="cfgcmd"> + +set protocols nhrp tunnel \<tunnel\> shortcut-target \<address\> +holding-time \<timeout\> + +Specifies the holding time for NHRP Registration Requests and Resolution +Replies sent from this interface or shortcut-target. The holdtime is specified +in seconds and defaults to two hours. + +</div> + +## Example + +This blueprint uses VyOS as the DMVPN Hub and Cisco (7206VXR) and VyOS as +multiple spoke sites. The lab was built using `EVE-NG (Emulated Virtual +Environment NG)`. + +<figure> +<img src="/_static/images/blueprint-dmvpn.webp" alt="DMVPN network" /> +<figcaption>DMVPN example network</figcaption> +</figure> + +Each node (Hub and Spoke) uses an IP address from the network 172.16.253.128/29. + +The below referenced IP address <span class="title-ref">192.0.2.1</span> is used as example address +representing a global unicast address under which the HUB can be contacted by +each and every individual spoke. + +### Configuration + +#### Hub + +``` none +set interfaces ethernet eth0 address 192.0.2.1/24 + +set interfaces tunnel tun100 address '172.16.253.134/29' +set interfaces tunnel tun100 encapsulation 'gre' +set interfaces tunnel tun100 local-ip '192.0.2.1' +set interfaces tunnel tun100 enable-multicast +set interfaces tunnel tun100 parameters ip key '1' + +set protocols nhrp tunnel tun100 cisco-authentication 'secret' +set protocols nhrp tunnel tun100 holding-time '300' +set protocols nhrp tunnel tun100 multicast 'dynamic' +set protocols nhrp tunnel tun100 redirect +set protocols nhrp tunnel tun100 shortcut + +set vpn ipsec esp-group ESP-HUB lifetime '1800' +set vpn ipsec esp-group ESP-HUB mode 'transport' +set vpn ipsec esp-group ESP-HUB pfs 'dh-group2' +set vpn ipsec esp-group ESP-HUB proposal 1 encryption 'aes256' +set vpn ipsec esp-group ESP-HUB proposal 1 hash 'sha1' +set vpn ipsec esp-group ESP-HUB proposal 2 encryption '3des' +set vpn ipsec esp-group ESP-HUB proposal 2 hash 'md5' +set vpn ipsec ike-group IKE-HUB key-exchange 'ikev1' +set vpn ipsec ike-group IKE-HUB lifetime '3600' +set vpn ipsec ike-group IKE-HUB proposal 1 dh-group '2' +set vpn ipsec ike-group IKE-HUB proposal 1 encryption 'aes256' +set vpn ipsec ike-group IKE-HUB proposal 1 hash 'sha1' +set vpn ipsec ike-group IKE-HUB proposal 2 dh-group '2' +set vpn ipsec ike-group IKE-HUB proposal 2 encryption 'aes128' +set vpn ipsec ike-group IKE-HUB proposal 2 hash 'sha1' + +set vpn ipsec interface 'eth0' + +set vpn ipsec profile NHRPVPN authentication mode 'pre-shared-secret' +set vpn ipsec profile NHRPVPN authentication pre-shared-secret 'secret' +set vpn ipsec profile NHRPVPN bind tunnel 'tun100' +set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' +set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Setting this up on AWS will require a "Custom Protocol Rule" for +protocol number "47" (GRE) Allow Rule in TWO places. Firstly on the VPC +Network ACL, and secondly on the security group network ACL attached to the +EC2 instance. This has been tested as working for the official AMI image on +the AWS Marketplace. (Locate the correct VPC and security group by navigating +through the details pane below your EC2 instance in the AWS console). + +</div> + +#### Spoke + +The individual spoke configurations only differ in the local IP address on the +`tun10` interface. See the above diagram for the individual IP addresses. + +##### spoke01-spoke04 + +``` none +crypto keyring DMVPN + pre-shared-key address 192.0.2.1 key secret +! +crypto isakmp policy 10 + encr aes 256 + authentication pre-share + group 2 +crypto isakmp invalid-spi-recovery +crypto isakmp keepalive 30 30 periodic +crypto isakmp profile DMVPN + keyring DMVPN + match identity address 192.0.2.1 255.255.255.255 +! +crypto ipsec transform-set DMVPN-AES256 esp-aes 256 esp-sha-hmac + mode transport +! +crypto ipsec profile DMVPN + set security-association idle-time 720 + set transform-set DMVPN-AES256 + set isakmp-profile DMVPN +! +interface Tunnel10 + ! individual spoke tunnel IP must change + ip address 172.16.253.129 255.255.255.248 + no ip redirects + ip nhrp authentication secret + ip nhrp map 172.16.253.134 192.0.2.1 + ip nhrp map multicast 192.0.2.1 + ip nhrp network-id 1 + ip nhrp holdtime 600 + ip nhrp nhs 172.16.253.134 + ip nhrp registration timeout 75 + tunnel source FastEthernet0/0 + tunnel mode gre multipoint + tunnel protection ipsec profile DMVPN + tunnel key 1 +! +interface FastEthernet0/0 + ip address dhcp + duplex half +``` + +##### spoke05 + +VyOS can also run in DMVPN spoke mode. + +``` none +set interfaces ethernet eth0 address 'dhcp' + +set interfaces tunnel tun100 address '172.16.253.133/29' +set interfaces tunnel tun100 local-ip 0.0.0.0 +set interfaces tunnel tun100 encapsulation 'gre' +set interfaces tunnel tun100 enable-multicast +set interfaces tunnel tun100 parameters ip key '1' + +set protocols nhrp tunnel tun100 cisco-authentication 'secret' +set protocols nhrp tunnel tun100 holding-time '300' +set protocols nhrp tunnel tun100 map 172.16.253.134/29 nbma-address '192.0.2.1' +set protocols nhrp tunnel tun100 map 172.16.253.134/29 register +set protocols nhrp tunnel tun100 multicast 'nhs' +set protocols nhrp tunnel tun100 redirect +set protocols nhrp tunnel tun100 shortcut + +set vpn ipsec esp-group ESP-HUB lifetime '1800' +set vpn ipsec esp-group ESP-HUB mode 'transport' +set vpn ipsec esp-group ESP-HUB pfs 'dh-group2' +set vpn ipsec esp-group ESP-HUB proposal 1 encryption 'aes256' +set vpn ipsec esp-group ESP-HUB proposal 1 hash 'sha1' +set vpn ipsec esp-group ESP-HUB proposal 2 encryption '3des' +set vpn ipsec esp-group ESP-HUB proposal 2 hash 'md5' +set vpn ipsec ike-group IKE-HUB close-action 'none' +set vpn ipsec ike-group IKE-HUB key-exchange 'ikev1' +set vpn ipsec ike-group IKE-HUB lifetime '3600' +set vpn ipsec ike-group IKE-HUB proposal 1 dh-group '2' +set vpn ipsec ike-group IKE-HUB proposal 1 encryption 'aes256' +set vpn ipsec ike-group IKE-HUB proposal 1 hash 'sha1' +set vpn ipsec ike-group IKE-HUB proposal 2 dh-group '2' +set vpn ipsec ike-group IKE-HUB proposal 2 encryption 'aes128' +set vpn ipsec ike-group IKE-HUB proposal 2 hash 'sha1' + +set vpn ipsec interface 'eth0' + +set vpn ipsec profile NHRPVPN authentication mode 'pre-shared-secret' +set vpn ipsec profile NHRPVPN authentication pre-shared-secret 'secret' +set vpn ipsec profile NHRPVPN bind tunnel 'tun100' +set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' +set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' +``` diff --git a/docs/configuration/vpn/md-index.md b/docs/configuration/vpn/md-index.md new file mode 100644 index 00000000..b9aa768e --- /dev/null +++ b/docs/configuration/vpn/md-index.md @@ -0,0 +1,20 @@ +# VPN + +<div class="toctree" maxdepth="1" includehidden=""> + +ipsec/index +l2tp +openconnect +pptp +rsa-keys +sstp + +</div> + +pages to sort + +<div class="toctree" maxdepth="1" includehidden=""> + +dmvpn + +</div> diff --git a/docs/configuration/vpn/md-l2tp.md b/docs/configuration/vpn/md-l2tp.md new file mode 100644 index 00000000..1b71c71f --- /dev/null +++ b/docs/configuration/vpn/md-l2tp.md @@ -0,0 +1,837 @@ +# L2TP + +VyOS utilizes [accel-ppp](https://accel-ppp.org/) to provide L2TP server functionality. It can be used +with local authentication or a connected RADIUS server. + +## Configuring L2TP Server + +``` none +set vpn l2tp remote-access authentication mode local +set vpn l2tp remote-access authentication local-users username test password 'test' +set vpn l2tp remote-access client-ip-pool L2TP-POOL range 192.168.255.2-192.168.255.254 +set vpn l2tp remote-access default-pool 'L2TP-POOL' +set vpn l2tp remote-access outside-address 192.0.2.2 +set vpn l2tp remote-access gateway-address 192.168.255.1 +``` + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication mode \<local | radius\> + +Set authentication backend. The configured authentication backend is used +for all queries. + +- **radius**: All authentication queries are handled by a configured RADIUS + server. +- **local**: All authentication queries are handled locally. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication local-users username \<user\> password +\<pass\> + +Create <span class="title-ref">\<user\></span> for local authentication on this system. The users password +will be set to <span class="title-ref">\<pass\></span>. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access client-ip-pool \<POOL-NAME\> range \<x.x.x.x-x.x.x.x | x.x.x.x/x\> + +Use this command to define the first IP address of a pool of +addresses to be given to l2tp clients. If notation `x.x.x.x-x.x.x.x`, +it must be within a /24 subnet. If notation `x.x.x.x/x` is +used there is possibility to set host/netmask. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access default-pool \<POOL-NAME\> + +Use this command to define default address pool name. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access gateway-address \<gateway\> + +Specifies single <span class="title-ref">\<gateway\></span> IP address to be used as local address of PPP +interfaces. + +</div> + +## Configuring IPsec + +``` none +set vpn ipsec interface eth0 +set vpn l2tp remote-access ipsec-settings authentication mode pre-shared-secret +set vpn l2tp remote-access ipsec-settings authentication pre-shared-secret secret +``` + +<div class="cfgcmd"> + +set vpn ipsec interface \<INTERFACE\> + +Use this command to define IPsec interface. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access ipsec-settings authentication mode \<pre-shared-secret | x509\> + +Set mode for IPsec authentication between VyOS and L2TP clients. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access ipsec-settings authentication pre-shared-secret \<secret\> + +Set predefined shared secret phrase. + +</div> + +If a local firewall policy is in place on your external interface you will need +to allow the ports below: + +- UDP port 500 (IKE) +- IP protocol number 50 (ESP) +- UDP port 1701 for IPsec + +As well as the below to allow NAT-traversal (when NAT is detected by the +VPN client, ESP is encapsulated in UDP for NAT-traversal): + +- UDP port 4500 (NAT-T) + +Example: + +``` none +set firewall ipv4 name OUTSIDE-LOCAL rule 40 action 'accept' +set firewall ipv4 name OUTSIDE-LOCAL rule 40 protocol 'esp' +set firewall ipv4 name OUTSIDE-LOCAL rule 41 action 'accept' +set firewall ipv4 name OUTSIDE-LOCAL rule 41 destination port '500' +set firewall ipv4 name OUTSIDE-LOCAL rule 41 protocol 'udp' +set firewall ipv4 name OUTSIDE-LOCAL rule 42 action 'accept' +set firewall ipv4 name OUTSIDE-LOCAL rule 42 destination port '4500' +set firewall ipv4 name OUTSIDE-LOCAL rule 42 protocol 'udp' +set firewall ipv4 name OUTSIDE-LOCAL rule 43 action 'accept' +set firewall ipv4 name OUTSIDE-LOCAL rule 43 destination port '1701' +set firewall ipv4 name OUTSIDE-LOCAL rule 43 ipsec 'match-ipsec' +set firewall ipv4 name OUTSIDE-LOCAL rule 43 protocol 'udp' +``` + +To allow VPN-clients access via your external address, a NAT rule is required: + +``` none +set nat source rule 110 outbound-interface 'eth0' +set nat source rule 110 source address '192.168.255.0/24' +set nat source rule 110 translation address masquerade +``` + +## Configuring RADIUS authentication + +To enable RADIUS based authentication, the authentication mode needs to be +changed within the configuration. Previous settings like the local users, still +exists within the configuration, however they are not used if the mode has been +changed from local to radius. Once changed back to local, it will use all local +accounts again. + +``` none +set vpn l2tp remote-access authentication mode radius +``` + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius server \<server\> key \<secret\> + +Configure RADIUS <span class="title-ref">\<server\></span> and its required shared <span class="title-ref">\<secret\></span> for +communicating with the RADIUS server. + +</div> + +Since the RADIUS server would be a single point of failure, multiple RADIUS +servers can be setup and will be used subsequentially. +For example: + +``` none +set vpn l2tp remote-access authentication radius server 10.0.0.1 key 'foo' +set vpn l2tp remote-access authentication radius server 10.0.0.2 key 'foo' +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Some [RADIUS](https://en.wikipedia.org/wiki/RADIUS) severs use an access control list which allows or denies +queries, make sure to add your VyOS router to the allowed client list. + +</div> + +### RADIUS source address + +If you are using OSPF as your IGP, use the interface connected closest to the +RADIUS server. You can bind all outgoing RADIUS requests to a single source IP +e.g. the loopback interface. + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queires. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The `source-address` must be configured to that of an interface. +Best practice would be a loopback or dummy interface. + +</div> + +### RADIUS advanced options + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius server \<server\> port \<port\> + +Configure RADIUS <span class="title-ref">\<server\></span> and its required port for authentication requests. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius server \<server\> fail-time \<time\> + +Mark RADIUS server as offline for this given <span class="title-ref">\<time\></span> in seconds. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius server \<server\> disable + +Temporary disable this RADIUS server. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius acct-timeout \<timeout\> + +Timeout to wait reply for Interim-Update packets. (default 3 seconds) + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius dynamic-author server \<address\> + +Specifies IP address for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius dynamic-author port \<port\> + +Port for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius dynamic-author key \<secret\> + +Secret for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius max-try \<number\> + +Maximum number of tries to send Access-Request/Accounting-Request queries + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius timeout \<timeout\> + +Timeout to wait response from server (seconds) + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius nas-identifier \<identifier\> + +Value to send to RADIUS server in NAS-Identifier attribute and to be matched +in DM/CoA requests. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius nas-ip-address \<address\> + +Value to send to RADIUS server in NAS-IP-Address attribute and to be matched +in DM/CoA requests. Also DM/CoA server will bind to that address. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queires. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius rate-limit attribute \<attribute\> + +Specifies which RADIUS server attribute contains the rate limit information. +The default attribute is <span class="title-ref">Filter-Id</span>. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you set a custom RADIUS attribute you must define it on both +dictionaries on the RADIUS server and client. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius rate-limit enable + +Enables bandwidth shaping via RADIUS. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication radius rate-limit vendor + +Specifies the vendor dictionary. This dictionary needs to be present in +/usr/share/accel-ppp/radius. + +</div> + +Received RADIUS attributes have a higher priority than parameters defined within +the CLI configuration, refer to the explanation below. + +### Allocation clients ip addresses by RADIUS + +If the RADIUS server sends the attribute `Framed-IP-Address` then this IP +address will be allocated to the client and the option `default-pool` within +the CLI config will be ignored. + +If the RADIUS server sends the attribute `Framed-Pool`, then the IP address +will be allocated from a predefined IP pool whose name equals the attribute +value. + +If the RADIUS server sends the attribute `Stateful-IPv6-Address-Pool`, the +IPv6 address will be allocated from a predefined IPv6 pool `prefix` whose +name equals the attribute value. + +If the RADIUS server sends the attribute `Delegated-IPv6-Prefix-Pool`, an +IPv6 delegation prefix will be allocated from a predefined IPv6 pool +`delegate` whose name equals the attribute value. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +`Stateful-IPv6-Address-Pool` and `Delegated-IPv6-Prefix-Pool` are defined in +RFC6911. If they are not defined in your RADIUS server, add new [dictionary](https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911). + +</div> + +The client's interface can be put into a VRF context via a RADIUS Access-Accept +packet, or changed via RADIUS CoA. `Accel-VRF-Name` is used for these +purposes. This is a custom [ACCEL-PPP attribute](https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel). Define it in your RADIUS +server. + +### Renaming clients interfaces by RADIUS + +If the RADIUS server uses the attribute `NAS-Port-Id`, ppp tunnels will be +renamed. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The value of the attribute `NAS-Port-Id` must be less than 16 +characters, otherwise the interface won't be renamed. + +</div> + +## Configuring LNS (L2TP Network Server) + +LNS are often used to connect to a LAC (L2TP Access Concentrator). + +<div class="cfgcmd"> + +set vpn l2tp remote-access lns host-name \<hostname\> + +Sent to the client (LAC) in the Host-Name attribute + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access lns shared-secret \<secret\> + +Tunnel password used to authenticate the client (LAC) + +</div> + +To explain the usage of LNS follow our blueprint `examples-lac-lns`. + +## IPv6 + +<div class="cfgcmd"> + +set vpn l2tp remote-access ppp-options ipv6 \<require | prefer | allow | deny\> + +Specifies IPv6 negotiation preference. + +- **require** - Require IPv6 negotiation +- **prefer** - Ask client for IPv6 negotiation, do not fail if it rejects +- **allow** - Negotiate IPv6 only if client requests +- **deny** - Do not negotiate IPv6 (default value) + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access client-ipv6-pool \<IPv6-POOL-NAME\> prefix \<address\> +mask \<number-of-bits\> + +Use this comand to set the IPv6 address pool from which an l2tp client will +get an IPv6 prefix of your defined length (mask) to terminate the l2tp +endpoint at their side. The mask length can be set between 48 and 128 bits +long, the default value is 64. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access client-ipv6-pool \<IPv6-POOL-NAME\> delegate \<address\> +delegation-prefix \<number-of-bits\> + +Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on l2tp. +You will have to set your IPv6 pool and the length of the delegation +prefix. From the defined IPv6 pool you will be handing out networks of the +defined length (delegation-prefix). The length of the delegation prefix can +be between 32 and 64 bits long. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access default-ipv6-pool \<IPv6-POOL-NAME\> + +Use this command to define default IPv6 address pool name. + +</div> + +``` none +set vpn l2tp remote-access ppp-options ipv6 allow +set vpn l2tp remote-access client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' +set vpn l2tp remote-access client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' +set vpn l2tp remote-access default-ipv6-pool IPv6-POOL +``` + +### IPv6 Advanced Options + +<div class="cfgcmd"> + +set vpn l2tp remote-access ppp-options ipv6-accept-peer-interface-id + +Accept peer interface identifier. By default this is not defined. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access ppp-options ipv6-interface-id \<random | x:x:x:x\> + +Specifies if a fixed or random interface identifier is used for IPv6. The +default is fixed. + +- **random** - Random interface identifier for IPv6 +- **x:x:x:x** - Specify interface identifier for IPv6 + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access ppp-options ipv6-interface-id \<random | x:x:x:x\> + +Specifies the peer interface identifier for IPv6. The default is fixed. + +- **random** - Random interface identifier for IPv6 +- **x:x:x:x** - Specify interface identifier for IPv6 +- **ipv4-addr** - Calculate interface identifier from IPv4 address. +- **calling-sid** - Calculate interface identifier from calling-station-id. + +</div> + +## Scripting + +<div class="cfgcmd"> + +set vpn l2tp remote-access extended-scripts on-change \<path_to_script\> + +Script to run when the session interface is changed by RADIUS CoA handling + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access extended-scripts on-down \<path_to_script\> + +Script to run when the session interface is about to terminate + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access extended-scripts on-pre-up \<path_to_script\> + +Script to run before the session interface comes up + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access extended-scripts on-up \<path_to_script\> + +Script to run when the session interface is completely configured and started + +</div> + +## Advanced Options + +### Authentication Advanced Options + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication local-users username \<user\> disable + +Disable <span class="title-ref">\<user\></span> account. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication local-users username \<user\> static-ip +\<address\> + +Assign a static IP address to <span class="title-ref">\<user\></span> account. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication local-users username \<user\> rate-limit +download \<bandwidth\> + +Rate limit the download bandwidth for <span class="title-ref">\<user\></span> to <span class="title-ref">\<bandwidth\></span> kbit/s. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication local-users username \<user\> rate-limit +upload \<bandwidth\> + +Rate limit the upload bandwidth for <span class="title-ref">\<user\></span> to <span class="title-ref">\<bandwidth\></span> kbit/s + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access authentication protocols +\<pap | chap | mschap | mschap-v2\> + +Require the peer to authenticate itself using one of the following protocols: +pap, chap, mschap, mschap-v2. + +</div> + +### Client IP Pool Advanced Options + +<div class="cfgcmd"> + +set vpn l2tp remote-access client-ip-pool \<POOL-NAME\> next-pool \<NEXT-POOL-NAME\> + +Use this command to define the next address pool name. + +</div> + +### PPP Advanced Options + +<div class="cfgcmd"> + +set vpn l2tp remote-access ppp-options disable-ccp + +Disable Compression Control Protocol (CCP). +CCP is enabled by default. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access ppp-options interface-cache \<number\> + +Specifies number of interfaces to cache. This prevents interfaces from being +removed once the corresponding session is destroyed. Instead, interfaces are +cached for later use in new sessions. This should reduce the kernel-level +interface creation/deletion rate. +Default value is **0**. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access ppp-options ipv4 \<require | prefer | allow | deny\> + +Specifies IPv4 negotiation preference. + +- **require** - Require IPv4 negotiation +- **prefer** - Ask client for IPv4 negotiation, do not fail if it rejects +- **allow** - Negotiate IPv4 only if client requests (Default value) +- **deny** - Do not negotiate IPv4 + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access ppp-options lcp-echo-failure \<number\> + +Defines the maximum <span class="title-ref">\<number\></span> of unanswered echo requests. Upon reaching the +value <span class="title-ref">\<number\></span>, the session will be reset. Default value is **3**. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access ppp-options lcp-echo-interval \<interval\> + +If this option is specified and is greater than 0, then the PPP module will +send LCP echo requests every <span class="title-ref">\<interval\></span> seconds. +Default value is **30**. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access ppp-options lcp-echo-timeout + +Specifies timeout in seconds to wait for any peer activity. If this option is +specified it turns on adaptive lcp echo functionality and "lcp-echo-failure" +is not used. Default value is **0**. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access ppp-options min-mtu \<number\> + +Defines the minimum acceptable MTU. If a client tries to negotiate an MTU +lower than this it will be NAKed, and disconnected if it rejects a greater +MTU. +Default value is **100**. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access ppp-options mppe \<require | prefer | deny\> + +Specifies `MPPE (Microsoft Point-to-Point Encryption)` negotiation +preference. + +- **require** - ask client for mppe, if it rejects drop connection +- **prefer** - ask client for mppe, if it rejects don't fail. (Default value) +- **deny** - deny mppe + +Default behavior - don't ask the client for mppe, but allow it if the client +wants. +Please note that RADIUS may override this option with the +MS-MPPE-Encryption-Policy attribute. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access ppp-options mru \<number\> + +Defines preferred MRU. By default is not defined. + +</div> + +### Global Advanced options + +<div class="cfgcmd"> + +set vpn l2tp remote-access description \<description\> + +Set description. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access limits burst \<value\> + +Burst count + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access limits connection-limit \<value\> + +Maximum accepted connection rate (e.g. 1/min, 60/sec) + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access limits timeout \<value\> + +Timeout in seconds + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access mtu + +Maximum Transmission Unit (MTU) (default: **1436**) + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access max-concurrent-sessions + +Maximum number of concurrent session start attempts + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access name-server \<address\> + +Connected clients should use <span class="title-ref">\<address\></span> as their DNS server. This command +accepts both IPv4 and IPv6 addresses. Up to two nameservers can be configured +for IPv4, up to three for IPv6. + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access shaper fwmark \<1-2147483647\> + +Match firewall mark value + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access snmp master-agent + +Enable SNMP + +</div> + +<div class="cfgcmd"> + +set vpn l2tp remote-access wins-server \<address\> + +Windows Internet Name Service (WINS) servers propagated to client + +</div> + +## Monitoring + +``` none +vyos@vyos:~$ show l2tp-server sessions + ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes +--------+----------+---------------+-----+--------+-------------+------------+--------+----------+----------+---------- + l2tp0 | test | 192.168.255.3 | | | 192.168.0.36 | | active | 02:01:47 | 7.7 KiB | 1.2 KiB +``` + +``` none +vyos@vyos:~$ show l2tp-server statistics + uptime: 0.02:49:49 +cpu: 0% +mem(rss/virt): 5920/100892 kB +core: + mempool_allocated: 133202 + mempool_available: 131770 + thread_count: 1 + thread_active: 1 + context_count: 5 + context_sleeping: 0 + context_pending: 0 + md_handler_count: 3 + md_handler_pending: 0 + timer_count: 0 + timer_pending: 0 +sessions: + starting: 0 + active: 0 + finishing: 0 +l2tp: + tunnels: + starting: 0 + active: 0 + finishing: 0 + sessions (control channels): + starting: 0 + active: 0 + finishing: 0 + sessions (data channels): + starting: 0 + active: 0 + finishing: 0 +``` diff --git a/docs/configuration/vpn/md-openconnect.md b/docs/configuration/vpn/md-openconnect.md new file mode 100644 index 00000000..91310cdd --- /dev/null +++ b/docs/configuration/vpn/md-openconnect.md @@ -0,0 +1,329 @@ +# OpenConnect + +OpenConnect-compatible server feature has been available since Equuleus (1.3). +Openconnect VPN supports SSL connection and offers full network access. SSL VPN +network extension connects the end-user system to the corporate network with +access controls based only on network layer information, such as destination IP +address and port number. So, it provides safe communication for all types of +device traffic across public networks and private networks, also encrypts the +traffic with SSL protocol. + +The remote user will use the openconnect client to connect to the router and +will receive an IP address from a VPN pool, allowing full access to the +network. + +## Configuration + +### SSL Certificates + +We need to generate the certificate which authenticates users who attempt to +access the network resource through the SSL VPN tunnels. The following commands +will create a self signed certificates and will be stored in configuration: + +``` none +run generate pki ca install <CA name> +run generate pki certificate sign <CA name> install <Server name> +``` + +We can also create the certificates using Certbot which is an easy-to-use +client that fetches a certificate from Let's Encrypt an open certificate +authority launched by the EFF, Mozilla, and others and deploys it to a web +server. + +``` none +sudo certbot certonly --standalone --preferred-challenges http -d <domain name> +``` + +### Server Configuration + +``` none +set vpn openconnect authentication local-users username <user> password <pass> +set vpn openconnect authentication mode <local password|radius> +set vpn openconnect network-settings client-ip-settings subnet <subnet> +set vpn openconnect network-settings name-server <address> +set vpn openconnect network-settings name-server <address> +set vpn openconnect ssl ca-certificate <pki-ca-name> +set vpn openconnect ssl certificate <pki-cert-name> +set vpn openconnect ssl passphrase <pki-password> +``` + +### 2FA OTP support + +Instead of password only authentication, 2FA password +authentication + OTP key can be used. Alternatively, OTP authentication only, +without a password, can be used. +To do this, an OTP configuration must be added to the configuration above: + +``` none +set vpn openconnect authentication mode local <password-otp|otp> +set vpn openconnect authentication local-users username <user> otp <key> +set vpn openconnect authentication local-users username <user> interval <interval (optional)> +set vpn openconnect authentication local-users username <user> otp-length <otp-length (optional)> +set vpn openconnect authentication local-users username <user> token-type <token-type (optional)> +``` + +For generating an OTP key in VyOS, you can use the CLI command +(operational mode): + +``` none +generate openconnect username <user> otp-key hotp-time +``` + +## Verification + +``` none +vyos@vyos:~$ sh openconnect-server sessions +interface username ip remote IP RX TX state uptime +----------- ---------- ------------- ----------- ------- --------- --------- -------- +sslvpn0 tst 172.20.20.198 192.168.6.1 0 bytes 152 bytes connected 3s +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +It is compatible with Cisco (R) AnyConnect (R) clients. + +</div> + +## Example + +### SSL Certificates generation + +Follow the instructions to generate CA cert (in configuration mode): + +``` none +vyos@vyos# run generate pki ca install ca-ocserv +Enter private key type: [rsa, dsa, ec] (Default: rsa) +Enter private key bits: (Default: 2048) +Enter country code: (Default: GB) US +Enter state: (Default: Some-State) Delaware +Enter locality: (Default: Some-City) Mycity +Enter organization name: (Default: VyOS) MyORG +Enter common name: (Default: vyos.io) oc-ca +Enter how many days certificate will be valid: (Default: 1825) 3650 +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] N +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +[edit] +``` + +Follow the instructions to generate server cert (in configuration mode): + +``` none +vyos@vyos# run generate pki certificate sign ca-ocserv install srv-ocserv +Do you already have a certificate request? [y/N] N +Enter private key type: [rsa, dsa, ec] (Default: rsa) +Enter private key bits: (Default: 2048) +Enter country code: (Default: GB) US +Enter state: (Default: Some-State) Delaware +Enter locality: (Default: Some-City) Mycity +Enter organization name: (Default: VyOS) MyORG +Enter common name: (Default: vyos.io) oc-srv +Do you want to configure Subject Alternative Names? [y/N] N +Enter how many days certificate will be valid: (Default: 365) 1830 +Enter certificate type: (client, server) (Default: server) +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] N +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +[edit] +``` + +Each of the install command should be applied to the configuration and commited +before using under the openconnect configuration: + +``` none +vyos@vyos# commit +[edit] +vyos@vyos# save +Saving configuration to '/config/config.boot'... +Done +[edit] +``` + +### Openconnect Configuration + +Simple setup with one user added and password authentication: + +``` none +set vpn openconnect authentication local-users username tst password 'OC_bad_Secret' +set vpn openconnect authentication mode local password +set vpn openconnect network-settings client-ip-settings subnet '172.20.20.0/24' +set vpn openconnect network-settings name-server '10.1.1.1' +set vpn openconnect network-settings name-server '10.1.1.2' +set vpn openconnect ssl ca-certificate 'ca-ocserv' +set vpn openconnect ssl certificate 'srv-ocserv' +``` + +### Adding a 2FA with an OTP-key + +First the OTP keys must be generated and sent to the user and to the +configuration: + +``` none +vyos@vyos:~$ generate openconnect username tst otp-key hotp-time +# You can share it with the user, he just needs to scan the QR in his OTP app +# username: tst +# OTP KEY: 5PA4SGYTQSGOBO3H3EQSSNCUNZAYAPH2 +# OTP URL: otpauth://totp/tst@vyos?secret=5PA4SGYTQSGOBO3H3EQSSNCUNZAYAPH2&digits=6&period=30 +█████████████████████████████████████████ +█████████████████████████████████████████ +████ ▄▄▄▄▄ █▀ ██▄▀ ▄█▄▀▀▄▄▄▄██ ▄▄▄▄▄ ████ +████ █ █ █▀ █▄▄▀▀▀▄█ ▄▄▀▄ █ █ █ ████ +████ █▄▄▄█ █▀█▀▄▄▀ ▄▀ █▀ ▀▄██ █▄▄▄█ ████ +████▄▄▄▄▄▄▄█▄█▄▀ ▀▄█ ▀ ▀ ▀ █▄█▄▄▄▄▄▄▄████ +████ ▄▄▄▀▄▄ ▄███▀▄▀█▄██▀ ▀▄ ▀▄█ ▀ ▀████ +████ ▀▀ ▀ ▄█▄ ▀ ▀▄ ▄█▀ ▄█ ▄▀▀▄██ █████ +████▄ █▄▀▀▄█▀ ▀█▄█▄▄▄▄ ▄▀█▀▀█ ▀ ▄ ▀█▀████ +█████ ▀█▀▄▄ █ ▀▄▄ ▄█▄ ▀█▀▀ █▀ ▄█████ +████▀██▀█▄▄ ▀▀▀▀█▄▀ ▀█▄▄▀▀▀ ▀ ▀█▄██▀▀████ +████▄ ▄ ▄▀▄██▀█ ▄ ▀▄██ ▄▄ ▀▀▄█▄██ ▄█████ +████▀▀ ▄▀ ▄ ▀█▀█▀█ █▀█▄▄▀█▀█▄██▄▄█ ▀████ +████ █ ▀█▄▄█▄ ▀ ▄▄▀▀ ▀ █▄█▀████ █▀ ▀████ +████▄██▄██▄█▀ ▄▀ ▄▄▀▄ ▄▀█ ▄ ▄▄▄ ▀█▄ ████ +████ ▄▄▄▄▄ █▄ ▀█▄█ ▄ ▀ ▄ ▄ █▄█ ▄▀▄█████ +████ █ █ █ ▀▄██▄▄▀█▄▀▄██▄▀ ▄ ▀██▀████ +████ █▄▄▄█ █ ██▀▄▄ ▀▄▄▀█▀ ▀█ ▄▀█ ▀██████ +████▄▄▄▄▄▄▄█▄███▄███▄█▄▄▄▄█▄▄█▄██▄█▄█████ +█████████████████████████████████████████ +█████████████████████████████████████████ +# To add this OTP key to configuration, run the following commands: +set vpn openconnect authentication local-users username tst otp key 'ebc1c91b13848ce0bb67d9212934546e41803cfa' +``` + +Next it is necessary to configure 2FA for OpenConnect: + +``` none +set vpn openconnect authentication mode local password-otp +set vpn openconnect authentication local-users username tst otp key 'ebc1c91b13848ce0bb67d9212934546e41803cfa' +``` + +Now when connecting the user will first be asked for the password +and then the OTP key. + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +When using Time-based one-time password (TOTP) (OTP HOTP-time), +be sure that the time on the server and the +OTP token generator are synchronized by NTP + +</div> + +To display the configured OTP user settings, use the command: + +``` none +show openconnect-server user <username> otp <full|key-b32|key-hex|qrcode|uri> +``` + +### Identity Based Configuration + +OpenConnect supports a subset of it's configuration options to be applied on a +per user/group basis, for configuration purposes we refer to this functionality +as "Identity based config". The following [OpenConnect Server Manual](https://ocserv.gitlab.io/www/manual.html#:~:text=Configuration%20files%20that%20will%20be%20applied%20per%20user%20connection%20or%0A%23%20per%20group) +outlines the set of configuration options that are allowed. This can be +leveraged to apply different sets of configs to different users or groups of +users. + +``` none +sudo mkdir -p /config/auth/ocserv/config-per-user +sudo touch /config/auth/ocserv/default-user.conf + +set vpn set vpn openconnect authentication identity-based-config mode user +set vpn openconnect authentication identity-based-config directory /config/auth/ocserv/config-per-user +set vpn openconnect authentication identity-based-config default-config /config/auth/ocserv/default-user.conf +``` + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +The above directory and default-config must be a child directory +of /config/auth, since files outside this directory are not persisted after an +image upgrade. + +</div> + +Once you commit the above changes you can create a config file in the +/config/auth/ocserv/config-per-user directory that matches a username of a +user you have created e.g. "tst". Now when logging in with the "tst" user the +config options you set in this file will be loaded. + +Be sure to set a sane default config in the default config file, this will be +loaded in the case that a user is authenticated and no file is found in the +configured directory matching the users username/group. + +``` none +sudo nano /config/auth/ocserv/config-per-user/tst +``` + +The same configuration options apply when Identity based config is configured +in group mode except that group mode can only be used with RADIUS +authentication. + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +OpenConnect server matches the filename in a case sensitive +manner, make sure the username/group name you configure matches the +filename exactly. + +</div> + +### Configuring RADIUS accounting + +OpenConnect can be configured to send accounting information to a +RADIUS server to capture user session data such as time of +connect/disconnect, data transferred, and so on. + +Configure an accounting server and enable accounting with: + +``` none +set vpn openconnect accounting mode radius +set vpn openconnect accounting radius server 172.20.20.10 +set vpn openconnect accounting radius server 172.20.20.10 port 1813 +set vpn openconnect accounting radius server 172.20.20.10 key your_radius_secret +``` + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +The RADIUS accounting feature must be used with the OpenConnect +authentication mode RADIUS. It cannot be used with local authentication. +You must configure the OpenConnect authentication mode to "radius". + +</div> + +An example of the data captured by a FREERADIUS server with sql accounting: + +``` none +mysql> SELECT username, nasipaddress, acctstarttime, acctstoptime, acctinputoctets, acctoutputoctets, callingstationid, framedipaddress, connectinfo_start FROM radacct; ++----------+---------------+---------------------+---------------------+-----------------+------------------+-------------------+-----------------+-----------------------------------+ +| username | nasipaddress | acctstarttime | acctstoptime | acctinputoctets | acctoutputoctets | callingstationid | framedipaddress | connectinfo_start | ++----------+---------------+---------------------+---------------------+-----------------+------------------+-------------------+-----------------+-----------------------------------+ +| test | 198.51.100.15 | 2023-01-13 00:59:15 | 2023-01-13 00:59:21 | 10606 | 152 | 192.168.6.1 | 172.20.20.198 | Open AnyConnect VPN Agent v8.05-1 | ++----------+---------------+---------------------+---------------------+-----------------+------------------+-------------------+-----------------+-----------------------------------+ +``` diff --git a/docs/configuration/vpn/md-pptp.md b/docs/configuration/vpn/md-pptp.md new file mode 100644 index 00000000..2f973da2 --- /dev/null +++ b/docs/configuration/vpn/md-pptp.md @@ -0,0 +1,808 @@ +# PPTP-Server + +The Point-to-Point Tunneling Protocol ([PPTP](#pptp)) has been implemented in VyOS only +for backwards compatibility. PPTP has many well known security issues and you +should use one of the many other new VPN implementations. + +## Configuring PPTP Server + +``` none +set vpn pptp remote-access authentication mode local +set vpn pptp remote-access authentication local-users username test password 'test' +set vpn pptp remote-access client-ip-pool PPTP-POOL range 192.168.255.2-192.168.255.254 +set vpn pptp remote-access default-pool 'PPTP-POOL' +set vpn pptp remote-access outside-address 192.0.2.2 +set vpn pptp remote-access gateway-address 192.168.255.1 +``` + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication mode \<local | radius\> + +Set authentication backend. The configured authentication backend is used +for all queries. + +- **radius**: All authentication queries are handled by a configured RADIUS + server. +- **local**: All authentication queries are handled locally. +- **noauth**: Authentication disabled. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication local-users username \<user\> password +\<pass\> + +Create <span class="title-ref">\<user\></span> for local authentication on this system. The users password +will be set to <span class="title-ref">\<pass\></span>. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access client-ip-pool \<POOL-NAME\> range \<x.x.x.x-x.x.x.x | x.x.x.x/x\> + +Use this command to define the first IP address of a pool of +addresses to be given to PPTP clients. If notation `x.x.x.x-x.x.x.x`, +it must be within a /24 subnet. If notation `x.x.x.x/x` is +used there is possibility to set host/netmask. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access default-pool \<POOL-NAME\> + +Use this command to define default address pool name. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access gateway-address \<gateway\> + +Specifies single <span class="title-ref">\<gateway\></span> IP address to be used as local address of PPP +interfaces. + +</div> + +## Configuring RADIUS authentication + +To enable RADIUS based authentication, the authentication mode needs to be +changed within the configuration. Previous settings like the local users, still +exists within the configuration, however they are not used if the mode has been +changed from local to radius. Once changed back to local, it will use all local +accounts again. + +``` none +set vpn pptp remote-access authentication mode radius +``` + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius server \<server\> key \<secret\> + +Configure RADIUS <span class="title-ref">\<server\></span> and its required shared <span class="title-ref">\<secret\></span> for +communicating with the RADIUS server. + +</div> + +Since the RADIUS server would be a single point of failure, multiple RADIUS +servers can be setup and will be used subsequentially. +For example: + +``` none +set vpn pptp remote-access authentication radius server 10.0.0.1 key 'foo' +set vpn pptp remote-access authentication radius server 10.0.0.2 key 'foo' +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Some RADIUS severs use an access control list which allows or denies +queries, make sure to add your VyOS router to the allowed client list. + +</div> + +### RADIUS source address + +If you are using OSPF as IGP, always the closest interface connected to the +RADIUS server is used. You can bind all outgoing RADIUS requests +to a single source IP e.g. the loopback interface. + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queires. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The `source-address` must be configured on one of VyOS interface. +Best practice would be a loopback or dummy interface. + +</div> + +### RADIUS advanced options + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius server \<server\> port \<port\> + +Configure RADIUS <span class="title-ref">\<server\></span> and its required port for authentication requests. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius server \<server\> fail-time \<time\> + +Mark RADIUS server as offline for this given <span class="title-ref">\<time\></span> in seconds. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius server \<server\> disable + +Temporary disable this RADIUS server. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius acct-timeout \<timeout\> + +Timeout to wait reply for Interim-Update packets. (default 3 seconds) + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius dynamic-author server \<address\> + +Specifies IP address for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius dynamic-author port \<port\> + +Port for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius dynamic-author key \<secret\> + +Secret for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius max-try \<number\> + +Maximum number of tries to send Access-Request/Accounting-Request queries + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius timeout \<timeout\> + +Timeout to wait response from server (seconds) + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius nas-identifier \<identifier\> + +Value to send to RADIUS server in NAS-Identifier attribute and to be matched +in DM/CoA requests. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius nas-ip-address \<address\> + +Value to send to RADIUS server in NAS-IP-Address attribute and to be matched +in DM/CoA requests. Also DM/CoA server will bind to that address. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queires. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius rate-limit attribute \<attribute\> + +Specifies which RADIUS server attribute contains the rate limit information. +The default attribute is <span class="title-ref">Filter-Id</span>. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you set a custom RADIUS attribute you must define it on both +dictionaries at RADIUS server and client. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius rate-limit enable + +Enables bandwidth shaping via RADIUS. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication radius rate-limit vendor + +Specifies the vendor dictionary, dictionary needs to be in +/usr/share/accel-ppp/radius. + +</div> + +Received RADIUS attributes have a higher priority than parameters defined within +the CLI configuration, refer to the explanation below. + +### Allocation clients ip addresses by RADIUS + +If the RADIUS server sends the attribute `Framed-IP-Address` then this IP +address will be allocated to the client and the option `default-pool` within the CLI +config is being ignored. + +If the RADIUS server sends the attribute `Framed-Pool`, IP address will be allocated +from a predefined IP pool whose name equals the attribute value. + +If the RADIUS server sends the attribute `Stateful-IPv6-Address-Pool`, IPv6 address +will be allocated from a predefined IPv6 pool `prefix` whose name equals the attribute value. + +If the RADIUS server sends the attribute `Delegated-IPv6-Prefix-Pool`, IPv6 +delegation pefix will be allocated from a predefined IPv6 pool `delegate` +whose name equals the attribute value. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +`Stateful-IPv6-Address-Pool` and `Delegated-IPv6-Prefix-Pool` are defined in +RFC6911. If they are not defined in your RADIUS server, add new [dictionary](https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911). + +</div> + +User interface can be put to VRF context via RADIUS Access-Accept packet, or change +it via RADIUS CoA. `Accel-VRF-Name` is used from these purposes. It is custom [ACCEL-PPP attribute](https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel). +Define it in your RADIUS server. + +### Renaming clients interfaces by RADIUS + +If the RADIUS server uses the attribute `NAS-Port-Id`, ppp tunnels will be +renamed. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The value of the attribute `NAS-Port-Id` must be less than 16 +characters, otherwise the interface won't be renamed. + +</div> + +## IPv6 + +<div class="cfgcmd"> + +set vpn pptp remote-access ppp-options ipv6 \<require | prefer | allow | deny\> + +Specifies IPv6 negotiation preference. + +- **require** - Require IPv6 negotiation +- **prefer** - Ask client for IPv6 negotiation, do not fail if it rejects +- **allow** - Negotiate IPv6 only if client requests +- **deny** - Do not negotiate IPv6 (default value) + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access client-ipv6-pool \<IPv6-POOL-NAME\> prefix \<address\> +mask \<number-of-bits\> + +Use this comand to set the IPv6 address pool from which an PPTP client +will get an IPv6 prefix of your defined length (mask) to terminate the +PPTP endpoint at their side. The mask length can be set from 48 to 128 +bit long, the default value is 64. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access client-ipv6-pool \<IPv6-POOL-NAME\> delegate \<address\> +delegation-prefix \<number-of-bits\> + +Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on +PPTP. You will have to set your IPv6 pool and the length of the +delegation prefix. From the defined IPv6 pool you will be handing out +networks of the defined length (delegation-prefix). The length of the +delegation prefix can be set from 32 to 64 bit long. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access default-ipv6-pool \<IPv6-POOL-NAME\> + +Use this command to define default IPv6 address pool name. + +</div> + +``` none +set vpn pptp remote-access ppp-options ipv6 allow +set vpn pptp remote-access client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' +set vpn pptp remote-access client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' +set vpn pptp remote-access default-ipv6-pool IPv6-POOL +``` + +### IPv6 Advanced Options + +<div class="cfgcmd"> + +set vpn pptp remote-access ppp-options ipv6-accept-peer-interface-id + +Accept peer interface identifier. By default is not defined. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access ppp-options ipv6-interface-id \<random | x:x:x:x\> + +Specifies fixed or random interface identifier for IPv6. +By default is fixed. + +- **random** - Random interface identifier for IPv6 +- **x:x:x:x** - Specify interface identifier for IPv6 + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access ppp-options ipv6-interface-id \<random | x:x:x:x\> + +Specifies peer interface identifier for IPv6. By default is fixed. + +- **random** - Random interface identifier for IPv6 +- **x:x:x:x** - Specify interface identifier for IPv6 +- **ipv4-addr** - Calculate interface identifier from IPv4 address. +- **calling-sid** - Calculate interface identifier from calling-station-id. + +</div> + +## Scripting + +<div class="cfgcmd"> + +set vpn pptp remote-access extended-scripts on-change \<path_to_script\> + +Script to run when session interface changed by RADIUS CoA handling + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access extended-scripts on-down \<path_to_script\> + +Script to run when session interface going to terminate + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access extended-scripts on-pre-up \<path_to_script\> + +Script to run before session interface comes up + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access extended-scripts on-up \<path_to_script\> + +Script to run when session interface is completely configured and started + +</div> + +## Advanced Options + +### Authentication Advanced Options + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication local-users username \<user\> disable + +Disable <span class="title-ref">\<user\></span> account. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication local-users username \<user\> static-ip +\<address\> + +Assign static IP address to <span class="title-ref">\<user\></span> account. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication local-users username \<user\> rate-limit +download \<bandwidth\> + +Download bandwidth limit in kbit/s for <span class="title-ref">\<user\></span>. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication local-users username \<user\> rate-limit +upload \<bandwidth\> + +Upload bandwidth limit in kbit/s for <span class="title-ref">\<user\></span>. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access authentication protocols +\<pap | chap | mschap | mschap-v2\> + +Require the peer to authenticate itself using one of the following protocols: +pap, chap, mschap, mschap-v2. + +</div> + +### Client IP Pool Advanced Options + +<div class="cfgcmd"> + +set vpn pptp remote-access client-ip-pool \<POOL-NAME\> next-pool \<NEXT-POOL-NAME\> + +Use this command to define the next address pool name. + +</div> + +### PPP Advanced Options + +<div class="cfgcmd"> + +set vpn pptp remote-access ppp-options disable-ccp + +Disable Compression Control Protocol (CCP). +CCP is enabled by default. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access ppp-options interface-cache \<number\> + +Specifies number of interfaces to keep in cache. It means that don’t +destroy interface after corresponding session is destroyed, instead +place it to cache and use it later for new sessions repeatedly. +This should reduce kernel-level interface creation/deletion rate lack. +Default value is **0**. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access ppp-options ipv4 \<require | prefer | allow | deny\> + +Specifies IPv4 negotiation preference. + +- **require** - Require IPv4 negotiation +- **prefer** - Ask client for IPv4 negotiation, do not fail if it rejects +- **allow** - Negotiate IPv4 only if client requests (Default value) +- **deny** - Do not negotiate IPv4 + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access ppp-options lcp-echo-failure \<number\> + +Defines the maximum <span class="title-ref">\<number\></span> of unanswered echo requests. Upon reaching the +value <span class="title-ref">\<number\></span>, the session will be reset. Default value is **3**. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access ppp-options lcp-echo-interval \<interval\> + +If this option is specified and is greater than 0, then the PPP module will +send LCP pings of the echo request every <span class="title-ref">\<interval\></span> seconds. +Default value is **30**. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access ppp-options lcp-echo-timeout + +Specifies timeout in seconds to wait for any peer activity. If this option +specified it turns on adaptive lcp echo functionality and "lcp-echo-failure" +is not used. Default value is **0**. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access ppp-options min-mtu \<number\> + +Defines minimum acceptable MTU. If client will try to negotiate less then +specified MTU then it will be NAKed or disconnected if rejects greater MTU. +Default value is **100**. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access ppp-options mppe \<require | prefer | deny\> + +Specifies `MPPE (Microsoft Point-to-Point Encryption)` negotiation +preference. + +- **require** - ask client for mppe, if it rejects drop connection +- **prefer** - ask client for mppe, if it rejects don't fail. (Default value) +- **deny** - deny mppe + +Default behavior - don't ask client for mppe, but allow it if client wants. +Please note that RADIUS may override this option by MS-MPPE-Encryption-Policy +attribute. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access ppp-options mru \<number\> + +Defines preferred MRU. By default is not defined. + +</div> + +### Global Advanced options + +<div class="cfgcmd"> + +set vpn pptp remote-access description \<description\> + +Set description. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access limits burst \<value\> + +Burst count + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access limits connection-limit \<value\> + +Acceptable rate of connections (e.g. 1/min, 60/sec) + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access limits timeout \<value\> + +Timeout in seconds + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access mtu + +Maximum Transmission Unit (MTU) (default: **1436**) + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access max-concurrent-sessions + +Maximum number of concurrent session start attempts + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access name-server \<address\> + +Connected client should use <span class="title-ref">\<address\></span> as their DNS server. This +command accepts both IPv4 and IPv6 addresses. Up to two nameservers +can be configured for IPv4, up to three for IPv6. + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access shaper fwmark \<1-2147483647\> + +Match firewall mark value + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access snmp master-agent + +Enable SNMP + +</div> + +<div class="cfgcmd"> + +set vpn pptp remote-access wins-server \<address\> + +Windows Internet Name Service (WINS) servers propagated to client + +</div> + +## Monitoring + +<div class="opcmd"> + +show pptp-server sessions + +Use this command to locally check the active sessions in the PPTP +server. + +</div> + +``` none +vyos@vyos:~$ show pptp-server sessions + ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes +--------+----------+----------+-----+--------+----------------+------------+--------+----------+----------+---------- + pptp0 | test | 10.0.0.2 | | | 192.168.10.100 | | active | 00:01:26 | 6.9 KiB | 220 B +``` + +``` none +vyos@vyos:~$ show pptp-server statistics + uptime: 0.00:04:52 +cpu: 0% +mem(rss/virt): 5504/100176 kB +core: + mempool_allocated: 152007 + mempool_available: 149007 + thread_count: 1 + thread_active: 1 + context_count: 6 + context_sleeping: 0 + context_pending: 0 + md_handler_count: 6 + md_handler_pending: 0 + timer_count: 2 + timer_pending: 0 +sessions: + starting: 0 + active: 1 + finishing: 0 +pptp: + starting: 0 + active: 1 +``` + +## Troubleshooting + +``` none +vyos@vyos:~$sudo journalctl -u accel-ppp@pptp -b 0 + +Feb 29 14:58:57 vyos accel-pptp[4629]: pptp: new connection from 192.168.10.100 +Feb 29 14:58:57 vyos accel-pptp[4629]: :: recv [PPTP Start-Ctrl-Conn-Request <Version 1> <Framing 1> <Bearer 1> <Max-Chan 0>] +Feb 29 14:58:57 vyos accel-pptp[4629]: :: send [PPTP Start-Ctrl-Conn-Reply <Version 1> <Result 1> <Error 0> <Framing 3> <Bearer 3> <Max-Chan 1>] +Feb 29 14:58:57 vyos accel-pptp[4629]: :: recv [PPTP Outgoing-Call-Request <Call-ID 2961> <Call-Serial 2> <Min-BPS 300> <Max-BPS 100000000> <Bearer 3> <Framing 3> <Window-Size 64> <Delay 0>] +Feb 29 14:58:57 vyos accel-pptp[4629]: :: send [PPTP Outgoing-Call-Reply <Call-ID 2> <Peer-Call-ID 2961> <Result 1> <Error 0> <Cause 0> <Speed 100000000> <Window-Size 64> <Delay 0> <Channel 0>] +Feb 29 14:58:57 vyos accel-pptp[4629]: :: lcp_layer_init +Feb 29 14:58:57 vyos accel-pptp[4629]: :: auth_layer_init +Feb 29 14:58:57 vyos accel-pptp[4629]: :: ccp_layer_init +Feb 29 14:58:57 vyos accel-pptp[4629]: :: ipcp_layer_init +Feb 29 14:58:57 vyos accel-pptp[4629]: :: ipv6cp_layer_init +Feb 29 14:58:57 vyos accel-pptp[4629]: :: ppp establishing +Feb 29 14:58:57 vyos accel-pptp[4629]: :: lcp_layer_start +Feb 29 14:58:57 vyos accel-pptp[4629]: :: send [LCP ConfReq id=75 <auth PAP> <mru 1436> <magic 483920bd>] +Feb 29 14:58:57 vyos accel-pptp[4629]: :: recv [PPTP Set-Link-Info] +Feb 29 14:58:57 vyos accel-pptp[4629]: :: recv [LCP ConfReq id=0 <mru 1400> <magic 0142785a> <pcomp> <accomp> < d 3 6 >] +Feb 29 14:58:57 vyos accel-pptp[4629]: :: send [LCP ConfRej id=0 <pcomp> <accomp> < d 3 6 >] +Feb 29 14:58:57 vyos accel-pptp[4629]: :: recv [LCP ConfReq id=1 <mru 1400> <magic 0142785a>] +Feb 29 14:58:57 vyos accel-pptp[4629]: :: send [LCP ConfAck id=1] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: fsm timeout 9 +Feb 29 14:59:00 vyos accel-pptp[4629]: :: send [LCP ConfReq id=75 <auth PAP> <mru 1436> <magic 483920bd>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP ConfNak id=75 <auth MSCHAP-v2>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: send [LCP ConfReq id=76 <auth CHAP-md5> <mru 1436> <magic 483920bd>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP ConfNak id=76 <auth MSCHAP-v2>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: send [LCP ConfReq id=77 <auth MSCHAP-v1> <mru 1436> <magic 483920bd>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP ConfNak id=77 <auth MSCHAP-v2>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: send [LCP ConfReq id=78 <auth MSCHAP-v2> <mru 1436> <magic 483920bd>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP ConfAck id=78 <auth MSCHAP-v2> <mru 1436> <magic 483920bd>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: lcp_layer_started +Feb 29 14:59:00 vyos accel-pptp[4629]: :: auth_layer_start +Feb 29 14:59:00 vyos accel-pptp[4629]: :: send [MSCHAP-v2 Challenge id=1 <8aa758781676e6a8e85c11963ee010>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP Ident id=2 <MSRASV5.20>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP Ident id=3 <MSRAS-0-MSEDGEWIN10>] +Feb 29 14:59:00 vyos accel-pptp[4629]: [43B blob data] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [PPTP Set-Link-Info] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [MSCHAP-v2 Response id=1 <90c21af1091f745e8bf22388b058>, <e695ae5aae274c88a3fa1ee3dc9057aece4d53c87b9fea>, F=0, name="test"] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: connect: ppp0 <--> pptp(192.168.10.100) +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ppp connected +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [MSCHAP-v2 Success id=1 "S=347F417CF04BEBBC7F75CFA7F43474C36FB218F9 M=Authentication succeeded"] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: test: authentication succeeded +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: auth_layer_started +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ccp_layer_start +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [CCP ConfReq id=b9 <mppe +H -M +S -L -D -C>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ipcp_layer_start +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ipv6cp_layer_start +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: IPV6CP: discarding packet +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [LCP ProtoRej id=122 <8057>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: recv [IPCP ConfReq id=6 <addr 0.0.0.0> <dns1 0.0.0.0> <wins1 0.0.0.0> <dns2 0.0.0.0> <wins2 0.0.0.0>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [IPCP ConfReq id=3b <addr 10.0.0.1>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [IPCP ConfRej id=6 <dns1 0.0.0.0> <wins1 0.0.0.0> <dns2 0.0.0.0> <wins2 0.0.0.0>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: recv [LCP ProtoRej id=7 <80fd>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ccp_layer_finished +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: recv [IPCP ConfAck id=3b <addr 10.0.0.1>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: recv [IPCP ConfReq id=8 <addr 0.0.0.0>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [IPCP ConfNak id=8 <addr 10.0.0.2>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: recv [IPCP ConfReq id=9 <addr 10.0.0.2>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [IPCP ConfAck id=9] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ipcp_layer_started +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: rename interface to 'pptp0' +Feb 29 14:59:00 vyos accel-pptp[4629]: pptp0:test: pptp: ppp started +``` diff --git a/docs/configuration/vpn/md-rsa-keys.md b/docs/configuration/vpn/md-rsa-keys.md new file mode 100644 index 00000000..7d54126f --- /dev/null +++ b/docs/configuration/vpn/md-rsa-keys.md @@ -0,0 +1,105 @@ +# RSA-Keys + +RSA can be used for services such as key exchanges and for encryption purposes. +To make IPSec work with dynamic address on one/both sides, we will have to use +RSA keys for authentication. They are very fast and easy to setup. + +First, on both routers run the operational command "generate pki key-pair +install \<key-pair name\>". You may choose different length than 2048 of course. + +``` none +vyos@left# run generate pki key-pair install ipsec-LEFT +Enter private key type: [rsa, dsa, ec] (Default: rsa) +Enter private key bits: (Default: 2048) +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] N +Configure mode commands to install key pair: +Do you want to install the public key? [Y/n] Yrgerg +set pki key-pair ipsec-LEFT public key 'MIIBIjANBgkqh...' +Do you want to install the private key? [Y/n] Y +set pki key-pair ipsec-LEFT private key 'MIIEvgIBADAN...' +[edit] +``` + +Configuration commands will display. +Note the command with the public key +(set pki key-pair ipsec-LEFT public key 'MIIBIjANBgkqh...'). +Then do the same on the opposite router: + +``` none +vyos@left# run generate pki key-pair install ipsec-RIGHT +``` + +Note the command with the public key +(set pki key-pair ipsec-RIGHT public key 'FAAOCAQ8AMII...'). + +The noted public keys should be entered on the opposite routers. + +On the LEFT: + +``` none +set pki key-pair ipsec-RIGHT public key 'FAAOCAQ8AMII...' +``` + +On the RIGHT: + +``` none +set pki key-pair ipsec-LEFT public key 'MIIBIjANBgkqh...' +``` + +Now you are ready to setup IPsec. The key points: + +1. Since both routers do not know their effective public addresses, we set the local-address of the peer to "any". +2. On the initiator, we set the peer address to its public address, but on the responder we only set the id. +3. On the initiator, we need to set the remote-id option so that it can identify IKE traffic from the responder correctly. +4. On the responder, we need to set the local id so that initiator can know who's talking to it for the point \#3 to work. + +On the LEFT (static address): + +``` none +set vpn ipsec interface eth0 + +set vpn ipsec esp-group MyESPGroup proposal 1 encryption aes128 +set vpn ipsec esp-group MyESPGroup proposal 1 hash sha1 + +set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group 2 +set vpn ipsec ike-group MyIKEGroup proposal 1 encryption aes128 +set vpn ipsec ike-group MyIKEGroup proposal 1 hash sha1 + +set vpn ipsec site-to-site peer @RIGHT authentication id LEFT +set vpn ipsec site-to-site peer @RIGHT authentication mode rsa +set vpn ipsec site-to-site peer @RIGHT authentication rsa local-key ipsec-LEFT +set vpn ipsec site-to-site peer @RIGHT authentication rsa remote-key ipsec-RIGHT +set vpn ipsec site-to-site peer @RIGHT authentication remote-id RIGHT +set vpn ipsec site-to-site peer @RIGHT default-esp-group MyESPGroup +set vpn ipsec site-to-site peer @RIGHT ike-group MyIKEGroup +set vpn ipsec site-to-site peer @RIGHT local-address 192.0.2.10 +set vpn ipsec site-to-site peer @RIGHT connection-type respond +set vpn ipsec site-to-site peer @RIGHT tunnel 1 local prefix 192.168.99.1/32 # Additional loopback address on the local +set vpn ipsec site-to-site peer @RIGHT tunnel 1 remote prefix 192.168.99.2/32 # Additional loopback address on the remote +``` + +On the RIGHT (dynamic address): + +``` none +set vpn ipsec interface eth0 + +set vpn ipsec esp-group MyESPGroup proposal 1 encryption aes128 +set vpn ipsec esp-group MyESPGroup proposal 1 hash sha1 + +set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group 2 +set vpn ipsec ike-group MyIKEGroup proposal 1 encryption aes128 +set vpn ipsec ike-group MyIKEGroup proposal 1 hash sha1 + +set vpn ipsec site-to-site peer 192.0.2.10 authentication id RIGHT +set vpn ipsec site-to-site peer 192.0.2.10 authentication mode rsa +set vpn ipsec site-to-site peer 192.0.2.10 authentication rsa local-key ipsec-RIGHT +set vpn ipsec site-to-site peer 192.0.2.10 authentication rsa remote-key ipsec-LEFT +set vpn ipsec site-to-site peer 192.0.2.10 authentication remote-id LEFT +set vpn ipsec site-to-site peer 192.0.2.10 connection-type initiate +set vpn ipsec site-to-site peer 192.0.2.10 default-esp-group MyESPGroup +set vpn ipsec site-to-site peer 192.0.2.10 ike-group MyIKEGroup +set vpn ipsec site-to-site peer 192.0.2.10 local-address any +set vpn ipsec site-to-site peer 192.0.2.10 tunnel 1 local prefix 192.168.99.2/32 # Additional loopback address on the local +set vpn ipsec site-to-site peer 192.0.2.10 tunnel 1 remote prefix 192.168.99.1/32 # Additional loopback address on the remote +``` diff --git a/docs/configuration/vpn/md-sstp.md b/docs/configuration/vpn/md-sstp.md new file mode 100644 index 00000000..8ac7d665 --- /dev/null +++ b/docs/configuration/vpn/md-sstp.md @@ -0,0 +1,919 @@ +# SSTP Server + +`SSTP (Secure Socket Tunneling Protocol)` is a form of `VPN +(Virtual Private Network)` tunnel that provides a mechanism to transport PPP +traffic through an SSL/TLS channel. SSL/TLS provides transport-level security +with key negotiation, encryption and traffic integrity checking. The use of +SSL/TLS over TCP port 443 allows SSTP to pass through virtually all firewalls +and proxy servers except for authenticated web proxies. + +SSTP is available for Linux, BSD, and Windows. + +VyOS utilizes [accel-ppp]() to provide SSTP server functionality. We support both +local and RADIUS authentication. + +As SSTP provides PPP via a SSL/TLS channel the use of either publicly signed +certificates or private PKI is required. + +## Configuring SSTP Server + +### Certificates + +Using our documentation chapter - `pki` generate and install CA and Server certificate + +``` none +vyos@vyos:~$ generate pki ca install CA +``` + +``` none +vyos@vyos:~$ generate pki certificate sign CA install Server +``` + +### Configuration + +``` none +set vpn sstp authentication local-users username test password 'test' +set vpn sstp authentication mode 'local' +set vpn sstp client-ip-pool SSTP-POOL range '10.0.0.2-10.0.0.100' +set vpn sstp default-pool 'SSTP-POOL' +set vpn sstp gateway-address '10.0.0.1' +set vpn sstp ssl ca-certificate 'CA1' +set vpn sstp ssl certificate 'Server' +``` + +<div class="cfgcmd"> + +set vpn sstp authentication mode \<local | radius\> + +Set authentication backend. The configured authentication backend is used +for all queries. + +- **radius**: All authentication queries are handled by a configured RADIUS + server. +- **local**: All authentication queries are handled locally. + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication local-users username \<user\> password +\<pass\> + +Create <span class="title-ref">\<user\></span> for local authentication on this system. The users password +will be set to <span class="title-ref">\<pass\></span>. + +</div> + +<div class="cfgcmd"> + +set vpn sstp client-ip-pool \<POOL-NAME\> range \<x.x.x.x-x.x.x.x | x.x.x.x/x\> + +Use this command to define the first IP address of a pool of +addresses to be given to SSTP clients. If notation `x.x.x.x-x.x.x.x`, +it must be within a /24 subnet. If notation `x.x.x.x/x` is +used there is possibility to set host/netmask. + +</div> + +<div class="cfgcmd"> + +set vpn sstp default-pool \<POOL-NAME\> + +Use this command to define default address pool name. + +</div> + +<div class="cfgcmd"> + +set vpn sstp gateway-address \<gateway\> + +Specifies single <span class="title-ref">\<gateway\></span> IP address to be used as local address of PPP +interfaces. + +</div> + +<div class="cfgcmd"> + +set vpn sstp ssl ca-certificate \<file\> + +Name of installed certificate authority certificate. + +</div> + +<div class="cfgcmd"> + +set vpn sstp ssl certificate \<file\> + +Name of installed server certificate. + +</div> + +## Configuring RADIUS authentication + +To enable RADIUS based authentication, the authentication mode needs to be +changed within the configuration. Previous settings like the local users still +exist within the configuration, however they are not used if the mode has been +changed from local to radius. Once changed back to local, it will use all local +accounts again. + +``` none +set vpn sstp authentication mode radius +``` + +<div class="cfgcmd"> + +set vpn sstp authentication radius server \<server\> key \<secret\> + +Configure RADIUS <span class="title-ref">\<server\></span> and its required shared <span class="title-ref">\<secret\></span> for +communicating with the RADIUS server. + +</div> + +Since the RADIUS server would be a single point of failure, multiple RADIUS +servers can be setup and will be used subsequentially. +For example: + +``` none +set vpn sstp authentication radius server 10.0.0.1 key 'foo' +set vpn sstp authentication radius server 10.0.0.2 key 'foo' +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Some RADIUS severs use an access control list which allows or denies +queries, make sure to add your VyOS router to the allowed client list. + +</div> + +### RADIUS source address + +If you are using OSPF as your IGP, use the interface connected closest to the +RADIUS server. You can bind all outgoing RADIUS requests to a single source IP +e.g. the loopback interface. + +<div class="cfgcmd"> + +set vpn sstp authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queires. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The `source-address` must be configured to that of an interface. +Best practice would be a loopback or dummy interface. + +</div> + +### RADIUS advanced options + +<div class="cfgcmd"> + +set vpn sstp authentication radius server \<server\> port \<port\> + +Configure RADIUS <span class="title-ref">\<server\></span> and its required port for authentication requests. + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication radius server \<server\> fail-time \<time\> + +Mark RADIUS server as offline for this given <span class="title-ref">\<time\></span> in seconds. + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication radius server \<server\> disable + +Temporary disable this RADIUS server. + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication radius acct-timeout \<timeout\> + +Timeout to wait reply for Interim-Update packets. (default 3 seconds) + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication radius dynamic-author server \<address\> + +Specifies IP address for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication radius dynamic-author port \<port\> + +Port for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication radius dynamic-author key \<secret\> + +Secret for Dynamic Authorization Extension server (DM/CoA) + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication radius max-try \<number\> + +Maximum number of tries to send Access-Request/Accounting-Request queries + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication radius timeout \<timeout\> + +Timeout to wait response from server (seconds) + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication radius nas-identifier \<identifier\> + +Value to send to RADIUS server in NAS-Identifier attribute and to be matched +in DM/CoA requests. + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication radius nas-ip-address \<address\> + +Value to send to RADIUS server in NAS-IP-Address attribute and to be matched +in DM/CoA requests. Also DM/CoA server will bind to that address. + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queires. + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication radius rate-limit attribute \<attribute\> + +Specifies which RADIUS server attribute contains the rate limit information. +The default attribute is <span class="title-ref">Filter-Id</span>. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you set a custom RADIUS attribute you must define it on both +dictionaries on the RADIUS server and client. + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication radius rate-limit enable + +Enables bandwidth shaping via RADIUS. + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication radius rate-limit vendor + +Specifies the vendor dictionary, This dictionary needs to be present in +/usr/share/accel-ppp/radius. + +</div> + +Received RADIUS attributes have a higher priority than parameters defined within +the CLI configuration, refer to the explanation below. + +### Allocation clients ip addresses by RADIUS + +If the RADIUS server sends the attribute `Framed-IP-Address` then this IP +address will be allocated to the client and the option `default-pool` within +the CLI config will being ignored. + +If the RADIUS server sends the attribute `Framed-Pool`, then the IP address +will be allocated from a predefined IP pool whose name equals the attribute +value. + +If the RADIUS server sends the attribute `Stateful-IPv6-Address-Pool`, the +IPv6 address will be allocated from a predefined IPv6 pool `prefix` whose +name equals the attribute value. + +If the RADIUS server sends the attribute `Delegated-IPv6-Prefix-Pool`, an +IPv6 delegation prefix will be allocated from a predefined IPv6 pool `delegate` +whose name equals the attribute value. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +`Stateful-IPv6-Address-Pool` and `Delegated-IPv6-Prefix-Pool` are defined in +RFC6911. If they are not defined in your RADIUS server, add new [dictionary](https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911). + +</div> + +The client's interface can be put into a VRF context via a RADIUS Access-Accept +packet, or changed via RADIUS CoA. `Accel-VRF-Name` is used for these +purposes. This is a custom [ACCEL-PPP attribute](https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel). Define it in your RADIUS +server. + +### Renaming clients interfaces by RADIUS + +If the RADIUS server uses the attribute `NAS-Port-Id`, ppp tunnels will be +renamed. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The value of the attribute `NAS-Port-Id` must be less than 16 +characters, otherwise the interface won't be renamed. + +</div> + +## IPv6 + +<div class="cfgcmd"> + +set vpn sstp ppp-options ipv6 \<require | prefer | allow | deny\> + +Specifies IPv6 negotiation preference. + +- **require** - Require IPv6 negotiation +- **prefer** - Ask client for IPv6 negotiation, do not fail if it rejects +- **allow** - Negotiate IPv6 only if client requests +- **deny** - Do not negotiate IPv6 (default value) + +</div> + +<div class="cfgcmd"> + +set vpn sstp client-ipv6-pool \<IPv6-POOL-NAME\> prefix \<address\> +mask \<number-of-bits\> + +Use this comand to set the IPv6 address pool from which an SSTP client will +get an IPv6 prefix of your defined length (mask) to terminate the SSTP +endpoint at their side. The mask length can be set between 48 and 128 bits +long, the default value is 64. + +</div> + +<div class="cfgcmd"> + +set vpn sstp client-ipv6-pool \<IPv6-POOL-NAME\> delegate \<address\> +delegation-prefix \<number-of-bits\> + +Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on SSTP. You +will have to set your IPv6 pool and the length of the delegation prefix. From +the defined IPv6 pool you will be handing out networks of the defined length +(delegation-prefix). The length of the delegation prefix can be set between +32 and 64 bits long. + +</div> + +<div class="cfgcmd"> + +set vpn sstp default-ipv6-pool \<IPv6-POOL-NAME\> + +Use this command to define default IPv6 address pool name. + +</div> + +``` none +set vpn sstp ppp-options ipv6 allow +set vpn sstp client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' +set vpn sstp client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' +set vpn sstp default-ipv6-pool IPv6-POOL +``` + +### IPv6 Advanced Options + +<div class="cfgcmd"> + +set vpn sstp ppp-options ipv6-accept-peer-interface-id + +Accept peer interface identifier. By default this is not defined. + +</div> + +<div class="cfgcmd"> + +set vpn sstp ppp-options ipv6-interface-id \<random | x:x:x:x\> + +Specifies if a fixed or random interface identifier is used for IPv6. The +default is fixed. + +- **random** - Random interface identifier for IPv6 +- **x:x:x:x** - Specify interface identifier for IPv6 + +</div> + +<div class="cfgcmd"> + +set vpn sstp ppp-options ipv6-interface-id \<random | x:x:x:x\> + +Specifies the peer interface identifier for IPv6. The default is fixed. + +- **random** - Random interface identifier for IPv6 +- **x:x:x:x** - Specify interface identifier for IPv6 +- **ipv4-addr** - Calculate interface identifier from IPv4 address. +- **calling-sid** - Calculate interface identifier from calling-station-id. + +</div> + +## Scripting + +<div class="cfgcmd"> + +set vpn sstp extended-scripts on-change \<path_to_script\> + +Script to run when the session interface is changed by RADIUS CoA handling + +</div> + +<div class="cfgcmd"> + +set vpn sstp extended-scripts on-down \<path_to_script\> + +Script to run when the session interface about to terminate + +</div> + +<div class="cfgcmd"> + +set vpn sstp extended-scripts on-pre-up \<path_to_script\> + +Script to run before the session interface comes up + +</div> + +<div class="cfgcmd"> + +set vpn sstp extended-scripts on-up \<path_to_script\> + +Script to run when the session interface is completely configured and started + +</div> + +## Advanced Options + +### Authentication Advanced Options + +<div class="cfgcmd"> + +set vpn sstp authentication local-users username \<user\> disable + +Disable <span class="title-ref">\<user\></span> account. + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication local-users username \<user\> static-ip +\<address\> + +Assign a static IP address to <span class="title-ref">\<user\></span> account. + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication local-users username \<user\> rate-limit +download \<bandwidth\> + +Rate limit the download bandwidth for <span class="title-ref">\<user\></span> to <span class="title-ref">\<bandwidth\></span> kbit/s. + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication local-users username \<user\> rate-limit +upload \<bandwidth\> + +Rate limit the upload bandwidth for <span class="title-ref">\<user\></span> to <span class="title-ref">\<bandwidth\></span> kbit/s. + +</div> + +<div class="cfgcmd"> + +set vpn sstp authentication protocols +\<pap | chap | mschap | mschap-v2\> + +Require the peer to authenticate itself using one of the following protocols: +pap, chap, mschap, mschap-v2. + +</div> + +### Client IP Pool Advanced Options + +<div class="cfgcmd"> + +set vpn sstp client-ip-pool \<POOL-NAME\> next-pool \<NEXT-POOL-NAME\> + +Use this command to define the next address pool name. + +</div> + +### PPP Advanced Options + +<div class="cfgcmd"> + +set vpn sstp ppp-options disable-ccp + +Disable Compression Control Protocol (CCP). +CCP is enabled by default. + +</div> + +<div class="cfgcmd"> + +set vpn sstp ppp-options interface-cache \<number\> + +Specifies number of interfaces to cache. This prevents interfaces from being +removed once the corresponding session is destroyed. Instead, interfaces are +cached for later use in new sessions. This should reduce the kernel-level +interface creation/deletion rate. +Default value is **0**. + +</div> + +<div class="cfgcmd"> + +set vpn sstp ppp-options ipv4 \<require | prefer | allow | deny\> + +Specifies IPv4 negotiation preference. + +- **require** - Require IPv4 negotiation +- **prefer** - Ask client for IPv4 negotiation, do not fail if it rejects +- **allow** - Negotiate IPv4 only if client requests (Default value) +- **deny** - Do not negotiate IPv4 + +</div> + +<div class="cfgcmd"> + +set vpn sstp ppp-options lcp-echo-failure \<number\> + +Defines the maximum <span class="title-ref">\<number\></span> of unanswered echo requests. Upon reaching the +value <span class="title-ref">\<number\></span>, the session will be reset. Default value is **3**. + +</div> + +<div class="cfgcmd"> + +set vpn sstp ppp-options lcp-echo-interval \<interval\> + +If this option is specified and is greater than 0, then the PPP module will +send LCP echo requests every <span class="title-ref">\<interval\></span> seconds. +Default value is **30**. + +</div> + +<div class="cfgcmd"> + +set vpn sstp ppp-options lcp-echo-timeout + +Specifies timeout in seconds to wait for any peer activity. If this option is +specified it turns on adaptive lcp echo functionality and "lcp-echo-failure" +is not used. Default value is **0**. + +</div> + +<div class="cfgcmd"> + +set vpn sstp ppp-options min-mtu \<number\> + +Defines the minimum acceptable MTU. If a client tries to negotiate an MTU +lower than this it will be NAKed, and disconnected if it rejects a greater +MTU. +Default value is **100**. + +</div> + +<div class="cfgcmd"> + +set vpn sstp ppp-options mppe \<require | prefer | deny\> + +Specifies `MPPE (Microsoft Point-to-Point Encryption)` negotiation +preference. + +- **require** - ask client for mppe, if it rejects drop connection +- **prefer** - ask client for mppe, if it rejects don't fail. (Default value) +- **deny** - deny mppe + +Default behavior - don't ask the client for mppe, but allow it if the client +wants. +Please note that RADIUS may override this option by MS-MPPE-Encryption-Policy +attribute. + +</div> + +<div class="cfgcmd"> + +set vpn sstp ppp-options mru \<number\> + +Defines preferred MRU. By default is not defined. + +</div> + +### Global Advanced options + +<div class="cfgcmd"> + +set vpn sstp description \<description\> + +Set description. + +</div> + +<div class="cfgcmd"> + +set vpn sstp limits burst \<value\> + +Burst count + +</div> + +<div class="cfgcmd"> + +set vpn sstp limits connection-limit \<value\> + +Maximum accepted connection rate (e.g. 1/min, 60/sec) + +</div> + +<div class="cfgcmd"> + +set vpn sstp limits timeout \<value\> + +Timeout in seconds + +</div> + +<div class="cfgcmd"> + +set vpn sstp mtu + +Maximum Transmission Unit (MTU) (default: **1500**) + +</div> + +<div class="cfgcmd"> + +set vpn sstp max-concurrent-sessions + +Maximum number of concurrent session start attempts + +</div> + +<div class="cfgcmd"> + +set vpn sstp name-server \<address\> + +Connected clients should use <span class="title-ref">\<address\></span> as their DNS server. This command +accepts both IPv4 and IPv6 addresses. Up to two nameservers can be configured +for IPv4, up to three for IPv6. + +</div> + +<div class="cfgcmd"> + +set vpn sstp shaper fwmark \<1-2147483647\> + +Match firewall mark value + +</div> + +<div class="cfgcmd"> + +set vpn sstp snmp master-agent + +Enable SNMP + +</div> + +<div class="cfgcmd"> + +set vpn sstp wins-server \<address\> + +Windows Internet Name Service (WINS) servers propagated to client + +</div> + +<div class="cfgcmd"> + +set vpn sstp host-name \<hostname\> + +If this option is given, only SSTP connections to the specified host +and with the same TLS SNI will be allowed. + +</div> + +## Configuring SSTP client + +Once you have setup your SSTP server there comes the time to do some basic +testing. The Linux client used for testing is called [sstpc](https://github.com/reliablehosting/sstp-client). [sstpc](https://github.com/reliablehosting/sstp-client) requires a +PPP configuration/peer file. + +If you use a self-signed certificate, do not forget to install CA on the client side. + +The following PPP configuration tests MSCHAP-v2: + +``` none +$ cat /etc/ppp/peers/vyos +usepeerdns +#require-mppe +#require-pap +require-mschap-v2 +noauth +lock +refuse-pap +refuse-eap +refuse-chap +refuse-mschap +#refuse-mschap-v2 +nobsdcomp +nodeflate +debug +``` + +You can now "dial" the peer with the follwoing command: `sstpc --log-level 4 --log-stderr --user vyos --password vyos vpn.example.com -- call vyos`. + +A connection attempt will be shown as: + +``` none +$ sstpc --log-level 4 --log-stderr --user vyos --password vyos vpn.example.com -- call vyos + +Mar 22 13:29:12 sstpc[12344]: Resolved vpn.example.com to 192.0.2.1 +Mar 22 13:29:12 sstpc[12344]: Connected to vpn.example.com +Mar 22 13:29:12 sstpc[12344]: Sending Connect-Request Message +Mar 22 13:29:12 sstpc[12344]: SEND SSTP CRTL PKT(14) +Mar 22 13:29:12 sstpc[12344]: TYPE(1): CONNECT REQUEST, ATTR(1): +Mar 22 13:29:12 sstpc[12344]: ENCAP PROTO(1): 6 +Mar 22 13:29:12 sstpc[12344]: RECV SSTP CRTL PKT(48) +Mar 22 13:29:12 sstpc[12344]: TYPE(2): CONNECT ACK, ATTR(1): +Mar 22 13:29:12 sstpc[12344]: CRYPTO BIND REQ(4): 40 +Mar 22 13:29:12 sstpc[12344]: Started PPP Link Negotiation +Mar 22 13:29:15 sstpc[12344]: Sending Connected Message +Mar 22 13:29:15 sstpc[12344]: SEND SSTP CRTL PKT(112) +Mar 22 13:29:15 sstpc[12344]: TYPE(4): CONNECTED, ATTR(1): +Mar 22 13:29:15 sstpc[12344]: CRYPTO BIND(3): 104 +Mar 22 13:29:15 sstpc[12344]: Connection Established + +$ ip addr show ppp0 +164: ppp0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1452 qdisc fq_codel state UNKNOWN group default qlen 3 + link/ppp promiscuity 0 + inet 100.64.2.2 peer 100.64.1.1/32 scope global ppp0 + valid_lft forever preferred_lft forever +``` + +## Monitoring + +<div class="opcmd"> + +show sstp-server sessions + +Use this command to locally check the active sessions in the SSTP +server. + +</div> + +``` none +vyos@vyos:~$ show sstp-server sessions + ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes +--------+----------+----------+-----+--------+----------------+------------+--------+----------+----------+---------- + sstp0 | test | 10.0.0.2 | | | 192.168.10.100 | | active | 00:15:46 | 16.3 KiB | 210 B +``` + +``` none +vyos@vyos:~$ show sstp-server statistics + uptime: 0.01:21:54 +cpu: 0% +mem(rss/virt): 6688/100464 kB +core: + mempool_allocated: 149420 + mempool_available: 146092 + thread_count: 1 + thread_active: 1 + context_count: 6 + context_sleeping: 0 + context_pending: 0 + md_handler_count: 7 + md_handler_pending: 0 + timer_count: 2 + timer_pending: 0 +sessions: + starting: 0 + active: 1 + finishing: 0 +sstp: + starting: 0 + active: 1 +``` + +## Troubleshooting + +``` none +vyos@vyos:~$sudo journalctl -u accel-ppp@sstp -b 0 + +Feb 28 17:03:04 vyos accel-sstp[2492]: sstp: new connection from 192.168.10.100:49852 +Feb 28 17:03:04 vyos accel-sstp[2492]: sstp: starting +Feb 28 17:03:04 vyos accel-sstp[2492]: sstp: started +Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [HTTP <SSTP_DUPLEX_POST /sra_{BA195980-CD49-458b-9E23-C84EE0ADCD75}/ HTTP/1.1>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [HTTP <SSTPCORRELATIONID: {48B82435-099A-4158-A987-052E7570CFAA}>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [HTTP <Content-Length: 18446744073709551615>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [HTTP <Host: vyos.io>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [HTTP <HTTP/1.1 200 OK>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [HTTP <Date: Wed, 28 Feb 2024 17:03:04 GMT>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [HTTP <Content-Length: 18446744073709551615>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [SSTP SSTP_MSG_CALL_CONNECT_REQUEST] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [SSTP SSTP_MSG_CALL_CONNECT_ACK] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: lcp_layer_init +Feb 28 17:03:04 vyos accel-sstp[2492]: :: auth_layer_init +Feb 28 17:03:04 vyos accel-sstp[2492]: :: ccp_layer_init +Feb 28 17:03:04 vyos accel-sstp[2492]: :: ipcp_layer_init +Feb 28 17:03:04 vyos accel-sstp[2492]: :: ipv6cp_layer_init +Feb 28 17:03:04 vyos accel-sstp[2492]: :: ppp establishing +Feb 28 17:03:04 vyos accel-sstp[2492]: :: lcp_layer_start +Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [LCP ConfReq id=56 <auth PAP> <mru 1452> <magic 1cd9ad05>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [LCP ConfReq id=0 <mru 4091> <magic 345f64ca> <pcomp> <accomp> < d 3 6 >] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [LCP ConfRej id=0 <pcomp> <accomp> < d 3 6 >] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [LCP ConfReq id=1 <mru 4091> <magic 345f64ca>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [LCP ConfNak id=1 <mru 1452>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [LCP ConfReq id=2 <mru 1452> <magic 345f64ca>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [LCP ConfAck id=2] +Feb 28 17:03:07 vyos accel-sstp[2492]: :: fsm timeout 9 +Feb 28 17:03:07 vyos accel-sstp[2492]: :: send [LCP ConfReq id=56 <auth PAP> <mru 1452> <magic 1cd9ad05>] +Feb 28 17:03:07 vyos accel-sstp[2492]: :: recv [LCP ConfAck id=56 <auth PAP> <mru 1452> <magic 1cd9ad05>] +Feb 28 17:03:07 vyos accel-sstp[2492]: :: lcp_layer_started +Feb 28 17:03:07 vyos accel-sstp[2492]: :: auth_layer_start +Feb 28 17:03:07 vyos accel-sstp[2492]: :: recv [LCP Ident id=3 <MSRASV5.20>] +Feb 28 17:03:07 vyos accel-sstp[2492]: :: recv [LCP Ident id=4 <MSRAS-0-MSEDGEWIN10>] +Feb 28 17:03:07 vyos accel-sstp[2492]: [50B blob data] +Feb 28 17:03:07 vyos accel-sstp[2492]: :: recv [PAP AuthReq id=3] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: connect: ppp0 <--> sstp(192.168.10.100:49852) +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: ppp connected +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [PAP AuthAck id=3 "Authentication succeeded"] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: test: authentication succeeded +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: auth_layer_started +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: ccp_layer_start +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: ipcp_layer_start +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: ipv6cp_layer_start +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: recv [SSTP SSTP_MSG_CALL_CONNECTED] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: IPV6CP: discarding packet +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [LCP ProtoRej id=88 <8057>] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: recv [IPCP ConfReq id=7 <addr 0.0.0.0> <dns1 0.0.0.0> <wins1 0.0.0.0> <dns2 0.0.0.0> <wins2 0.0.0.0>] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [IPCP ConfReq id=25 <addr 10.0.0.1>] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [IPCP ConfRej id=7 <dns1 0.0.0.0> <wins1 0.0.0.0> <dns2 0.0.0.0> <wins2 0.0.0.0>] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: recv [IPCP ConfAck id=25 <addr 10.0.0.1>] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: recv [IPCP ConfReq id=8 <addr 0.0.0.0>] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [IPCP ConfNak id=8 <addr 10.0.0.5>] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: recv [IPCP ConfReq id=9 <addr 10.0.0.5>] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [IPCP ConfAck id=9] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: ipcp_layer_started +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: rename interface to 'sstp0' +Feb 28 17:03:07 vyos accel-sstp[2492]: sstp0:test: sstp: ppp: started +``` diff --git a/docs/configuration/vrf/md-index.md b/docs/configuration/vrf/md-index.md new file mode 100644 index 00000000..7ab24fc2 --- /dev/null +++ b/docs/configuration/vrf/md-index.md @@ -0,0 +1,694 @@ +lastproofread +2021-07-07 + +# VRF + +`VRF (Virtual Routing and Forwarding)` devices combined with ip rules +provides the ability to create virtual routing and forwarding domains (aka +VRFs, VRF-lite to be specific) in the Linux network stack. One use case is the +multi-tenancy problem where each tenant has their own unique routing tables and +in the very least need different default gateways. + +## Configuration + +A VRF device is created with an associated route table. Network interfaces are +then enslaved to a VRF device. + +<div class="cfgcmd"> + +set vrf name \<name\> table \<id\> + +Create a new VRF instance with <span class="title-ref">\<name\></span> and <span class="title-ref">\<id\></span>. The name is used when placing +individual interfaces into the VRF. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +A routing table ID can not be modified once it is assigned. It can +only be changed by deleting and re-adding the VRF instance. + +</div> + +</div> + +<div class="cfgcmd"> + +set vrf bind-to-all + +By default the scope of the port bindings for unbound sockets is limited to +the default VRF. That is, it will not be matched by packets arriving on +interfaces enslaved to a VRF and processes may bind to the same port if +they bind to a VRF. + +TCP & UDP services running in the default VRF context (ie., not bound to any +VRF device) can work across all VRF domains by enabling this option. + +</div> + +### Zebra/Kernel route filtering + +Zebra supports prefix-lists and Route Mapss to match routes received from +other FRR components. The permit/deny facilities provided by these commands +can be used to filter which routes zebra will install in the kernel. + +<div class="cfgcmd"> + +set vrf \<name\> ip protocol \<protocol\> route-map \<route-map\> + +Apply a route-map filter to routes for the specified protocol. + +The following protocols can be used: any, babel, bgp, connected, eigrp, +isis, kernel, ospf, rip, static, table + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you choose any as the option that will cause all protocols that +are sending routes to zebra. + +</div> + +</div> + +<div class="cfgcmd"> + +set vrf \<name\> ipv6 protocol \<protocol\> route-map \<route-map\> + +Apply a route-map filter to routes for the specified protocol. + +The following protocols can be used: any, babel, bgp, connected, isis, +kernel, ospfv3, ripng, static, table + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you choose any as the option that will cause all protocols that +are sending routes to zebra. + +</div> + +</div> + +### Nexthop Tracking + +Nexthop tracking resolve nexthops via the default route by default. This is enabled +by default for a traditional profile of FRR which we use. It and can be disabled if +you do not wan't to e.g. allow BGP to peer across the default route. + +<div class="cfgcmd"> + +set vrf name \<name\> ip nht no-resolve-via-default + +Do not allow IPv4 nexthop tracking to resolve via the default route. This +parameter is configured per-VRF, so the command is also available in the VRF +subnode. + +</div> + +<div class="cfgcmd"> + +set vrf name \<name\> ipv6 nht no-resolve-via-default + +Do not allow IPv4 nexthop tracking to resolve via the default route. This +parameter is configured per-VRF, so the command is also available in the VRF +subnode. + +</div> + +### Interfaces + +When VRFs are used it is not only mandatory to create a VRF but also the VRF +itself needs to be assigned to an interface. + +<div class="cfgcmd"> + +set interfaces \<dummy | ethernet | bonding | bridge | pppoe\> +\<interface\> vrf \<name\> + +Assign interface identified by <span class="title-ref">\<interface\></span> to VRF named <span class="title-ref">\<name\></span>. + +</div> + +### Routing + +<div class="note"> + +<div class="title"> + +Note + +</div> + +VyOS 1.4 (sagitta) introduced dynamic routing support for VRFs. + +</div> + +Currently dynamic routing is supported for the following protocols: + +- `routing-bgp` +- `routing-isis` +- `routing-ospf` +- `routing-ospfv3` +- `routing-static` + +The CLI configuration is same as mentioned in above articles. The only +difference is, that each routing protocol used, must be prefixed with the <span class="title-ref">vrf +name \<name\></span> command. + +#### Example + +The following commands would be required to set options for a given dynamic +routing protocol inside a given vrf: + +- `routing-bgp`: `set vrf name <name> protocols bgp ...` +- `routing-isis`: `set vrf name <name> protocols isis ...` +- `routing-ospf`: `set vrf name <name> protocols ospf ...` +- `routing-ospfv3`: `set vrf name <name> protocols ospfv3 ...` +- `routing-static`: `set vrf name <name> protocols static ...` + +## Operation + +It is not sufficient to only configure a VRF but VRFs must be maintained, too. +For VRF maintenance the following operational commands are in place. + +<div class="opcmd"> + +show vrf + +Lists VRFs that have been created + +``` none +vyos@vyos:~$ show vrf +VRF name state mac address flags interfaces +-------- ----- ----------- ----- ---------- +blue up 00:53:12:d8:74:24 noarp,master,up,lower_up dum200,eth0.302 +red up 00:53:de:02:df:aa noarp,master,up,lower_up dum100,eth0.300,bond0.100,peth0 +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Command should probably be extended to list also the real +interfaces assigned to this one VRF to get a better overview. + +</div> + +</div> + +<div class="opcmd"> + +show vrf \<name\> + +``` none +vyos@vyos:~$ show vrf name blue +VRF name state mac address flags interfaces +-------- ----- ----------- ----- ---------- +blue up 00:53:12:d8:74:24 noarp,master,up,lower_up dum200,eth0.302 +``` + +</div> + +<div class="opcmd"> + +show ip route vrf \<name\> + +Display IPv4 routing table for VRF identified by <span class="title-ref">\<name\></span>. + +``` none +vyos@vyos:~$ show ip route vrf blue +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued route, r - rejected route + +VRF blue: +K 0.0.0.0/0 [255/8192] unreachable (ICMP unreachable), 00:00:50 +S>* 172.16.0.0/16 [1/0] via 192.0.2.1, dum1, 00:00:02 +C>* 192.0.2.0/24 is directly connected, dum1, 00:00:06 +``` + +</div> + +<div class="opcmd"> + +show ipv6 route vrf \<name\> + +Display IPv6 routing table for VRF identified by <span class="title-ref">\<name\></span>. + +``` none +vyos@vyos:~$ show ipv6 route vrf red +Codes: K - kernel route, C - connected, S - static, R - RIPng, + O - OSPFv3, I - IS-IS, B - BGP, N - NHRP, T - Table, + v - VNC, V - VNC-Direct, A - Babel, D - SHARP, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued route, r - rejected route + +VRF red: +K ::/0 [255/8192] unreachable (ICMP unreachable), 00:43:20 +C>* 2001:db8::/64 is directly connected, dum1, 00:02:19 +C>* fe80::/64 is directly connected, dum1, 00:43:19 +K>* ff00::/8 [0/256] is directly connected, dum1, 00:43:19 +``` + +</div> + +<div class="opcmd"> + +ping \<host\> vrf \<name\> + +The ping command is used to test whether a network host is reachable or not. + +Ping uses ICMP protocol's mandatory ECHO_REQUEST datagram to elicit an +ICMP ECHO_RESPONSE from a host or gateway. ECHO_REQUEST datagrams (pings) +will have an IP and ICMP header, followed by "struct timeval" and an +arbitrary number of pad bytes used to fill out the packet. + +When doing fault isolation with ping, you should first run it on the local +host, to verify that the local network interface is up and running. Then, +continue with hosts and gateways further down the road towards your +destination. Round-trip time and packet loss statistics are computed. + +Duplicate packets are not included in the packet loss calculation, although +the round-trip time of these packets is used in calculating the minimum/ +average/maximum round-trip time numbers. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Ping command can be interrupted at any given time using `<Ctrl>+c`. +A brief statistic is shown afterwards. + +</div> + +``` none +vyos@vyos:~$ ping 192.0.2.1 vrf red +PING 192.0.2.1 (192.0.2.1) 56(84) bytes of data. +64 bytes from 192.0.2.1: icmp_seq=1 ttl=64 time=0.070 ms +64 bytes from 192.0.2.1: icmp_seq=2 ttl=64 time=0.078 ms +^C +--- 192.0.2.1 ping statistics --- +2 packets transmitted, 2 received, 0% packet loss, time 4ms +rtt min/avg/max/mdev = 0.070/0.074/0.078/0.004 ms +``` + +</div> + +<div class="opcmd"> + +traceroute vrf \<name\> \[ipv4 | ipv6\] \<host\> + +Displays the route packets taken to a network host utilizing VRF instance +identified by <span class="title-ref">\<name\></span>. When using the IPv4 or IPv6 option, displays the +route packets taken to the given hosts IP address family. This option is +useful when the host is specified as a hostname rather than an IP address. + +</div> + +<div class="opcmd"> + +force vrf \<name\> + +Join a given VRF. This will open a new subshell within the specified VRF. + +The prompt is adjusted to reflect this change in both config and op-mode. + +``` none +vyos@vyos:~$ force vrf blue +vyos@vyos(vrf:blue):~$ +``` + +</div> + +## Example + +### VRF route leaking + +The following example topology was built using EVE-NG. + +<figure> +<img src="/_static/images/vrf-example-topology-01.webp" alt="VRF topology example" /> +<figcaption>VRF route leaking</figcaption> +</figure> + +- PC1 is in the `default` VRF and acting as e.g. a "fileserver" +- PC2 is in VRF `blue` which is the development department +- PC3 and PC4 are connected to a bridge device on router `R1` which is in VRF + `red`. Say this is the HR department. +- R1 is managed through an out-of-band network that resides in VRF `mgmt` + +#### Configuration + +> ``` none +> set interfaces bridge br10 address '10.30.0.254/24' +> set interfaces bridge br10 member interface eth3 +> set interfaces bridge br10 member interface eth4 +> set interfaces bridge br10 vrf 'red' +> +> set interfaces ethernet eth0 address 'dhcp' +> set interfaces ethernet eth0 vrf 'mgmt' +> set interfaces ethernet eth1 address '10.0.0.254/24' +> set interfaces ethernet eth2 address '10.20.0.254/24' +> set interfaces ethernet eth2 vrf 'blue' +> +> set protocols static route 10.20.0.0/24 interface eth2 vrf 'blue' +> set protocols static route 10.30.0.0/24 interface br10 vrf 'red' +> +> set service ssh disable-host-validation +> set service ssh vrf 'mgmt' +> +> set system name-server 'eth0' +> +> set vrf name blue protocols static route 10.0.0.0/24 interface eth1 vrf 'default' +> set vrf name blue table '3000' +> set vrf name mgmt table '1000' +> set vrf name red protocols static route 10.0.0.0/24 interface eth1 vrf 'default' +> set vrf name red table '2000' +> ``` + +### VRF and NAT + +#### Configuration + +> ``` none +> set interfaces ethernet eth0 address '172.16.50.12/24' +> set interfaces ethernet eth0 vrf 'red' +> +> set interfaces ethernet eth1 address '192.168.130.100/24' +> set interfaces ethernet eth1 vrf 'blue' +> +> set nat destination rule 110 description 'NAT ssh- INSIDE' +> set nat destination rule 110 destination port '2022' +> set nat destination rule 110 inbound-interface 'eth0' +> set nat destination rule 110 protocol 'tcp' +> set nat destination rule 110 translation address '192.168.130.40' +> +> set nat source rule 100 outbound-interface 'eth0' +> set nat source rule 100 protocol 'all' +> set nat source rule 100 source address '192.168.130.0/24' +> set nat source rule 100 translation address 'masquerade' +> +> set service ssh vrf 'red' +> +> set vrf bind-to-all +> set vrf name blue protocols static route 0.0.0.0/0 next-hop 172.16.50.1 vrf 'red' +> set vrf name blue protocols static route 172.16.50.0/24 interface eth0 vrf 'red' +> set vrf name blue table '1010' +> +> set vrf name red protocols static route 0.0.0.0/0 next-hop 172.16.50.1 +> set vrf name red protocols static route 192.168.130.0/24 interface eth1 vrf 'blue' +> set vrf name red table '2020' +> ``` + +#### Operation + +After committing the configuration we can verify all leaked routes are +installed, and try to ICMP ping PC1 from PC3. + +> ``` none +> PCS> ping 10.0.0.1 +> +> 84 bytes from 10.0.0.1 icmp_seq=1 ttl=63 time=1.943 ms +> 84 bytes from 10.0.0.1 icmp_seq=2 ttl=63 time=1.618 ms +> 84 bytes from 10.0.0.1 icmp_seq=3 ttl=63 time=1.745 ms +> ``` +> +> ``` none +> VPCS> show ip +> +> NAME : VPCS[1] +> IP/MASK : 10.30.0.1/24 +> GATEWAY : 10.30.0.254 +> DNS : +> MAC : 00:50:79:66:68:0f +> ``` + +##### VRF default routing table + +> ``` none +> vyos@R1:~$ show ip route +> Codes: K - kernel route, C - connected, S - static, R - RIP, +> O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, +> T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, +> F - PBR, f - OpenFabric, +> > - selected route, * - FIB route, q - queued, r - rejected, b - backup +> +> C>* 10.0.0.0/24 is directly connected, eth1, 00:07:44 +> S>* 10.20.0.0/24 [1/0] is directly connected, eth2 (vrf blue), weight 1, 00:07:38 +> S>* 10.30.0.0/24 [1/0] is directly connected, br10 (vrf red), weight 1, 00:07:38 +> ``` + +##### VRF red routing table + +> ``` none +> vyos@R1:~$ show ip route vrf red +> Codes: K - kernel route, C - connected, S - static, R - RIP, +> O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, +> T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, +> F - PBR, f - OpenFabric, +> > - selected route, * - FIB route, q - queued, r - rejected, b - backup +> +> VRF red: +> K>* 0.0.0.0/0 [255/8192] unreachable (ICMP unreachable), 00:07:57 +> S>* 10.0.0.0/24 [1/0] is directly connected, eth1 (vrf default), weight 1, 00:07:40 +> C>* 10.30.0.0/24 is directly connected, br10, 00:07:54 +> ``` + +##### VRF blue routing table + +> ``` none +> vyos@R1:~$ show ip route vrf blue +> Codes: K - kernel route, C - connected, S - static, R - RIP, +> O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, +> T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, +> F - PBR, f - OpenFabric, +> > - selected route, * - FIB route, q - queued, r - rejected, b - backup +> +> VRF blue: +> K>* 0.0.0.0/0 [255/8192] unreachable (ICMP unreachable), 00:08:00 +> S>* 10.0.0.0/24 [1/0] is directly connected, eth1 (vrf default), weight 1, 00:07:44 +> C>* 10.20.0.0/24 is directly connected, eth2, 00:07:53 +> ``` + +# L3VPN VRFs + +`L3VPN VRFs ( Layer 3 Virtual Private Networks )` bgpd supports for +IPv4 RFC 4364 and IPv6 RFC 4659. L3VPN routes, and their associated VRF +MPLS labels, can be distributed to VPN SAFI neighbors in the default, i.e., +non VRF, BGP instance. VRF MPLS labels are reached using core MPLS labels +which are distributed using LDP or BGP labeled unicast. +bgpd also supports inter-VRF route leaking. + +## VRF Route Leaking + +BGP routes may be leaked (i.e. copied) between a unicast VRF RIB and the VPN +SAFI RIB of the default VRF for use in MPLS-based L3VPNs. Unicast routes may +also be leaked between any VRFs (including the unicast RIB of the default BGP +instance). A shortcut syntax is also available for specifying leaking from +one VRF to another VRF using the default instance’s VPN RIB as the intemediary +. A common application of the VRF-VRF feature is to connect a customer’s +private routing domain to a provider’s VPN service. Leaking is configured from +the point of view of an individual VRF: import refers to routes leaked from VPN +to a unicast VRF, whereas export refers to routes leaked from a unicast VRF to +VPN. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Routes exported from a unicast VRF to the VPN RIB must be augmented +by two parameters: + +an RD / RTLIST + +Configuration for these exported routes must, at a minimum, specify +these two parameters. + +</div> + +## Configuration + +Configuration of route leaking between a unicast VRF RIB and the VPN SAFI RIB +of the default VRF is accomplished via commands in the context of a VRF +address-family. + +<div class="cfgcmd"> + +set vrf name \<name\> protocols bgp address-family +\<ipv4-unicast[|ipv6-unicast\> rd vpn export \<asn:nn|](##SUBST##|ipv6-unicast> rd vpn export <asn:nn|)address:nn\> + +Specifies the route distinguisher to be added to a route exported from the +current unicast VRF to VPN. + +</div> + +<div class="cfgcmd"> + +set vrf name \<name\> protocols bgp address-family +\<ipv4-unicast[|ipv6-unicast\> route-target vpn \<import|](##SUBST##|ipv6-unicast> route-target vpn <import|)export|both\> +\[RTLIST\] + +Specifies the route-target list to be attached to a route (export) or the +route-target list to match against (import) when exporting/importing +between the current unicast VRF and VPN.The RTLIST is a space-separated +list of route-targets, which are BGP extended community values as +described in Extended Communities Attribute. + +</div> + +<div class="cfgcmd"> + +set vrf name \<name\> protocols bgp address-family +\<ipv4-unicast[|ipv6-unicast\> label vpn export \<0-1048575|](##SUBST##|ipv6-unicast> label vpn export <0-1048575|)auto\> + +Enables an MPLS label to be attached to a route exported from the current +unicast VRF to VPN. If the value specified is auto, the label value is +automatically assigned from a pool maintained. + +</div> + +<div class="cfgcmd"> + +set vrf name \<name\> protocols bgp address-family +\<ipv4-unicast|ipv6-unicast\> label vpn allocation-mode per-nexthop + +Select how labels are allocated in the given VRF. By default, the per-vrf +mode is selected, and one label is used for all prefixes from the VRF. The +per-nexthop will use a unique label for all prefixes that are reachable via +the same nexthop. + +</div> + +<div class="cfgcmd"> + +set vrf name \<name\> protocols bgp address-family +\<ipv4-unicast[|ipv6-unicast\> route-map vpn \<import|](##SUBST##|ipv6-unicast> route-map vpn <import|)export\> +\[route-map \<name\>\] + +Specifies an optional route-map to be applied to routes imported or +exported between the current unicast VRF and VPN. + +</div> + +<div class="cfgcmd"> + +set vrf name \<name\> protocols bgp address-family +\<ipv4-unicast[|ipv6-unicast\> \<import|](##SUBST##|ipv6-unicast> <import|)export\> vpn + +Enables import or export of routes between the current unicast VRF and VPN. + +</div> + +<div class="cfgcmd"> + +set vrf name \<name\> protocols bgp address-family +\<ipv4-unicast|ipv6-unicast\> import vrf \<name\> + +Shortcut syntax for specifying automatic leaking from vrf VRFNAME to the +current VRF using the VPN RIB as intermediary. The RD and RT are auto +derived and should not be specified explicitly for either the source or +destination VRF’s. + +</div> + +<div class="cfgcmd"> + +set vrf name \<name\> protocols bgp address-family +\<ipv4-unicast|ipv6-unicast\> route-map vrf import +\[route-map \<name\>\] + +Specifies an optional route-map to be applied to routes imported from VRFs. + +</div> + +<div class="cfgcmd"> + +set vrf name \<name\> protocols bgp interface \<interface\> mpls +forwarding + +It is possible to permit BGP install VPN prefixes without transport labels. +This configuration will install VPN prefixes originated from an e-bgp session, +and with the next-hop directly connected. + +</div> + +## Operation + +It is not sufficient to only configure a L3VPN VRFs but L3VPN VRFs must be +maintained, too.For L3VPN VRF maintenance the following operational commands +are in place. + +<div class="opcmd"> + +show bgp \<ipv4|ipv6\> vpn + +Print active IPV4 or IPV6 routes advertised via the VPN SAFI. + +``` none +BGP table version is 2, local router ID is 10.0.1.1, vrf id 0 +Default local pref 100, local AS 65001 +Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, + i internal, r RIB-failure, S Stale, R Removed +Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self +Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path +Route Distinguisher: 10.50.50.1:1011 +*>i10.50.50.0/24 10.0.0.7 0 100 0 i + UN=10.0.0.7 EC{65035:1011} label=80 type=bgp, subtype=0 +Route Distinguisher: 10.60.60.1:1011 +*>i10.60.60.0/24 10.0.0.10 0 100 0 i + UN=10.0.0.10 EC{65035:1011} label=80 type=bgp, subtype=0 +``` + +</div> + +<div class="opcmd"> + +show bgp \<ipv4|ipv6\> vpn summary + +Print a summary of neighbor connections for the specified AFI/SAFI +combination. + +``` none +``` + +BGP router identifier 10.0.1.1, local AS number 65001 vrf-id 0 +BGP table version 0 +RIB entries 9, using 1728 bytes of memory +Peers 4, using 85 KiB of memory +Peer groups 1, using 64 bytes of memory + +Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd PfxSnt +10.0.0.7 4 65001 2860 2870 0 0 0 1d23h34m 2 10 + +</div> diff --git a/docs/contributing/md-build-vyos.md b/docs/contributing/md-build-vyos.md new file mode 100644 index 00000000..c8074bd7 --- /dev/null +++ b/docs/contributing/md-build-vyos.md @@ -0,0 +1,876 @@ +# Build VyOS + +## Prerequisites + +There are different ways you can build VyOS. + +Building using a `build_docker` container, although not the only way, +is the easiest way as all dependencies are managed for you. However, you can +also set up your own build machine and run a `build_native`. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Starting with VyOS 1.2 the release model of VyOS has changed. VyOS +is now **free as in speech, but not as in beer**. This means that while +VyOS is still an open source project, the release ISOs are no longer free +and can only be obtained via subscription, or by contributing to the +community. + +The source code remains public and an ISO can be built using the process +outlined in this chapter. + +</div> + +### Native Build + +To build VyOS natively you require a properly configured build host with the +following Debian versions installed: + +- Debian Jessie for VyOS 1.2 (crux) +- Debian Buster for VyOS 1.3 (equuleus) +- Debian Bookworm for VyOS 1.4 (sagitta) +- Debian Bookworm or updated for VyOS 1.5 (circinus, current) - aka the + rolling release + +To start, clone the repository to your local machine: + +``` none +# For VyOS 1.2 (crux) +$ git clone -b crux --single-branch https://github.com/vyos/vyos-build + +# For VyOS 1.3 (equuleus) +$ git clone -b equuleus --single-branch https://github.com/vyos/vyos-build + +# For VyOS 1.4 (sagitta) +$ git clone -b sagitta --single-branch https://github.com/vyos/vyos-build + +# For VyOS 1.5 (circinus, current) +$ git clone -b current --single-branch https://github.com/vyos/vyos-build + +$ cd vyos-build + +# For VyOS 1.2 (crux) and VyOS 1.3 (equuleus) +$ ./configure --architecture amd64 --build-by "j.randomhacker@vyos.io" +$ sudo make iso + +# For VyOS 1.4 (sagitta) and VyOS 1.5 (circinus, current) +$ sudo make clean +$ sudo ./build-vyos-image iso --architecture amd64 --build-by "j.randomhacker@vyos.io" +``` + +For the packages required, you can refer to the `docker/Dockerfile` file +in the [repository](https://github.com/vyos/vyos-build). The `./build-vyos-image` script will also warn you if any +dependencies are missing. + +### Docker + +This will guide you through the process of building a VyOS ISO using [Docker](https://www.docker.com). +This process has been tested on clean installs of Debian Bullseye (11) and +Bookworm (12). + +Installing [Docker](https://www.docker.com) and prerequisites: + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +Due to the updated version of Docker, the following examples may +become invalid. + +Due to differences in version updates and build processes, content related +to VyOS 1.3 and below is no longer included below. + +</div> + +[On Debian](https://docs.docker.com/engine/install/debian/) + +``` none +# Add Docker's official GPG key: +$ sudo apt-get update +$ sudo apt-get install ca-certificates curl gnupg +$ sudo install -m 0755 -d /etc/apt/keyrings +$ curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg +$ sudo chmod a+r /etc/apt/keyrings/docker.gpg + +# Add the repository to Apt sources: +$ echo \ + "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \ + https://download.docker.com/linux/debian \ + $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \ + sudo tee /etc/apt/sources.list.d/docker.list > /dev/null + +$ sudo apt-get update +$ sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin +``` + +To be able to use [Docker](https://www.docker.com) without `sudo`, the current non-root user must be +added to the `docker` group by calling: `sudo usermod -aG docker yourusername`. + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +Doing so grants privileges equivalent to the `root` user! It is +recommended to remove the non-root user from the `docker` group after +building the VyOS ISO. See also [Docker as non-root](https://docs.docker.com/engine/install/linux-postinstall). + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The build process needs to be built on a local file system, building +on SMB or NFS shares will result in the container failing to build properly! +VirtualBox Drive Share is also not an option as block device operations +are not implemented and the drive is always mounted as "nodev" + +</div> + +#### Build Container + +The container can be built by hand or by fetching the pre-built one from +DockerHub. Using the pre-built containers from the [VyOS DockerHub +organisation](https://hub.docker.com/u/vyos) will ensure that the container is always up-to-date. A rebuild +is triggered once the container changes (please note this will take 2-3 hours +after pushing to the vyos-build repository). + +##### Dockerhub + +To manually download the container from DockerHub, run: + +``` none +$ docker pull vyos/vyos-build:sagitta # For VyOS 1.4 +$ docker pull vyos/vyos-build:current # For rolling release +``` + +##### Build from source + +The container can also be built directly from source: + +``` none +# For VyOS 1.4 (sagitta) +$ git clone -b sagitta --single-branch https://github.com/vyos/vyos-build + +# For VyOS 1.5 (circinus, current) +$ git clone -b current --single-branch https://github.com/vyos/vyos-build + + +$ cd vyos-build +$ docker build -t vyos/vyos-build:sagitta docker # For VyOS 1.4 +$ docker build -t vyos/vyos-build:current docker # For rolling release +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Since VyOS has switched to Debian (12) Bookworm in its `current` +branch, It is recommended to use the official Docker Hub container image +to build `equleus` and `crux`. + +</div> + +#### Tips and Tricks + +You can create yourself some handy Bash aliases to always launch the latest - +per release train (<span class="title-ref">current</span> or <span class="title-ref">sagitta</span>) - container. Add the following to +your `.bash_aliases` file: + +``` none +alias vybld='docker pull vyos/vyos-build:current && docker run --rm -it \ + -v "$(pwd)":/vyos \ + -v "$HOME/.gitconfig":/etc/gitconfig \ + -v "$HOME/.bash_aliases":/home/vyos_bld/.bash_aliases \ + -v "$HOME/.bashrc":/home/vyos_bld/.bashrc \ + -w /vyos --privileged --sysctl net.ipv6.conf.lo.disable_ipv6=0 \ + -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) \ + vyos/vyos-build:current bash' + +alias vybld_sagitta='docker pull vyos/vyos-build:sagitta && docker run --rm -it \ + -v "$(pwd)":/vyos \ + -v "$HOME/.gitconfig":/etc/gitconfig \ + -v "$HOME/.bash_aliases":/home/vyos_bld/.bash_aliases \ + -v "$HOME/.bashrc":/home/vyos_bld/.bashrc \ + -w /vyos --privileged --sysctl net.ipv6.conf.lo.disable_ipv6=0 \ + -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) \ + vyos/vyos-build:sagitta bash' +``` + +Now you are prepared with two new aliases `vybld` and `vybld_sagitta` to +spawn your development containers in your current working directory. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Some VyOS packages (namely vyos-1x) come with build-time tests which +verify some of the internal library calls that they work as expected. Those +tests are carried out through the Python Unittest module. If you want to +build the `vyos-1x` package (which is our main development package) you +need to start your Docker container using the following argument: +`--sysctl net.ipv6.conf.lo.disable_ipv6=0`, otherwise those tests will +fail. + +</div> + +## Build ISO + +Now as you are aware of the prerequisites we can continue and build our own +ISO from source. For this we have to fetch the latest source code from GitHub. +Please note as this will differ for both <span class="title-ref">current</span> and <span class="title-ref">crux</span>. + +``` none +# For VyOS 1.4 (sagitta) +$ git clone -b sagitta --single-branch https://github.com/vyos/vyos-build + +# For VyOS 1.5 (circinus, current) +$ git clone -b current --single-branch https://github.com/vyos/vyos-build +``` + +Now a fresh build of the VyOS ISO can begin. Change directory to the +`vyos-build` directory and run: + +``` none +$ cd vyos-build + +# For VyOS 1.4 (sagitta) +$ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:sagitta bash + +# For VyOS 1.5 (circinus, current) +$ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:current bash +``` + +``` none +# For MacOS (crux, equuleus, sagitta) +$ git clone https://github.com/vyos/vyos-utils-misc +$ cd build-tools/macos-build + +# For VyOS 1.2 (crux) +$ os=jessie64 branch=crux make build + +# For VyOS 1.3 (equuleus) +$ os=buster64 branch=equuleus make build + +# For VyOS 1.4 (sagitta) +$ os=buster64 branch=sagitta make build +``` + +Start the build: + +``` none +# For VyOS 1.4 (sagitta) and For VyOS 1.5 (circinus, current) +vyos_bld@8153428c7e1f:/vyos$ sudo make clean +vyos_bld@8153428c7e1f:/vyos$ sudo ./build-vyos-image iso --architecture amd64 --build-by "j.randomhacker@vyos.io" +``` + +When the build is successful, the resulting iso can be found inside the +`build` directory as `live-image-[architecture].hybrid.iso`. + +Good luck! + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +Building VyOS on Windows WSL2 with Docker integrated into WSL2 will +work like a charm. No problems are known so far! + +</div> + +### Customize<span id="build source"></span> + +This ISO can be customized with the following list of configure options. +The full and current list can be generated with `./build-vyos-image --help`: + +``` none +$ vyos_bld@8153428c7e1f:/vyos$ sudo ./build-vyos-image --help + I: Checking if packages required for VyOS image build are installed + usage: build-vyos-image [-h] [--architecture ARCHITECTURE] + [--build-by BUILD_BY] [--debian-mirror DEBIAN_MIRROR] + [--debian-security-mirror DEBIAN_SECURITY_MIRROR] + [--pbuilder-debian-mirror PBUILDER_DEBIAN_MIRROR] + [--vyos-mirror VYOS_MIRROR] [--build-type BUILD_TYPE] + [--version VERSION] [--build-comment BUILD_COMMENT] [--debug] [--dry-run] + [--custom-apt-entry CUSTOM_APT_ENTRY] [--custom-apt-key CUSTOM_APT_KEY] + [--custom-package CUSTOM_PACKAGE] + [build_flavor] + + positional arguments: + build_flavor Build flavor + + optional arguments: + -h, --help show this help message and exit + --architecture ARCHITECTURE + Image target architecture (amd64 or arm64) + --build-by BUILD_BY Builder identifier (e.g. jrandomhacker@example.net) + --debian-mirror DEBIAN_MIRROR + Debian repository mirror + --debian-security-mirror DEBIAN_SECURITY_MIRROR + Debian security updates mirror + --pbuilder-debian-mirror PBUILDER_DEBIAN_MIRROR + Debian repository mirror for pbuilder env bootstrap + --vyos-mirror VYOS_MIRROR + VyOS package mirror + --build-type BUILD_TYPE + Build type, release or development + --version VERSION Version number (release builds only) + --build-comment BUILD_COMMENT + Optional build comment + --debug Enable debug output + --dry-run Check build configuration and exit + --custom-apt-entry CUSTOM_APT_ENTRY + Custom APT entry + --custom-apt-key CUSTOM_APT_KEY + Custom APT key file + --custom-package CUSTOM_PACKAGE + Custom package to install from repositories +``` + +#### ISO Build Issues + +There are (rare) situations where building an ISO image is not possible at all +due to a broken package feed in the background. APT is not very good at +reporting the root cause of the issue. Your ISO build will likely fail with a +more or less similar looking error message: + +``` none +The following packages have unmet dependencies: + vyos-1x : Depends: accel-ppp but it is not installable +E: Unable to correct problems, you have held broken packages. +P: Begin unmounting filesystems... +P: Saving caches... +Reading package lists... +Building dependency tree... +Reading state information... +Del frr-pythontools 7.5-20210215-00-g8a5d3b7cd-0 [38.9 kB] +Del accel-ppp 1.12.0-95-g59f8e1b [475 kB] +Del frr 7.5-20210215-00-g8a5d3b7cd-0 [2671 kB] +Del frr-snmp 7.5-20210215-00-g8a5d3b7cd-0 [55.1 kB] +Del frr-rpki-rtrlib 7.5-20210215-00-g8a5d3b7cd-0 [37.3 kB] +make: *** [Makefile:30: iso] Error 1 +(10:13) vyos_bld ece068908a5b:/vyos [current] # +``` + +To debug the build process and gain additional information of what could be the +root cause, you need to use <span class="title-ref">chroot</span> to change into the build directory. This is +explained in the following step by step procedure: + +``` none +vyos_bld ece068908a5b:/vyos [current] # sudo chroot build/chroot /bin/bash +``` + +We now need to mount some required, volatile filesystems + +``` none +(live)root@ece068908a5b:/# mount -t proc none /proc +(live)root@ece068908a5b:/# mount -t sysfs none /sys +(live)root@ece068908a5b:/# mount -t devtmpfs none /dev +``` + +We now are free to run any command we would like to use for debugging, e.g. +re-installing the failed package after updating the repository. + +``` none +(live)root@ece068908a5b:/# apt-get update; apt-get install vyos-1x +Get:1 file:/root/packages ./ InRelease +Ign:1 file:/root/packages ./ InRelease +Get:2 file:/root/packages ./ Release [1235 B] +Get:2 file:/root/packages ./ Release [1235 B] +Get:3 file:/root/packages ./ Release.gpg +Ign:3 file:/root/packages ./ Release.gpg +Hit:4 http://repo.powerdns.com/debian buster-rec-43 InRelease +Hit:5 http://repo.saltstack.com/py3/debian/10/amd64/archive/3002.2 buster InRelease +Hit:6 http://deb.debian.org/debian bullseye InRelease +Hit:7 http://deb.debian.org/debian buster InRelease +Hit:8 http://deb.debian.org/debian-security buster/updates InRelease +Hit:9 http://deb.debian.org/debian buster-updates InRelease +Hit:10 http://deb.debian.org/debian buster-backports InRelease +Hit:11 http://dev.packages.vyos.net/repositories/current current InRelease +Reading package lists... Done +N: Download is performed unsandboxed as root as file '/root/packages/./InRelease' couldn't be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied) +Reading package lists... Done +Building dependency tree +Reading state information... Done +Some packages could not be installed. This may mean that you have +requested an impossible situation or if you are using the unstable +distribution that some required packages have not yet been created +or been moved out of Incoming. +The following information may help to resolve the situation: + +The following packages have unmet dependencies: + vyos-1x : Depends: accel-ppp but it is not installable +E: Unable to correct problems, you have held broken packages. +``` + +Now it's time to fix the package mirror and rerun the last step until the +package installation succeeds again! + +### Linux Kernel + +The Linux kernel used by VyOS is heavily tied to the ISO build process. The +file `data/defaults.toml` hosts a TOML definition of the kernel version used +`kernel_version` and the `kernel_flavor` of the kernel which represents the +kernel's LOCAL_VERSION. Both together form the kernel version variable in the +system: + +``` none +vyos@vyos:~$ uname -r +6.1.52-amd64-vyos +``` + +- Accel-PPP +- Intel NIC drivers +- Inter QAT + +Each of those modules holds a dependency on the kernel version and if you are +lucky enough to receive an ISO build error which sounds like: + +``` none +I: Create initramfs if it does not exist. +Extra argument '6.1.52-amd64-vyos' +Usage: update-initramfs {-c|-d|-u} [-k version] [-v] [-b directory] +Options: + -k version Specify kernel version or 'all' + -c Create a new initramfs + -u Update an existing initramfs + -d Remove an existing initramfs + -b directory Set alternate boot directory + -v Be verbose +See update-initramfs(8) for further details. +E: config/hooks/live/17-gen_initramfs.chroot failed (exit non-zero). You should check for errors. +``` + +The most obvious reasons could be: + +- `vyos-build` repo is outdated, please `git pull` to update to the latest + release kernel version from us. +- You have your own custom kernel <span class="title-ref">\*.deb</span> packages in the <span class="title-ref">packages</span> folder but + neglected to create all required out-of tree modules like Accel-PPP, Intel + QAT or Intel NIC drivers + +#### Building The Kernel + +The kernel build is quite easy, most of the required steps can be found in the +`vyos-build/packages/linux-kernel/Jenkinsfile` but we will walk you through +it. + +Clone the kernel source to \`vyos-build/packages/linux-kernel/\`: + +``` none +$ cd vyos-build/packages/linux-kernel/ +$ git clone https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git +``` + +Check out the required kernel version - see `vyos-build/data/defaults.toml` +file (example uses kernel 4.19.146): + +``` none +$ cd vyos-build/packages/linux-kernel/linux +$ git checkout v4.19.146 +Checking out files: 100% (61536/61536), done. +Note: checking out 'v4.19.146'. + +You are in 'detached HEAD' state. You can look around, make experimental +changes and commit them, and you can discard any commits you make in this +state without impacting any branches by performing another checkout. + +If you want to create a new branch to retain commits you create, you may +do so (now or later) by using -b with the checkout command again. Example: + + git checkout -b <new-branch-name> + +HEAD is now at 015e94d0e37b Linux 4.19.146 +``` + +Now we can use the helper script `build-kernel.sh` which does all the +necessary voodoo by applying required patches from the +<span class="title-ref">vyos-build/packages/linux-kernel/patches</span> folder, copying our kernel +configuration `x86_64_vyos_defconfig` to the right location, and finally +building the Debian packages. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Building the kernel will take some time depending on the speed and +quantity of your CPU/cores and disk speed. Expect 20 minutes +(or even longer) on lower end hardware. + +</div> + +``` none +(18:59) vyos_bld 412374ca36b8:/vyos/vyos-build/packages/linux-kernel [current] # ./build-kernel.sh +I: Copy Kernel config (x86_64_vyos_defconfig) to Kernel Source +I: Apply Kernel patch: /vyos/vyos-build/packages/linux-kernel/patches/kernel/0001-VyOS-Add-linkstate-IP-device-attribute.patch +patching file Documentation/networking/ip-sysctl.txt +patching file include/linux/inetdevice.h +patching file include/linux/ipv6.h +patching file include/uapi/linux/ip.h +patching file include/uapi/linux/ipv6.h +patching file net/ipv4/devinet.c +Hunk #1 succeeded at 2319 (offset 1 line). +patching file net/ipv6/addrconf.c +patching file net/ipv6/route.c +I: Apply Kernel patch: /vyos/vyos-build/packages/linux-kernel/patches/kernel/0002-VyOS-add-inotify-support-for-stackable-filesystems-o.patch +patching file fs/notify/inotify/Kconfig +patching file fs/notify/inotify/inotify_user.c +patching file fs/overlayfs/super.c +Hunk #2 succeeded at 1713 (offset 9 lines). +Hunk #3 succeeded at 1739 (offset 9 lines). +Hunk #4 succeeded at 1762 (offset 9 lines). +patching file include/linux/inotify.h +I: Apply Kernel patch: /vyos/vyos-build/packages/linux-kernel/patches/kernel/0003-RFC-builddeb-add-linux-tools-package-with-perf.patch +patching file scripts/package/builddeb +I: make x86_64_vyos_defconfig + HOSTCC scripts/basic/fixdep + HOSTCC scripts/kconfig/conf.o + YACC scripts/kconfig/zconf.tab.c + LEX scripts/kconfig/zconf.lex.c + HOSTCC scripts/kconfig/zconf.tab.o + HOSTLD scripts/kconfig/conf +# +# configuration written to .config +# +I: Generate environment file containing Kernel variable +I: Build Debian Kernel package + UPD include/config/kernel.release +/bin/sh ./scripts/package/mkdebian +dpkg-buildpackage -r"fakeroot -u" -a$(cat debian/arch) -b -nc -uc +dpkg-buildpackage: info: source package linux-4.19.146-amd64-vyos +dpkg-buildpackage: info: source version 4.19.146-1 +dpkg-buildpackage: info: source distribution buster +dpkg-buildpackage: info: source changed by vyos_bld <christian@poessinger.com> +dpkg-buildpackage: info: host architecture amd64 +dpkg-buildpackage: warning: debian/rules is not executable; fixing that + dpkg-source --before-build . + debian/rules build +make KERNELRELEASE=4.19.146-amd64-vyos ARCH=x86 KBUILD_BUILD_VERSION=1 KBUILD_SRC= + SYSTBL arch/x86/include/generated/asm/syscalls_32.h + +... + +dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory +dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory +dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory +dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory +dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory +dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory +dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory +dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory +dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory +dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory +dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory +dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory +dpkg-shlibdeps: warning: package could avoid a useless dependency if /vyos/vyos-build/packages/linux-kernel/linux/debian/toolstmp/usr/bin/trace /vyos/vyos-build/packages/linux-kernel/linux/debian/toolstmp/usr/bin/perf were not linked against libcrypto.so.1.1 (they use none of the library's symbols) +dpkg-shlibdeps: warning: package could avoid a useless dependency if /vyos/vyos-build/packages/linux-kernel/linux/debian/toolstmp/usr/bin/trace /vyos/vyos-build/packages/linux-kernel/linux/debian/toolstmp/usr/bin/perf were not linked against libcrypt.so.1 (they use none of the library's symbols) +dpkg-deb: building package 'linux-tools-4.19.146-amd64-vyos' in '../linux-tools-4.19.146-amd64-vyos_4.19.146-1_amd64.deb'. + dpkg-genbuildinfo --build=binary + dpkg-genchanges --build=binary >../linux-4.19.146-amd64-vyos_4.19.146-1_amd64.changes +dpkg-genchanges: warning: package linux-image-4.19.146-amd64-vyos-dbg in control file but not in files list +dpkg-genchanges: info: binary-only upload (no source code included) + dpkg-source --after-build . +dpkg-buildpackage: info: binary-only upload (no source included) +``` + +In the end you will be presented with the kernel binary packages which you can +then use in your custom ISO build process, by placing all the <span class="title-ref">\*.deb</span> files in +the vyos-build/packages folder where they will be used automatically when +building VyOS as documented above. + +##### Firmware + +If you upgrade your kernel or include new drivers you may need new firmware. +Build a new `vyos-linux-firmware` package with the included helper scripts. + +``` none +$ cd vyos-build/packages/linux-kernel +$ git clone https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git +$ ./build-linux-firmware.sh +$ cp vyos-linux-firmware_*.deb ../ +``` + +This tries to automatically detect which blobs are needed based on which drivers +were built. If it fails to find the correct files you can add them manually to +`vyos-build/packages/linux-kernel/build-linux-firmware.sh`: + +``` bash +ADD_FW_FILES="iwlwifi* ath11k/QCA6390/*/*.bin" +``` + +#### Building Out-Of-Tree Modules + +Building the kernel is one part, but now you also need to build the required +out-of-tree modules so everything is lined up and the ABIs match. To do so, +you can again take a look at `vyos-build/packages/linux-kernel/Jenkinsfile` +to see all of the required modules and their selected versions. We will show +you how to build all the current required modules. + +##### Accel-PPP + +First, clone the source code and check out the appropriate version by running: + +``` none +$ cd vyos-build/packages/linux-kernel +$ git clone https://github.com/accel-ppp/accel-ppp.git +``` + +We again make use of a helper script and some patches to make the build work. +Just run the following command: + +``` none +$ ./build-accel-ppp.sh +I: Build Accel-PPP Debian package +CMake Deprecation Warning at CMakeLists.txt:3 (cmake_policy): + The OLD behavior for policy CMP0003 will be removed from a future version + of CMake. + + The cmake-policies(7) manual explains that the OLD behaviors of all + policies are deprecated and that a policy should be set to OLD only under + specific short-term circumstances. Projects should be ported to the NEW + behavior and not rely on setting a policy to OLD. + +-- The C compiler identification is GNU 8.3.0 + +... + +CPack: Create package using DEB +CPack: Install projects +CPack: - Run preinstall target for: accel-ppp +CPack: - Install project: accel-ppp +CPack: Create package +CPack: - package: /vyos/vyos-build/packages/linux-kernel/accel-ppp/build/accel-ppp.deb generated. +``` + +After compiling the packages you will find yourself the newly generated <span class="title-ref">\*.deb</span> +binaries in `vyos-build/packages/linux-kernel` from which you can copy them +to the `vyos-build/packages` folder for inclusion during the ISO build. + +##### Intel NIC + +The Intel NIC drivers do not come from a Git repository, instead we just fetch +the tarballs from our mirror and compile them. + +Simply use our wrapper script to build all of the driver modules. + +``` none +./build-intel-drivers.sh + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed +100 490k 100 490k 0 0 648k 0 --:--:-- --:--:-- --:--:-- 648k +I: Compile Kernel module for Intel ixgbe driver + +... + +I: Building Debian package vyos-intel-iavf +Doing `require 'backports'` is deprecated and will not load any backport in the next major release. +Require just the needed backports instead, or 'backports/latest'. +Debian packaging tools generally labels all files in /etc as config files, as mandated by policy, so fpm defaults to this behavior for deb packages. You can disable this default behavior with --deb-no-default-config-files flag {:level=>:warn} +Created package {:path=>"vyos-intel-iavf_4.0.1-0_amd64.deb"} +I: Cleanup iavf source +``` + +After compiling the packages you will find yourself the newly generated <span class="title-ref">\*.deb</span> +binaries in `vyos-build/packages/linux-kernel` from which you can copy them +to the `vyos-build/packages` folder for inclusion during the ISO build. + +##### Intel QAT + +The Intel QAT (Quick Assist Technology) drivers do not come from a Git +repository, instead we just fetch the tarballs from 01.org, Intel's +open-source website. + +Simply use our wrapper script to build all of the driver modules. + +``` none +$ ./build-intel-qat.sh + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed +100 5065k 100 5065k 0 0 1157k 0 0:00:04 0:00:04 --:--:-- 1157k +I: Compile Kernel module for Intel qat driver +checking for a BSD-compatible install... /usr/bin/install -c +checking whether build environment is sane... yes +checking for a thread-safe mkdir -p... /bin/mkdir -p +checking for gawk... gawk +checking whether make sets $(MAKE)... yes + +... + +I: Building Debian package vyos-intel-qat +Doing `require 'backports'` is deprecated and will not load any backport in the next major release. +Require just the needed backports instead, or 'backports/latest'. +Debian packaging tools generally labels all files in /etc as config files, as mandated by policy, so fpm defaults to this behavior for deb packages. You can disable this default behavior with --deb-no-default-config-files flag {:level=>:warn} +Created package {:path=>"vyos-intel-qat_1.7.l.4.9.0-00008-0_amd64.deb"} +I: Cleanup qat source +``` + +After compiling the packages you will find yourself the newly generated <span class="title-ref">\*.deb</span> +binaries in `vyos-build/packages/linux-kernel` from which you can copy them +to the `vyos-build/packages` folder for inclusion during the ISO build. + +### Packages + +If you are brave enough to build yourself an ISO image containing any modified +package from our GitHub organisation - this is the place to be. + +Any "modified" package may refer to an altered version of e.g. vyos-1x package +that you would like to test before filing a pull request on GitHub. + +Building an ISO with any customized package is in no way different than +building a regular (customized or not) ISO image. Simply place your modified +<span class="title-ref">\*.deb</span> package inside the <span class="title-ref">packages</span> folder within <span class="title-ref">vyos-build</span>. The build +process will then pickup your custom package and integrate it into your ISO. + +### Troubleshooting + +Debian APT is not very verbose when it comes to errors. If your ISO build breaks +for whatever reason and you suspect it's a problem with APT dependencies or +installation you can add this small patch which increases the APT verbosity +during ISO build. + +``` diff +diff --git i/scripts/live-build-config w/scripts/live-build-config +index 1b3b454..3696e4e 100755 +--- i/scripts/live-build-config ++++ w/scripts/live-build-config +@@ -57,7 +57,8 @@ lb config noauto \ + --firmware-binary false \ + --updates true \ + --security true \ +- --apt-options "--yes -oAcquire::Check-Valid-Until=false" \ ++ --apt-options "--yes -oAcquire::Check-Valid-Until=false -oDebug::BuildDeps=true -oDebug::pkgDepCache::AutoInstall=true \ ++ -oDebug::pkgDepCache::Marker=true -oDebug::pkgProblemResolver=true -oDebug::Acquire::gpgv=true" \ + --apt-indices false + "${@}" + """ +``` + +### Virtualization Platforms + +#### QEMU + +Run the following command after building the ISO image. + +``` none +$ make qemu +``` + +#### VMware + +Run the following command after building the QEMU image. + +``` none +$ make vmware +``` + +## Packages + +VyOS itself comes with a bunch of packages that are specific to our system and +thus cannot be found in any Debian mirror. Those packages can be found at the +[VyOS GitHub project](https://github.com/vyos) in their source format can easily be compiled into +a custom Debian (<span class="title-ref">\*.deb</span>) package. + +The easiest way to compile your package is with the above mentioned +`build_docker` container, it includes all required dependencies for +all VyOS related packages. + +Assume we want to build the vyos-1x package on our own and modify it to our +needs. We first need to clone the repository from GitHub. + +``` none +$ git clone https://github.com/vyos/vyos-1x +``` + +### Build + +Launch Docker container and build package + +``` none +# For VyOS 1.3 (equuleus, current) +$ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:current bash + +# Change to source directory +$ cd vyos-1x + +# Build DEB +$ dpkg-buildpackage -uc -us -tc -b +``` + +After a minute or two you will find the generated DEB packages next to the +vyos-1x source directory: + +``` none +# ls -al ../vyos-1x*.deb +-rw-r--r-- 1 vyos_bld vyos_bld 567420 Aug 3 12:01 ../vyos-1x_1.3dev0-1847-gb6dcb0a8_all.deb +-rw-r--r-- 1 vyos_bld vyos_bld 3808 Aug 3 12:01 ../vyos-1x-vmware_1.3dev0-1847-gb6dcb0a8_amd64.deb +``` + +### Install + +To take your newly created package on a test drive you can simply SCP it to a +running VyOS instance and install the new <span class="title-ref">\*.deb</span> package over the current +running one. + +Just install using the following commands: + +``` none +vyos@vyos:~$ dpkg --install /tmp/vyos-1x_1.3dev0-1847-gb6dcb0a8_all.deb +(Reading database ... 58209 files and directories currently installed.) +Preparing to unpack .../vyos-1x_1.3dev0-1847-gb6dcb0a8_all.deb ... +Unpacking vyos-1x (1.3dev0-1847-gb6dcb0a8) over (1.3dev0-1847-gb6dcb0a8) ... +Setting up vyos-1x (1.3dev0-1847-gb6dcb0a8) ... +Processing triggers for rsyslog (8.1901.0-1) ... +``` + +You can also place the generated <span class="title-ref">\*.deb</span> into your ISO build environment to +include it in a custom iso, see `build_custom_packages` for more +information. + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +Any packages in the packages directory will be added to the iso +during build, replacing the upstream ones. Make sure you delete them (both +the source directories and built deb packages) if you want to build an iso +from purely upstream packages. + +</div> diff --git a/docs/contributing/md-debugging.md b/docs/contributing/md-debugging.md new file mode 100644 index 00000000..b7e66470 --- /dev/null +++ b/docs/contributing/md-debugging.md @@ -0,0 +1,189 @@ +# Debugging + +There are two flags available to aid in debugging configuration scripts. +Since configuration loading issues will manifest during boot, the flags are +passed as kernel boot parameters. + +## ISO image build + +When having trouble compiling your own ISO image or debugging Jenkins issues +you can follow the steps at `iso_build_issues`. + +## System Startup + +The system startup can be debugged (like loading in the configuration +file from `/config/config.boot`. This can be achieve by extending the +Kernel command-line in the bootloader. + +### Kernel + +- `vyos-debug` - Adding the parameter to the linux boot line will produce + timing results for the execution of scripts during commit. If one is seeing + an unexpected delay during manual or boot commit, this may be useful in + identifying bottlenecks. The internal flag is `VYOS_DEBUG`, and is found + in [vyatta-cfg](https://github.com/vyos/vyatta-cfg). Output is directed to `/var/log/vyatta/cfg-stdout.log`. +- `vyos-config-debug` - During development, coding errors can lead to a + commit failure on boot, possibly resulting in a failed initialization of the + CLI\. In this circumstance, the kernel boot parameter `vyos-config-debug` + will ensure access to the system as user `vyos`, and will log a Python + stack trace to the file `/tmp/boot-config-trace`. + File `boot-config-trace` will generate only if config loaded with a failure + status. + +## Live System + +A number of flags can be set up to change the behaviour of VyOS at runtime. +These flags can be toggled using either environment variables or creating +files. + +For each feature, a file called `vyos.feature.debug` can be created to +toggle the feature on. If a parameter is required it can be placed inside +the file as its first line. + +The file can be placed in `/tmp` for one time debugging (as the file +will be removed on reboot) or placed in '/config' to stay permanently. + +For example, `/tmp/vyos.ifconfig.debug` can be created to enable +interface debugging. + +It is also possible to set up the debugging using environment variables. +In that case, the name will be (in uppercase) VYOS_FEATURE_DEBUG. + +For example running, `export VYOS_IFCONFIG_DEBUG=""` on your vbash, +will have the same effect as `touch /tmp/vyos.ifconfig.debug`. + +- `ifconfig` - Once set, all commands used, and their responses received + from the OS, will be presented on the screen for inspection. +- `command` - Once set, all commands used, and their responses received + from the OS, will be presented on the screen for inspection. +- `developer` - Should a command fail, instead of printing a message to the + user explaining how to report issues, the python interpreter will start a + PBD post-mortem session to allow the developer to debug the issue. As the + debugger will wait from input from the developer, it has the capacity to + prevent a router to boot and therefore should only be permanently set up + on production if you are ready to see the OS fail to boot. +- `log` - In some rare cases, it may be useful to see what the OS is doing, + including during boot. This option sends all commands used by VyOS to a + file. The default file is `/tmp/full-log` but it can be changed. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +In order to retrieve the debug output on the command-line you need to +disable `vyos-configd` in addition. This can be run either one-time by +calling `sudo systemctl stop vyos-configd` or make this reboot-safe by +calling `sudo systemctl disable vyos-configd`. + +</div> + +### FRR + +Recent versions use the `vyos.frr` framework. The Python class is located +inside our `vyos-1x:python/vyos/frr.py`. It comes with an embedded debugging/ +(print style) debugger as vyos.ifconfig does. + +To enable debugging just run: `$ touch /tmp/vyos.frr.debug` + +### Debugging Python Code with PDB + +Sometimes it might be useful to debug Python code interactively on the live +system rather than a IDE. This can be achieved using pdb. + +Let us assume you want to debug a Python script that is called by an op-mode +command. After you found the script by looking up the op-mode-defitions you +can edit the script in the live system using e.g. vi: +`vi /usr/libexec/vyos/op_mode/show_xyz.py` + +Insert the following statement right before the section where you want to +investigate a problem (e.g. a statement you see in a backtrace): +`import pdb; pdb.set_trace()` +Optionally you can surrounded this statement by an `if` which only triggers +under the condition you are interested in. + +Once you run `show xyz` and your condition is triggered you should be dropped +into the python debugger: + +``` none +> /usr/libexec/vyos/op_mode/show_nat_translations.py(109)process() +-> rule_type = rule.get('type', '') +(Pdb) +``` + +You can type `help` to get an overview of the available commands, and +`help command` to get more information on each command. + +Useful commands are: + +- examine variables using `pp(var)` +- continue execution using `cont` +- get a backtrace using `bt` + +### Config Migration Scripts + +When writing a new configuration migrator it may happen that you see an error +when you try to invoke it manually on a development system. This error will +look like: + +``` none +vyos@vyos:~$ /opt/vyatta/etc/config-migrate/migrate/ssh/0-to-1 /tmp/config.boot +Traceback (most recent call last): + File "/opt/vyatta/etc/config-migrate/migrate/ssh/0-to-1", line 31, in <module> + config = ConfigTree(config_file) + File "/usr/lib/python3/dist-packages/vyos/configtree.py", line 134, in __init__ + raise ValueError("Failed to parse config: {0}".format(msg)) +ValueError: Failed to parse config: Syntax error on line 240, character 1: Invalid syntax. +``` + +The reason is that the configuration migration backend is rewritten and uses +a new form of "magic string" which is applied on demand when real config +migration is run on boot. When running individual migrators for testing, +you need to convert the "magic string" on your own by: + +``` none +vyos@vyos:~$ /usr/libexec/vyos/run-config-migration.py --virtual --set-vintage vyos /tmp/config.boot +``` + +### Configuration Error on System Boot + +Being brave and running the latest rolling releases will sometimes trigger +bugs due to corner cases we missed in our design. Those bugs should be filed +via [Phabricator]() but you can help us to narrow down the issue. Login to your +VyOS system and change into configuration mode by typing `configure`. Now +re-load your boot configuration by simply typing `load` followed by return. + +You should now see a Python backtrace which will help us to handle the issue, +please attach it to the [Phabricator]() task. + +### Boot Timing + +During the migration and extensive rewrite of functionality from Perl into +Python a significant increase in the overall system boottime was noticed. The +system boot time can be analysed and a graph can be generated in the end which +shows in detail who called whom during the system startup phase. + +This is done by utilizing the `systemd-bootchart` package which is now +installed by default on the VyOS 1.3 (equuleus) branch. The configuration is +also versioned so we get comparable results. `systemd-bootchart` is configured +using this file: [bootchart.conf](https://github.com/vyos/vyos-build/blob/current/data/live-build-config/includes.chroot/etc/systemd/bootchart.conf) + +To enable boot time graphing change the Kernel commandline and add the following +string: `init=/usr/lib/systemd/systemd-bootchart` + +This can also be done permanently by changing `/boot/grub/grub.cfg`. + +## Priorities + +VyOS CLI is all about priorities. Every CLI node has a corresponding +`node.def` file and possibly an attached script that is executed when the +node is present. Nodes can have a priority, and on system bootup - or any +other `commit` to the config all scripts are executed from lowest to highest +priority. This is good as this gives a deterministic behavior. + +To debug issues in priorities or to see what's going on in the background +you can use the `/opt/vyatta/sbin/priority.pl` script which lists to you +the execution order of the scripts. diff --git a/docs/contributing/md-development.md b/docs/contributing/md-development.md new file mode 100644 index 00000000..cc9fae00 --- /dev/null +++ b/docs/contributing/md-development.md @@ -0,0 +1,708 @@ +# Development + +All VyOS source code is hosted on GitHub under the VyOS organization which can +be found here: <https://github.com/vyos> + +Our code is split into several modules. VyOS is composed of multiple individual +packages, some of them are forks of upstream packages and are periodically +synced with upstream, so keeping the whole source under a single repository +would be very inconvenient and slow. There is now an ongoing effort to +consolidate all VyOS-specific framework/config packages into vyos-1x package, +but the basic structure is going to stay the same, just with fewer and fewer +packages while the base code is rewritten from Perl/BASH into Python using and +XML based interface definition for the CLI. + +The repository that contains all the ISO build scripts is: +<https://github.com/vyos/vyos-build> + +The README.md file will guide you to use the this top level repository. + +## Submit a Patch + +Patches are always more than welcome. To have a clean and easy to maintain +repository we have some guidelines when working with Git. A clean repository +eases the automatic generation of a changelog file. + +A good approach for writing commit messages is actually to have a look at the +file(s) history by invoking `git log path/to/file.txt`. + +### Prepare patch/commit + +In a big system, such as VyOS, that is comprised of multiple components, it's +impossible to keep track of all the changes and bugs/feature requests in one's +head. We use a bugtracker known as [Phabricator]() for it ("issue tracker" would +be a better term, but this one stuck). + +The information is used in three ways: + +- Keep track of the progress (what we've already done in this branch and what + we still need to do). +- Prepare release notes for upcoming releases +- Help future maintainers of VyOS (it could be you!) to find out why certain + things have been changed in the codebase or why certain features have been + added + +To make this approach work, every change must be associated with a task number +(prefixed with **T**) and a component. If there is no bug report/feature request +for the changes you are going to make, you have to create a [Phabricator]() task +first. Once there is an entry in [Phabricator](), you should reference its id in +your commit message, as shown below: + +- `ddclient: T1030: auto create runtime directories` +- `Jenkins: add current Git commit ID to build description` + +If there is no [Phabricator]() reference in the commits of your pull request, we +have to ask you to amend the commit message. Otherwise we will have to reject +it. + +#### Writing good commit messages + +The format should be and is inspired by: <https://git-scm.com/book/ch5-2.html> +It is also worth reading <https://chris.beams.io/posts/git-commit/> + +- A single, short, summary of the commit (recommended 50 characters or less, + not exceeding 80 characters) containing a prefix of the changed component + and the corresponding [Phabricator]() reference e.g. `snmp: T1111:` or + `ethernet: T2222:` - multiple components could be concatenated as in + `snmp: ethernet: T3333` +- In some contexts, the first line is treated as the subject of an email and + the rest of the text as the body. The blank line separating the summary from + the body is critical (unless you omit the body entirely); tools like rebase + can get confused if you run the two together. +- Followed by a message which describes all the details like: + - What/why/how something has been changed, makes everyone's life easier when + working with <span class="title-ref">git bisect</span> + - All text of the commit message should be wrapped at 72 characters if + possible which makes reading commit logs easier with `git log` on a + standard terminal (which happens to be 80x25) + - If applicable a reference to a previous commit should be made linking + those commits nicely when browsing the history: `After commit abcd12ef ("snmp: this is a headline") a Python import statement is missing, throwing the following exception: ABCDEF` +- Always use the `-x` option to the `git cherry-pick` command when back or + forward porting an individual commit. This automatically appends the line: + `(cherry picked from commit <ID>)` to the original authors commit message + making it easier when bisecting problems. +- Every change set must be consistent (self containing)! Do not fix multiple + bugs in a single commit. If you already worked on multiple fixes in the same + file use <span class="title-ref">git add --patch</span> to only add the parts related to the one issue + into your upcoming commit. + +Limits: + +- We only accept bugfixes in packages other than <https://github.com/vyos/vyos-1x> + as no new functionality should use the old style templates (`node.def` and + Perl/BASH code. Use the new style XML/Python interface instead. + +Please submit your patches using the well-known GitHub pull-request against our +repositories found in the VyOS GitHub organisation at <https://github.com/vyos> + +### Determinine source package + +Suppose you want to make a change in the webproxy script but yet you do not know +which of the many VyOS packages ship this file. You can determine the VyOS +package name in question by using Debian's `dpkg -S` command of your running +VyOS installation. + +``` none +vyos@vyos:~ dpkg -S /opt/vyatta/sbin/vyatta-update-webproxy.pl +vyatta-webproxy: /opt/vyatta/sbin/vyatta-update-webproxy.pl +``` + +This means the file in question (`/opt/vyatta/sbin/vyatta-update-webproxy.pl`) +is located in the `vyatta-webproxy` package which can be found here: +<https://github.com/vyos/vyatta-webproxy> + +### Fork Repository and submit Patch + +Forking the repository and submitting a GitHub pull-request is the preferred +way of submitting your changes to VyOS. You can fork any VyOS repository to your +very own GitHub account by just appending `/fork` to any repository's URL on +GitHub. To e.g. fork the `vyos-1x` repository, open the following URL in your +favourite browser: <https://github.com/vyos/vyos-1x/fork> + +You then can proceed with cloning your fork or add a new remote to your local +repository: + +- Clone: `git clone https://github.com/<user>/vyos-1x.git` +- Fork: `git remote add myfork https://github.com/<user>/vyos-1x.git` + +In order to record you as the author of the fix please identify yourself to Git +by setting up your name and email. This can be done local for this one and only +repository `git config` or globally using `git config --global`. + +``` none +git config --global user.name "J. Random Hacker" +git config --global user.email "jrhacker@example.net" +``` + +Make your changes and save them. Do the following for all changes files to +record them in your created Git commit: + +- Add file to Git index using `git add myfile`, or for a whole directory: + `git add somedir/*` +- Commit the changes by calling `git commit`. Please use a meaningful commit + headline (read above) and don't forget to reference the [Phabricator]() ID. +- Submit the patch `git push` and create the GitHub pull-request. + +### Attach patch to Phabricator task + +Follow the above steps on how to "Fork repository to submit a Patch". Instead +of uploading "pushing" your changes to GitHub you can export the patches/ +commits and send it to <maintainers@vyos.net> or attach it directly to the bug +(preferred over email) + +- Export last commit to patch file: `git format-patch` or export the last two + commits into its appropriate patch files: `git format-patch -2` + +## Coding Guidelines + +Like any other project we have some small guidelines about our source code, too. +The rules we have are not there to punish you - the rules are in place to help +us all. By having a consistent coding style it becomes very easy for new +and also longtime contributors to navigate through the sources and all the +implied logic of any one source file.. + +Python 3 **shall** be used. How long can we keep Python 2 alive anyway? No +considerations for Python 2 compatibility **should** be taken at any time. + +### Formatting + +- Python: Tabs **shall not** be used. Every indentation level should be 4 spaces +- XML: Tabs **shall not** be used. Every indentation level should be 2 spaces + +<div class="note"> + +<div class="title"> + +Note + +</div> + +There are extensions to e.g. VIM (xmllint) which will help you to get +your indention levels correct. Add to following to your .vimrc file: +`au FileType xml setlocal equalprg=xmllint\ --format\ --recover\ -\ 2>/dev/null` now you can call the linter using `gg=G` in command mode. + +</div> + +#### Text generation + +Template processor **should** be used for generating config files. Built-in +string formatting **may** be used for simple line-oriented formats where every +line is self-contained, such as iptables rules. Template processor **must** be +used for structured, multi-line formats such as those used by ISC DHCPd. + +The default template processor for VyOS code is [Jinja2](https://jinja.palletsprojects.com/). + +### Summary + +When modifying the source code, remember these rules of the legacy elimination +campaign: + +- No new features in Perl +- No old style command definitions +- No code incompatible with Python3 + +## Python + +The switch to the Python programming language for new code is not merely a +change of the language, but a chance to rethink and improve the programming +approach. + +Let's face it: VyOS is full of spaghetti code where logic for reading the VyOS +config, generating daemon configs, and restarting processes is all mixed up. + +Python (or any other language, for that matter) does not provide automatic +protection from bad design, so we need to also devise design guidelines and +follow them to keep the system extensible and maintainable. + +But we are here to assist you and want to guide you through how you can become +a good VyOS contributor. The rules we have are not there to punish you - the +rules are in place to help us all. What does it mean? By having a consistent +coding style it becomes very easy for new contributors and also longtime +contributors to navigate through the sources and all the implied logic of +the spaghetti code. + +Please use the following template as good starting point when developing new +modules or even rewrite a whole bunch of code in the new style XML/Python +interface. + +### Configuration Script Structure and Behaviour + +Your configuration script or operation mode script which is also written in +Python3 should have a line break on 80 characters. This seems to be a bit odd +nowadays but as some people also work remotely or program using vi(m) this is +a fair good standard which I hope we can rely on. + +In addition this also helps when browsing the GitHub codebase on a mobile +device if you happen to be a crazy scientist. + +``` python +#!/usr/bin/env python3 +# +# Copyright (C) 2020 VyOS maintainers and contributors +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License version 2 or later as +# published by the Free Software Foundation. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see <http://www.gnu.org/licenses/>. + +import sys + +from vyos.config import Config +from vyos import ConfigError + +def get_config(): + if config: + conf = config + else: + conf = Config() + + # Base path to CLI nodes + base = ['...', '...'] + # Convert the VyOS config to an abstract internal representation + config_data = conf.get_config_dict(base, key_mangling=('-', '_'), get_first_key=True) + return config_data + +def verify(config): + # Verify that configuration is valid + if invalid: + raise ConfigError("Descriptive message") + return True + +def generate(config): + # Generate daemon configs + pass + +def apply(config): + # Apply the generated configs to the live system + pass + +try: + c = get_config() + verify(c) + generate(c) + apply(c) +except ConfigError as e: + print(e) + sys.exit(1) +``` + +The `get_config()` function must convert the VyOS config to an abstract, +internal representation. No other function is allowed to call the `vyos.config. Config` object method directly. The rationale for it is that when config reads +are mixed with other logic, it's very hard to change the config syntax since +you need to weed out every occurrence of the old syntax. If syntax-specific +code is confined to a single function, the rest of the code can be left +untouched as long as the internal representation remains compatible. + +Another advantage is testability of the code. Mocking the entire config +subsystem is hard, while constructing an internal representation by hand is +way simpler. + +The `verify()` function takes your internal representation of the config and +checks if it's valid, otherwise it must raise `ConfigError` with an error +message that describes the problem and possibly suggests how to fix it. It must +not make any changes to the system. The rationale for it is again testability +and, in the future when the config backend is ready and every script is +rewritten in this fashion, ability to execute commit dry run ("commit test" +like in JunOS) and abort commit before making any changes to the system if an +error is found in any component. + +The `generate()` function generates config files for system components. + +The `apply()` function applies the generated configuration to the live +system. It should use non-disruptive reload whenever possible. It may execute +disruptive operations such as daemon process restart if a particular component +does not support non-disruptive reload, or when the expected service degradation +is minimal (for example, in case of auxiliary services such as LLDPd). In case +of high impact services such as VPN daemon and routing protocols, when non- +disruptive reload is supported for some but not all types of configuration +changes, scripts authors should make effort to determine if a configuration +change can be done in a non-disruptive way and only resort to disruptive restart +if it cannot be avoided. + +Unless absolutely necessary, configuration scripts should not modify the active +configuration of system components directly. Whenever at all possible, scripts +should generate a configuration file or files that can be applied with a single +command such as reloading a service through systemd init. Inserting statements +one by one is particularly discouraged, for example, when configuring netfilter +rules, saving them to a file and loading it with iptables-restore should always +be preferred to executing iptables directly. + +The `apply()` and `generate()` functions may `raise ConfigError` if, for +example, the daemon failed to start with the updated config. It shouldn't be a +substitute for proper config checking in the `verify()` function. All +reasonable effort should be made to verify that generated configuration is +valid and will be accepted by the daemon, including, when necessary, cross- +checks with other VyOS configuration subtrees. + +Exceptions, including `VyOSError` (which is raised by `vyos.config.Config` +on improper config operations, such as trying to use `list_nodes()` on a +non-tag node) should not be silenced or caught and re-raised as config error. +Sure this will not look pretty on user's screen, but it will make way better +bug reports, and help users (and most VyOS users are IT professionals) do their +own debugging as well. + +For easy orientation we suggest you take a look on the `ntp.py` or +`interfaces-bonding.py` (for tag nodes) implementation. Both files can be +found in the [vyos-1x](https://github.com/vyos/vyos-1x/tree/current/schema) repository. + +## XML (used for CLI definitions) + +The bash (or better vbash) completion in VyOS is defined in *templates*. +Templates are text files (called `node.def`) stored in a directory tree. The +directory names define the command names, and template files define the command +behaviour. Before VyOS 1.2 (crux) this files were created by hand. After a +complex redesign [process](https://blog.vyos.io/vyos-development-digest-10) the new style template are automatically generated +from a XML input file. + +XML interface definitions for VyOS come with a RelaxNG schema and are located +in the [vyos-1x](https://github.com/vyos/vyos-1x/tree/current/schema) module. This schema is a slightly modified schema from [VyConf](https://github.com/vyos/vyconf/tree/master/data/schemata) +alias VyOS 2.0 So VyOS 1.2.x interface definitions will be reusable in Nextgen +VyOS Versions with very minimal changes. + +The great thing about schemas is not only that people can know the complete +grammar for certain, but also that it can be automatically verified. The +<span class="title-ref">scripts/build-command-templates</span> script that converts the XML definitions to +old style templates also verifies them against the schema, so a bad definition +will cause the package build to fail. I do agree that the format is verbose, but +there is no other format now that would allow this. Besides, a specialized XML +editor can alleviate the issue with verbosity. + +Example: + +``` xml +<?xml version="1.0"?> +<!-- Cron configuration --> +<interfaceDefinition> + <node name="system"> + <children> + <node name="task-scheduler"> + <properties> + <help>Task scheduler settings</help> + </properties> + <children> + <tagNode name="task" owner="${vyos_conf_scripts_dir}/task_scheduler.py"> + <properties> + <help>Scheduled task</help> + <valueHelp> + <format><string></format> + <description>Task name</description> + </valueHelp> + <priority>999</priority> + </properties> + <children> + <leafNode name="crontab-spec"> + <properties> + <help>UNIX crontab time specification string</help> + </properties> + </leafNode> + <leafNode name="interval"> + <properties> + <help>Execution interval</help> + <valueHelp> + <format><minutes></format> + <description>Execution interval in minutes</description> + </valueHelp> + <valueHelp> + <format><minutes>m</format> + <description>Execution interval in minutes</description> + </valueHelp> + <valueHelp> + <format><hours>h</format> + <description>Execution interval in hours</description> + </valueHelp> + <valueHelp> + <format><days>d</format> + <description>Execution interval in days</description> + </valueHelp> + <constraint> + <regex>[1-9]([0-9]*)([mhd]{0,1})</regex> + </constraint> + </properties> + </leafNode> + <node name="executable"> + <properties> + <help>Executable path and arguments</help> + </properties> + <children> + <leafNode name="path"> + <properties> + <help>Path to executable</help> + </properties> + </leafNode> + <leafNode name="arguments"> + <properties> + <help>Arguments passed to the executable</help> + </properties> + </leafNode> + </children> + </node> + </children> + </tagNode> + </children> + </node> + </children> + </node> +</interfaceDefinition> +``` + +Command definitions are purely declarative, and cannot contain any logic. All +logic for generating config files for target applications, restarting services +and so on is implemented in configuration scripts instead. + +### GNU Preprocessor + +XML interface definition files use the <span class="title-ref">xml.in</span> file extension which was +implemented in `T1843`. XML interface definitions tend to have a lot of +duplicated code in areas such as: + +- VIF (incl. VIF-S/VIF-C) +- Address +- Description +- Enabled/Disabled + +Instead of supplying all those XML nodes multiple times there are now include +files with predefined features. Brief overview: + +- [IPv4, IPv6 and DHCP(v6)](https://github.com/vyos/vyos-1x/blob/current/interface-definitions/include/interface/address-ipv4-ipv6-dhcp.xml.i) address assignment +- [IPv4, IPv6](https://github.com/vyos/vyos-1x/blob/current/interface-definitions/include/interface/address-ipv4-ipv6.xml.i) address assignment +- [VLAN (VIF)](https://github.com/vyos/vyos-1x/blob/current/interface-definitions/include/interface/vif.xml.i) definition +- [MAC address](https://github.com/vyos/vyos-1x/blob/current/interface-definitions/include/interface/mac.xml.i) assignment + +All interface definition XML input files (.in suffix) will be sent to the GCC +preprocess and the output is stored in the <span class="title-ref">build/interface-definitions</span> +folder. The previously mentioned <span class="title-ref">scripts/build-command-templates</span> script +operates on the <span class="title-ref">build/interface-definitions</span> folder to generate all required +CLI nodes. + +``` none +$ make interface_definitions +install -d -m 0755 build/interface-definitions +install -d -m 0755 build/op-mode-definitions +Generating build/interface-definitions/intel_qat.xml from interface-definitions/intel_qat.xml.in +Generating build/interface-definitions/interfaces-bonding.xml from interface-definitions/interfaces-bonding.xml.in +Generating build/interface-definitions/cron.xml from interface-definitions/cron.xml.in +Generating build/interface-definitions/pppoe-server.xml from interface-definitions/pppoe-server.xml.in +Generating build/interface-definitions/mdns-repeater.xml from interface-definitions/mdns-repeater.xml.in +Generating build/interface-definitions/tftp-server.xml from interface-definitions/tftp-server.xml.in +[...] +``` + +### Guidelines + +#### Use of numbers + +Use of numbers in command names **should** be avoided unless a number is a +part of a protocol name or similar. Thus, `protocols ospfv3` is perfectly +fine, but something like `server-1` is questionable at best. + +#### Help String + +To ensure uniform look and feel, and improve readability, we should follow a +set of guidelines consistently. + +##### Capitalization and punctuation + +The first word of every help string **must** be capitalized. There **must not** +be a period at the end of help strings. + +Rationale: this seems to be the unwritten standard in network device CLIs, and +a good aesthetic compromise. + +Examples: + +- Good: "Frobnication algorithm" +- Bad: "frobnication algorithm" +- Bad: "Frobnication algorithm." +- Horrible: "frobnication algorithm." + +##### Use of abbreviations and acronyms + +Abbreviations and acronyms **must** be capitalized. + +Examples: + +- Good: "TCP connection timeout" +- Bad: "tcp connection timeout" +- Horrible: "Tcp connection timeout" + +Acronyms also **must** be capitalized to visually distinguish them from normal +words: + +Examples: + +- Good: RADIUS (as in remote authentication for dial-in user services) +- Bad: radius (unless it's about the distance between a center of a circle and + any of its points) + +Some abbreviations are traditionally written in mixed case. Generally, if it +contains words "over" or "version", the letter **should** be lowercase. If +there's an accepted spelling (especially if defined by an RFC or another +standard), it **must** be followed. + +Examples: + +- Good: PPPoE, IPsec +- Bad: PPPOE, IPSEC +- Bad: pppoe, ipsec + +##### Use of verbs + +Verbs **should** be avoided. If a verb can be omitted, omit it. + +Examples: + +- Good: "TCP connection timeout" +- Bad: "Set TCP connection timeout" + +If a verb is essential, keep it. For example, in the help text of `set system ipv6 disable-forwarding`, "Disable IPv6 forwarding on all interfaces" is a +perfectly justified wording. + +##### Prefer infinitives + +Verbs, when they are necessary, **should** be in their infinitive form. + +Examples: + +- Good: "Disable IPv6 forwarding" +- Bad: "Disables IPv6 forwarding" + +### Migrating old CLI + +<table> +<colgroup> +<col style="width: 25%" /> +<col style="width: 25%" /> +<col style="width: 50%" /> +</colgroup> +<thead> +<tr> +<th>Old concept/syntax</th> +<th>New syntax</th> +<th>Notes</th> +</tr> +</thead> +<tbody> +<tr> +<td>mynode/node.def</td> +<td><node name="mynode"> </node></td> +<td>Leaf nodes (nodes with values) use <leafNode> tag instead</td> +</tr> +<tr> +<td>mynode/node.tag , tag:</td> +<td><tagNode name="mynode> </node></td> +<td></td> +</tr> +<tr> +<td>help: My node</td> +<td><properties> <help>My node</help></td> +<td></td> +</tr> +<tr> +<td>val_help: <format>; some string</td> +<td><properties> <valueHelp> <format> format </format> <description> some +string </description></td> +<td>Do not add angle brackets around the format, they will be inserted +automatically</td> +</tr> +<tr> +<td>syntax:expression: pattern</td> +<td><properties> <constraint> <regex> ...</td> +<td><constraintErrorMessage> will be displayed on failure</td> +</tr> +<tr> +<td>syntax:expression: $VAR(@) in "foo", "bar", "baz"</td> +<td>None</td> +<td>Use regex</td> +</tr> +<tr> +<td>syntax:expression: exec ...</td> +<td><properties> <constraint> <validator> <name ="foo" argument="bar"></td> +<td>"${vyos_libexecdir}/validators/foo bar $VAR(@)" will be executed, +<constraintErrorMessage> will be displayed on failure</td> +</tr> +<tr> +<td>syntax:expression: (arithmetic expression)</td> +<td>None</td> +<td>External arithmetic validator may be added if there's demand, complex +validation is better left to commit-time scripts</td> +</tr> +<tr> +<td>priority: 999</td> +<td><properties> <priority>999</priority></td> +<td>Please leave a comment explaining why the priority was chosen +(e.g. "after interfaces are configured")</td> +</tr> +<tr> +<td>multi:</td> +<td><properties> <multi/></td> +<td>Only applicable to leaf nodes</td> +</tr> +<tr> +<td>allowed: echo foo bar</td> +<td><properties> <completionHelp> <list> foo bar </list></td> +<td></td> +</tr> +<tr> +<td>allowed: cli-shell-api listNodes vpn ipsec esp-group</td> +<td><properties> <completionHelp> <path> vpn ipsec esp-group </path> ...</td> +<td></td> +</tr> +<tr> +<td>allowed: /path/to/script</td> +<td><properties> <completionHelp> <script> /path/to/script </script> ...</td> +<td></td> +</tr> +<tr> +<td>default:</td> +<td>None</td> +<td>Move default values to scripts</td> +</tr> +<tr> +<td>commit:expression:</td> +<td>None</td> +<td>All commit time checks should be in the verify() function of the script</td> +</tr> +<tr> +<td>begin:/create:/delete:</td> +<td>None</td> +<td>All logic should be in the scripts</td> +</tr> +</tbody> +</table> + +## C++ Backend Code + +The CLI parser used in VyOS is a mix of bash, bash-completion helper and the +C++ backend library \[vyatta-cfg\](<https://github.com/vyos/vyatta-cfg>). This +section is a reference of common CLI commands and the respective entry point +in the C/C++ code. + +- `set` + - <https://github.com/vyos/vyatta-cfg/blob/0f42786a0b3/src/cstore/cstore.cpp#L352> + - <https://github.com/vyos/vyatta-cfg/blob/0f42786a0b3/src/cstore/cstore.cpp#L2549> +- `commit` + - <https://github.com/vyos/vyatta-cfg/blob/0f42786a0b3/src/commit/commit-algorithm.cpp#L1252> + +## Continuous Integration + +VyOS makes use of [Jenkins](https://jenkins.io/) as our Continuous Integration (CI) service. Our +[VyOS CI]() server is publicly accessible here: <https://ci.vyos.net>. You can get +a brief overview of all required components shipped in a VyOS ISO. + +To build our modules we utilize a CI/CD Pipeline script. Each and every VyOS +component comes with it's own `Jenkinsfile` which is (more or less) a copy. +The Pipeline utilizes the Docker container from the `build_iso` section - +but instead of building it from source on every run, we rather always fetch a +fresh copy (if needed) from [Dockerhub](https://hub.docker.com/u/vyos/). + +Each module is build on demand if a new commit on the branch in question is +found. After a successful run the resulting Debian Package(s) will be deployed +to our Debian repository which is used during build time. It is located here: +<http://dev.packages.vyos.net/repositories/>. diff --git a/docs/contributing/md-issues-features.md b/docs/contributing/md-issues-features.md new file mode 100644 index 00000000..c481fec5 --- /dev/null +++ b/docs/contributing/md-issues-features.md @@ -0,0 +1,60 @@ +# Issues/Feature requests + +## Bug Report/Issue + +Issues or bugs are found in any software project. VyOS is not an exception. + +All issues should be reported to the developers. This lets the developers know +what is not working properly. Without this sort of feedback every developer +will believe that everything is working correctly. + +### I have found a bug, what should I do? + +When you believe you have found a bug, it is always a good idea to verify the +issue prior to opening a bug request. + +- Consult the [documentation](https://docs.vyos.io) to ensure that you have configured your system + correctly +- Get community support via [Slack](https://slack.vyos.io) or our [Forum](https://forum.vyos.io) + +### Ensure the problem is reproducible + +When you are able to verify that it is actually a bug, spend some time to +document how to reproduce the issue. This documentation can be invaluable. + +When you wish to have a developer fix a bug that you found, helping them +reproduce the issue is beneficial to everyone. Be sure to include information +about the hardware you are using, commands that you were running, any other +activities that you may have been doing at the time. This additional +information can be very useful. + +- What were you attempting to achieve? +- What was the configuration prior to the change? +- What commands did you use? Use e.g. `run show configuration commands` + +### Include output + +The output you get when you find a bug can provide lots of information. If you +get an error message on the screen, copy it exactly. Having the exact message +can provide detail that the developers can use. Like wise if you have any log +messages that also are from the time of the issue, include those. They may +also contain information that is helpful for the development team. + +### Report a Bug + +In order to open up a bug-report/feature request you need to create yourself +an account on VyOS [Phabricator](). On the left side of the specific project (VyOS +1.2 or VyOS 1.3) you will find quick-links for opening a bug-report/feature +request. + +- Provide as much information as you can +- Which version of VyOS are you using? `run show version` +- How can we reproduce this Bug? + +## Feature Request + +You have an idea of how to make VyOS better or you are in need of a specific +feature which all users of VyOS would benefit from? To send a feature request +please search [Phabricator]() if there is already a request pending. You can +enhance it or if you don't find one, create a new one by use the quick link in +the left side under the specific project. diff --git a/docs/contributing/md-testing.md b/docs/contributing/md-testing.md new file mode 100644 index 00000000..4f406e05 --- /dev/null +++ b/docs/contributing/md-testing.md @@ -0,0 +1,225 @@ +# Testing + +One of the major advantages introduced in VyOS 1.3 is an automated test +framework. When assembling an ISO image multiple things can go wrong badly and +publishing a faulty ISO makes no sense. The user is disappointed by the quality +of the image and the developers get flodded with bug reports over and over +again. + +As the VyOS documentation is not only for users but also for the developers - +and we keep no secret documentation - this section describes how the automated +testing works. + +## Jenkins CI + +Our [VyOS CI]() system is based on Jenkins and builds all our required packages +for VyOS 1.2 to 1.4. In addition to the package build, there is the vyos-build +Job which builds and tests the VyOS ISO image which is published after a +successful test drive. + +We differentiate in two independent tests, which are both run in parallel by +two separate QEmu instances which are launched via `make test` and `make testc` from within the [vyos-build]() repository. + +## Smoketests + +Smoketests executes predefined VyOS CLI commands and checks if the desired +daemon/service configuration is rendert - that is how to put it "short". + +When and ISO image is assembled by the [VyOS CI](), the `BUILD_SMOKETEST` +parameter is enabled by default, which will extend the ISO configuration line +with the following packages: + +``` python +def CUSTOM_PACKAGES = '' + if (params.BUILD_SMOKETESTS) + CUSTOM_PACKAGES = '--custom-package vyos-1x-smoketest' +``` + +So if you plan to build your own custom ISO image and want to make use of our +smoketests, ensure that you have the <span class="title-ref">vyos-1x-smoketest</span> package installed. + +The `make test` command from the [vyos-build]() repository will launch a new +QEmu instance and the ISO image is first installed to the virtual harddisk. + +After its first boot into the newly installed system the main Smoketest script +is executed, it can be found here: <span class="title-ref">/usr/bin/vyos-smoketest</span> + +The script only searches for executable "test-cases" under +`/usr/libexec/vyos/tests/smoke/cli/` and executes them one by one. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +As Smoketests will alter the system configuration and you are logged +in remote you may loose your connection to the system. + +</div> + +### Manual Smoketest Run + +On the other hand - as each test is contain in its own file - one can always +execute a single Smoketest by hand by simply running the Python test scripts. + +Example: + +``` none +vyos@vyos:~$ /usr/libexec/vyos/tests/smoke/cli/test_protocols_bgp.py +test_bgp_01_simple (__main__.TestProtocolsBGP) ... ok +test_bgp_02_neighbors (__main__.TestProtocolsBGP) ... ok +test_bgp_03_peer_groups (__main__.TestProtocolsBGP) ... ok +test_bgp_04_afi_ipv4 (__main__.TestProtocolsBGP) ... ok +test_bgp_05_afi_ipv6 (__main__.TestProtocolsBGP) ... ok +test_bgp_06_listen_range (__main__.TestProtocolsBGP) ... ok +test_bgp_07_l2vpn_evpn (__main__.TestProtocolsBGP) ... ok +test_bgp_08_zebra_route_map (__main__.TestProtocolsBGP) ... ok +test_bgp_09_distance_and_flowspec (__main__.TestProtocolsBGP) ... ok +test_bgp_10_vrf_simple (__main__.TestProtocolsBGP) ... ok +test_bgp_11_confederation (__main__.TestProtocolsBGP) ... ok +test_bgp_12_v6_link_local (__main__.TestProtocolsBGP) ... ok +test_bgp_13_solo (__main__.TestProtocolsBGP) ... ok + +---------------------------------------------------------------------- +Ran 13 tests in 348.191s + +OK +``` + +### Interface based tests + +Our smoketests not only test daemons and serives, but also check if what we +configure for an interface works. Thus there is a common base classed named: +`base_interfaces_test.py` which holds all the common code that an interface +supports and is tested. + +Those common tests consists out of: + +- Add one or more IP addresses +- DHCP client and DHCPv6 prefix delegation +- MTU size +- IP and IPv6 options +- Port description +- Port disable +- VLANs (QinQ and regular 802.1q) +- ... + +<div class="note"> + +<div class="title"> + +Note + +</div> + +When you are working on interface configuration and you also want to +test if the Smoketests pass you would normally loose the remote SSH connection +to your `DUT (Device Under Test)`. To handle this issue, some of the +interface based tests can be called with an environment variable beforehand +to limit the number of interfaces used in the test. By default all interface +e.g. all Ethernet interfaces are used. + +</div> + +``` none +vyos@vyos:~$ TEST_ETH="eth1 eth2" /usr/libexec/vyos/tests/smoke/cli/test_interfaces_bonding.py +test_add_multiple_ip_addresses (__main__.BondingInterfaceTest) ... ok +test_add_single_ip_address (__main__.BondingInterfaceTest) ... ok +test_bonding_hash_policy (__main__.BondingInterfaceTest) ... ok +test_bonding_lacp_rate (__main__.BondingInterfaceTest) ... ok +test_bonding_min_links (__main__.BondingInterfaceTest) ... ok +test_bonding_remove_member (__main__.BondingInterfaceTest) ... ok +test_dhcpv6_client_options (__main__.BondingInterfaceTest) ... ok +test_dhcpv6pd_auto_sla_id (__main__.BondingInterfaceTest) ... ok +test_dhcpv6pd_manual_sla_id (__main__.BondingInterfaceTest) ... ok +test_interface_description (__main__.BondingInterfaceTest) ... ok +test_interface_disable (__main__.BondingInterfaceTest) ... ok +test_interface_ip_options (__main__.BondingInterfaceTest) ... ok +test_interface_ipv6_options (__main__.BondingInterfaceTest) ... ok +test_interface_mtu (__main__.BondingInterfaceTest) ... ok +test_ipv6_link_local_address (__main__.BondingInterfaceTest) ... ok +test_mtu_1200_no_ipv6_interface (__main__.BondingInterfaceTest) ... ok +test_span_mirror (__main__.BondingInterfaceTest) ... ok +test_vif_8021q_interfaces (__main__.BondingInterfaceTest) ... ok +test_vif_8021q_lower_up_down (__main__.BondingInterfaceTest) ... ok +test_vif_8021q_mtu_limits (__main__.BondingInterfaceTest) ... ok +test_vif_8021q_qos_change (__main__.BondingInterfaceTest) ... ok +test_vif_s_8021ad_vlan_interfaces (__main__.BondingInterfaceTest) ... ok +test_vif_s_protocol_change (__main__.BondingInterfaceTest) ... ok + +---------------------------------------------------------------------- +Ran 23 tests in 244.694s + +OK +``` + +This will limit the <span class="title-ref">bond</span> interface test to only make use of <span class="title-ref">eth1</span> and <span class="title-ref">eth2</span> +as member ports. + +## Config Load Tests + +The other part of our tests are called "config load tests". The config load tests +will load - one after another - arbitrary configuration files to test if the +configuration migration scripts work as designed and that a given set of +functionality still can be loaded with a fresh VyOS ISO image. + +The configurations are all derived from production systems and can not only act +as a testcase but also as reference if one wants to enable a certain feature. +The configurations can be found here: +<https://github.com/vyos/vyos-1x/tree/current/smoketest/configs> + +The entire test is controlled by the main wrapper script `/usr/bin/vyos-configtest` +which behaves in the same way as the main smoketest script. It scans the folder +for potential configuration files and issues a `load` command one after another. + +### Manual config load test + +One is not bound to load all configurations one after another but can also load +individual test configurations on his own. + +``` none +vyos@vyos:~$ configure +load[edit] + +vyos@vyos# load /usr/libexec/vyos/tests/config/ospf-small +Loading configuration from '/usr/libexec/vyos/tests/config/ospf-small' +Load complete. Use 'commit' to make changes effective. +[edit] +vyos@vyos# compare +[edit interfaces ethernet eth0] +-hw-id 00:50:56:bf:c5:6d +[edit interfaces ethernet eth1] ++duplex auto +-hw-id 00:50:56:b3:38:c5 ++speed auto +[edit interfaces] +-ethernet eth2 { +- hw-id 00:50:56:b3:9c:1d +-} +-vti vti1 { +- address 192.0.2.1/30 +-} +... + +vyos@vyos# commit +vyos@vyos# +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Some of the configurations have preconditions which need to be met. +Those most likely include generation of crypographic keys before the config +can be applied - you will get a commit error otherwise. If you are interested +how those preconditions are fulfilled check the [vyos-build]() repository and +the `scripts/check-qemu-install` file. + +</div> diff --git a/docs/contributing/md-upstream-packages.md b/docs/contributing/md-upstream-packages.md new file mode 100644 index 00000000..bc0eeed1 --- /dev/null +++ b/docs/contributing/md-upstream-packages.md @@ -0,0 +1,77 @@ +# Upstream packages + +Many base system packages are pulled straight from Debian's main and contrib +repositories, but there are exceptions. + +This chapter lists those exceptions and gives you a brief overview what we +have done on those packages. If you only want to build yourself a fresh ISO +you can completely skip this chapter. It may become interesting once you have +a VyOS deep dive. + +## vyos-netplug + +Due to issues in the upstream version that sometimes set interfaces down, a +modified version is used. + +The source is located at <https://github.com/vyos/vyos-netplug> + +In the future, we may switch to using systemd infrastructure instead. Building +it doesn't require a special procedure. + +## keepalived + +Keepalived normally isn't updated to newer feature releases between Debian +versions, so we are building it from source. + +Debian does keep their package in git, but it's upstream tarball imported into +git without its original commit history. To be able to merge new tags in, we +keep a fork of the upstream repository with packaging files imported from +Debian at <https://github.com/vyos/keepalived-upstream> + +## strongswan + +Our StrongSWAN build differs from the upstream: + +- strongswan-nm package build is disabled since we don't use NetworkManager +- Patches for DMVPN are merged in + +The source is at <https://github.com/vyos/vyos-strongswan> + +DMVPN patches are added by this commit: +<https://github.com/vyos/vyos-strongswan/commit/1cf12b0f2f921bfc51affa3b81226> + +Our op mode scripts use the python-vici module, which is not included in +Debian's build, and isn't quite easy to integrate in that build. For this +reason we debianize that module by hand now, using this procedure: + +0. Install <https://pypi.org/project/stdeb/> +1. <span class="title-ref">cd vyos-strongswan</span> +2. <span class="title-ref">./configure --enable-python-eggs</span> +3. <span class="title-ref">cd src/libcharon/plugins/vici/python</span> +4. <span class="title-ref">make</span> +5. <span class="title-ref">python3 setup.py --command-packages=stdeb.command bdist_deb</span> + +The package ends up in deb_dist dir. + +## mdns-repeater + +This package doesn't exist in Debian. A debianized fork is kept at +<https://github.com/vyos/mdns-repeater> + +No special build procedure is required. + +## udp-broadcast-relay + +This package doesn't exist in Debian. A debianized fork is kept at +<https://github.com/vyos/udp-broadcast-relay> + +No special build procedure is required. + +## hvinfo + +A fork with packaging changes for VyOS is kept at <https://github.com/vyos/hvinfo> + +The original repo is at <https://github.com/dmbaturin/hvinfo> + +It's an Ada program and requires GNAT and gprbuild for building, dependencies +are properly specified so just follow debuild's suggestions. diff --git a/docs/installation/cloud/md-aws-ha.md b/docs/installation/cloud/md-aws-ha.md new file mode 100644 index 00000000..8cdfda44 --- /dev/null +++ b/docs/installation/cloud/md-aws-ha.md @@ -0,0 +1,132 @@ +\########## +VyOS High Availability (HA) Deployment on AWS +\########## + +This document describes how to deploy VyOS in a High Availability (HA) configuration on AWS using Terraform and a VPC Route Server to provide sub-second failover. + +# Why Use HA on AWS? + +This solution helps organizations achieve **high availability** routing with dynamic connectivity to multiple AWS VPCs or hybrid environments. + +Key Advantages: + +- Utilizes **AWS VPC Route Server** to manage BGP routes dynamically. +- Deploys two VyOS EC2 instances as BGP peers connected to the Route Server. Although both participate, one is typically preferred as the next-hop. +- Employs **Bidirectional Forwarding Detection (BFD)** for rapid failure detection. +- On failure: + - Withdraws the failed peer’s routes from the RIB. + - Recomputes the optimal path in the FIB. + - Updates VPC route tables to point to the active instance. +- Enables **sub-second failover** (\< 1 s), outperforming AWS API-based route table failover. + +This architecture supports: + +- Cloud edge routing with failover. +- Hybrid cloud resiliency. +- Rapid recovery during instance crashes, upgrades, or network disruptions. +- Continuity for mission-critical operations. + +# HA Architecture Diagram + +<figure> +<img src="/_static/images/cloud-aws-ha-architecture.webp" alt="VyOS HA topology diagram" /> +</figure> + +# Terraform Automation + +To streamline and standardize the process, we developed a Terraform project that automates the deployment of VyOS in High Availability (HA) mode on AWS. + +This Terraform project automates the deployment of: + +- Two VyOS instances in HA mode. +- VPC Route Server. +- Transit Gateway. +- A Transit VPC and a Data VPC containing a test Amazon Linux EC2 instance for connectivity validation. + +To integrate with existing AWS infrastructure: + +- Remove the Data VPC, its subnets, and EC2 test instance. +- Update <span class="title-ref">main.tf</span>, <span class="title-ref">network.tf</span>, <span class="title-ref">transit_gateway.tf</span>, <span class="title-ref">variables.tf</span>, and <span class="title-ref">outputs.tf</span> accordingly. + +# Prerequisites + +AWS Environment: + +- Active AWS account with permissions for EC2, VPC, Transit Gateway, Route Server, and IAM (for keypair and role management). + +Local Environment: + +- AWS CLI installed: <https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html> +- Terraform installed: <https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli> + +Set AWS credentials in your shell: + +``` none +export AWS_ACCESS_KEY_ID="<AWS_ACCESS_KEY_ID>" +export AWS_SECRET_ACCESS_KEY="<AWS_SECRET_ACCESS_KEY>" +export AWS_SESSION_TOKEN="<AWS_SESSION_TOKEN>" +export AWS_DEFAULT_REGION="<AWS_REGION>" # e.g., us-east-1 +``` + +Obtain VyOS AMI ID and Owner ID: + +Subscribe to VyOS via AWS Marketplace. Then run: + +``` none +aws ec2 describe-images \ + --owners aws-marketplace \ + --filters "Name=product-code,Values=8wqdkv3u2b9sa0y73xob2yl90" \ + --query 'Images[*].[ImageId,OwnerId,Name]' \ + --output table +``` + +Alternatively, set the <span class="title-ref">vyos_ami_id</span> variable directly in <span class="title-ref">variables.tf</span>. + +Generate an SSH keypair (or use the included demo key): + +``` none +ssh-keygen -b 2048 -t rsa -m PEM -f keys/vyos_custom_key.pem +chmod 400 keys/vyos_custom_key.pem +``` + +# Usage + +Configure variables in <span class="title-ref">variables.tf</span>, including instance type, region, and <span class="title-ref">vyos_ami_id</span>. + +Terraform Workflow: + +``` none +terraform init +terraform fmt +terraform validate +terraform plan +terraform apply +``` + +On completion, run: + +``` none +terraform output +``` + +This displays the management IP and connectivity test results. + +To clean up: + +``` none +terraform destroy +``` + +# Management + +SSH into VyOS: + +``` none +ssh vyos@<vyos_public_ip> -i keys/vyos_custom_key.pem +``` + +# GitHub Repository + +You can clone or download the Terraform project and use them in your environment: + +<https://github.com/vyos/vyos-automation/tree/main/Terraform/AWS/ha-instances-with-configs> diff --git a/docs/installation/cloud/md-aws-to-azure.md b/docs/installation/cloud/md-aws-to-azure.md new file mode 100644 index 00000000..87effb97 --- /dev/null +++ b/docs/installation/cloud/md-aws-to-azure.md @@ -0,0 +1,177 @@ +\########## +VyOS Deployment on AWS and Azure for Secure Cloud-to-Cloud Connectivity +\########## + +This document provides step-by-step guidance for deploying VyOS routers on both AWS and Azure. +It describes how to establish secure inter-cloud connectivity using IPsec tunnels with BGP, +automated through Terraform. Example workloads (Amazon Linux EC2 on AWS and Ubuntu VM on Azure) +are also deployed for connectivity validation. + +# Why Cloud-to-Cloud Connectivity? + +Cloud-to-cloud connectivity is needed in modern multi-cloud environments for several reasons: + +- **Inter-Cloud Connectivity** + + Enable secure and reliable communication between workloads in different clouds + (for example, AWS applications connecting to Azure-hosted identity services). + +- **Cloud-to-Cloud Migration** + + During migration projects, workloads may temporarily run in both clouds. + Direct tunnels ensure smooth transition and synchronization. + +- **Testing and Validation** + + Labs and proof-of-concepts often simulate multi-cloud architectures. + A VyOS-based tunnel lets teams test routing, encryption, and failover before production rollout. + +# Architecture + +The architecture consists of VyOS routers deployed in both AWS and Azure, connected via secure IPsec tunnels. +BGP is used for dynamic routing between the clouds, allowing for seamless communication. + +<figure> +<img src="/_static/images/cloud-aws-to-azure.webp" alt="VyOS Cloud-to-Cloud topology diagram" /> +</figure> + +# Terraform Automation + +To streamline and standardize the deployment process, a set of **Terraform projects** has been developed. +These projects automate the provisioning of **VyOS instances** and the required networking resources across **AWS** and **Azure**. + +In addition to deploying VyOS, these projects also provision an **Amazon Linux EC2 instance** on AWS and an **Ubuntu VM** on Azure. +These serve as test endpoints to validate connectivity between the cloud environments. + +# Prerequisites + +## AWS Environment + +- Active AWS account with permissions for EC2, VPC, Transit Gateway, Route Server, and IAM (for keypair and role management). + +Local Environment: + +- AWS CLI installed: <https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html> +- Terraform installed: <https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli> + +Set AWS credentials in your shell: + +``` none +export AWS_ACCESS_KEY_ID="<AWS_ACCESS_KEY_ID>" +export AWS_SECRET_ACCESS_KEY="<AWS_SECRET_ACCESS_KEY>" +export AWS_SESSION_TOKEN="<AWS_SESSION_TOKEN>" +export AWS_DEFAULT_REGION="<AWS_REGION>" # e.g., us-east-1 +``` + +Obtain VyOS AMI ID and Owner ID: + +Subscribe to VyOS via AWS Marketplace. Then run: + +``` none +aws ec2 describe-images \ + --owners aws-marketplace \ + --filters "Name=product-code,Values=8wqdkv3u2b9sa0y73xob2yl90" \ + --query 'Images[*].[ImageId,OwnerId,Name]' \ + --output table +``` + +Alternatively, set the `vyos_ami_id` variable directly in `variables.tf`. + +Generate an SSH keypair (or use the included demo key): + +``` none +ssh-keygen -b 2048 -t rsa -m PEM -f keys/vyos_custom_key.pem +chmod 400 keys/vyos_custom_key.pem +``` + +## Azure Environment + +- Active Azure subscription: + +``` none +az account set --subscription "<subscription ID or name>" +``` + +- Azure CLI installed: + + <https://learn.microsoft.com/en-us/cli/azure/install-azure-cli> + +- Logged in with Azure credentials: + +``` none +az version +az login +``` + +- Azure Resource Group (RG) created: + +``` none +az group create --name demoResourceGroup --location westus +az group list +az group show --name demoResourceGroup +``` + +- Terraform installed: + + <https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli> + +- SSH key generated: + +``` none +ssh-keygen -t rsa -b 4096 -f keys/id_rsa +chmod 400 keys/id_rsa +``` + +# Usage + +## AWS + +All variables needed for customization are defined in `variables.tf`. +Adjust them according to your requirements, such as EC2 instance type and networking configurations. + +Before deployment, ensure you check `aws_region`, `availability_zone`, and update `vyos_ami_id` as necessary. + +## Azure + +All variables needed for customization are defined in `variables.tf`. +Adjust them according to your requirements, such as VM size and networking configurations. + +Before deployment, ensure you check `azure_region`, `availability_zone`, and update `subscription_id` and `resource_group_name` as necessary. + +## Terraform Workflow + +``` none +terraform init +terraform fmt +terraform validate +terraform plan +terraform apply +``` + +On completion, run: + +``` none +terraform output +``` + +This displays the public IP addresses of the VyOS instances. + +To clean up: + +``` none +terraform destroy +``` + +# Management + +SSH into VyOS: + +``` none +ssh vyos@<vyos_public_ip> -i keys/vyos_custom_key.pem +``` + +# GitHub Repository + +You can clone or download the Terraform projects and use them in your environment: + +<https://github.com/vyos/vyos-automation/tree/main/Terraform/Cloud-to-Cloud> diff --git a/docs/installation/cloud/md-aws.md b/docs/installation/cloud/md-aws.md new file mode 100644 index 00000000..523fd280 --- /dev/null +++ b/docs/installation/cloud/md-aws.md @@ -0,0 +1,722 @@ +\########## +VyOS Deployment on AWS +\########## + +This manual provides detailed step-by-step instructions for deploying a VyOS instance and required resources (VPC, ENIs, Subnets, Security Groups) on AWS. + +Prerequisites +======== + +1\. AWS Account +----------- +Ensure you have an AWS account with administrative access. + +2\. IAM Permissions +----------- + +To deploy VyOS and related resources, the user must have the following permissions: + +- `ec2:` for managing EC2, ENIs, and EIPs. +- `vpc:` for creating VPCs, subnets, and route tables. +- `iam:` for attaching roles. + +3\. SSH Key Pair +----------- + +You can use Amazon EC2 to create your key pairs, or you can use a third-party tool to create your key pairs and then import them to Amazon EC2. +Amazon EC2 supports: + +- `2048-bit SSH-2 RSA keys` for Linux and Windows instances. +- `ED25519 keys` for Linux instances (not supported for Windows). + +When you create a key pair using Amazon EC2: + +- The `public key` is stored in Amazon EC2. +- You store the `private key` securely on your local machine. + +Steps to Create a Key Pair Using Amazon EC2 +^^^^^^^^^^^^^^ + +- Open the Amazon EC2 console <https://console.aws.amazon.com/ec2/>. +- In the navigation pane, under `Network & Security`, choose `Key Pairs`. + +<figure> +<img src="/_static/images/cloud-aws-keypair-01.webp" /> +</figure> + +- Choose `Create key pair` and select `AWS region` at the top right corner of the windows where you plan to deploy the VyOS instance. + +<figure> +<img src="/_static/images/cloud-aws-keypair-02.webp" /> +</figure> + +\- Configure Key Pair: +"""""""""" + +> - **Name**: Enter a descriptive name for the key pair, e.g., `vyos-keypair`. +> +> > <div class="note"> +> > +> > <div class="title"> +> > +> > Note +> > +> > </div> +> > +> > The key name can include up to 255 ASCII characters. It cannot include leading or trailing spaces. +> > +> > </div> +> +> - **Select Key Pair Type**: +> - For **Linux instances**: Choose either **RSA** or **ED25519**. +> +> - For **Windows instances**: Choose **RSA**. +> +> <div class="note"> +> +> <div class="title"> +> +> Note +> +> </div> +> +> ED25519 keys are not supported for Windows instances. +> +> </div> +> - **Private Key File Format**: +> - **PEM**: Choose this format if using OpenSSH or other SSH clients (e.g., on Linux/macOS). +> - **PPK**: Choose this format if using PuTTY on Windows. + +- **Optional**: Add tags to the key pair. Choose **Add tag** and provide the **key** and **value** for each tag. + +- Choose **Create key pair**. + +- The private key file will automatically download to your browser. + - The file name will match the name you provided (e.g., <span class="title-ref">vyos-keypair.pem</span>), with the extension determined by the format you chose. + +<figure> +<img src="/_static/images/cloud-aws-keypair-03.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-aws-keypair-04.webp" alt="Important Notes" /> +<figcaption aria-hidden="true"><strong>Important Notes</strong></figcaption> +</figure> + +- **Save the private key file securely**: + This is your **only chance** to download the private key. If you lose it, you cannot connect to your instance. + +- If you are using SSH on a **macOS or Linux computer**, set the correct permissions for the private key file: + +``` none +chmod 400 vyos-keypair.pem +``` + +If permissions are not set to **400**, you will encounter an **"Unprotected private key file"** error when attempting to connect to the instance. + +> **Example Usage for SSH** + +``` none +ssh -i vyos-keypair.pem vyos@<Public/Elastic IP> +``` + +For more information, please visit the official AWS documentation: + +<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/create-key-pairs.html#having-ec2-create-your-key-pair> + +4\. VyOS Subscription +----------- +- Go to the AWS Marketplace <https://aws.amazon.com/marketplace> and search for **VyOS**. +- Subscribe to the VyOS AMI. + +For more information, please visit: + +<https://aws.amazon.com/marketplace/seller-profile?id=7636d180-1710-48bc-acd6-d323c4a0429f> + +Create required resources +======== + +Certain resources need to be created in the AWS infrastructure before creating a VyOS instance, such as a VPC, Subnets, Elastic IPs, Route Tables, Security Groups, and others. + +Step 1: Create Virtual Private Cloud (VPC) and Subnets +----------- + +1\. Create a VPC +^^^^^^^^^^^^^^ + +To create a VPC for your AWS environment: + +- Go to the **Amazon VPC Console** at <https://console.aws.amazon.com/vpc/>. +- In the navigation pane, choose **Your VPCs**. +- Choose **Create VPC**. + +<figure> +<img src="/_static/images/cloud-aws-vpc-01.webp" /> +</figure> + +- **Configure VPC Settings**: + - **Name tag - optional**: Enter a descriptive name for your VPC, e.g., `VyOS-VPC`. + - **IPv4 CIDR Block**: Enter `10.0.0.0/16`. + +- Choose **Create VPC**. + +<figure> +<img src="/_static/images/cloud-aws-vpc-02.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-aws-vpc-03.webp" /> +</figure> + +For more information, please visit the AWS documentation: + +<https://docs.aws.amazon.com/vpc/latest/userguide/create-vpc.html> + +2\. Create Subnets +^^^^^^^^^^^^^^ + +Subnets allow you to divide your VPC into smaller IP spaces. Follow these steps to create subnets for both **public** and **private** networks: + +- Go to the **Amazon VPC Console** at <https://console.aws.amazon.com/vpc/>. +- In the navigation pane, choose **Subnets**. +- Choose **Create Subnet**. + +<figure> +<img src="/_static/images/cloud-aws-subnet-01.webp" /> +</figure> + +\- Configure Subnet Settings: +"""""""""" + +> - **Public Subnet**: +> - **VPC**: Select `VyOS-VPC`. +> - **Name Tag**: `VyOS-Public-Subnet`. +> - **IPv4 CIDR Block**: `10.0.1.0/24`. +> - **Availability Zone**: Select an AZ, e.g., `us-east-1a`. +> - **Private Subnet**: +> - **VPC**: Select `VyOS-VPC`. +> - **Name Tag**: `VyOS-Private-Subnet`. +> - **IPv4 CIDR Block**: `10.0.2.0/24`. +> - **Availability Zone**: Select an AZ, e.g., `us-east-1a`. + +- Choose **Create Subnet**. + +<figure> +<img src="/_static/images/cloud-aws-subnet-02.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-aws-subnet-03.webp" /> +</figure> + +For additional information, please visit the AWS documentation: + +<https://docs.aws.amazon.com/vpc/latest/userguide/create-subnets.html> + +For additional details about IP addressing for your VPC and subnets, refer to the AWS documentation: + +<https://docs.aws.amazon.com/vpc/latest/userguide/vpc-ip-addressing.html> + +Step 2: Create and Configure Security Groups +----------- + +1\. Create Public Security Group +^^^^^^^^^^^^^^ + +The **Public Security Group** is used for **outbound connectivity**. All external resources, systems, or networks will connect via this security group. + +- Open the **Amazon EC2 Console** at <https://console.aws.amazon.com/ec2/>. +- In the navigation pane, choose **Security Groups**. +- Choose **Create Security Group**. + +<figure> +<img src="/_static/images/cloud-aws-sg-01.webp" /> +</figure> + +- **Configure the Security Group**: + + > - **Name**: `VyOS-Public-SG`. + > - **Description**: "Public security group for outbound connectivity" + > - **VPC**: Select the VPC in which your VyOS instance resides. + +\- Inbound Rules: +"""""""""" + +> - **SSH**: Port `22`, Source `0.0.0.0/0` (Restrict to your IP for security). +> - **ICMP**: Allow for ping testing purposes. +> - **IPSec**: Allow port `500` (UDP) for ISAKMP (Phase 1 negotiation). +> - **NAT Traversal**: Allow port `4500` (UDP) for NAT-T support in IPsec. +> - **WireGuard**: Allow port `51820` (UDP). +> - **OpenVPN**: Allow port `1194` (UDP or TCP). + +<figure> +<img src="/_static/images/cloud-aws-sg-02.webp" /> +</figure> + +- (Optional) Add tags to identify the security group: + - **Key**: <span class="title-ref">Name</span>, **Value**: <span class="title-ref">VyOS-Public-SG</span>. + +- Choose **Create Security Group**. + +<figure> +<img src="/_static/images/cloud-aws-sg-03.webp" /> +</figure> + +2\. Create Private Security Group +^^^^^^^^^^^^^^ + +The **Private Security Group** is used for **internal connectivity** from internal or VPC-based resources. + +- Open the **Amazon EC2 Console**. +- In the navigation pane, choose **Security Groups**. +- Choose **Create Security Group**. + +\- Configure the Security Group: +"""""""""" + +> - **Name**: `VyOS-Private-SG`. +> - **Description**: "Private security group for internal connectivity" +> - **VPC**: Select the VPC in which your VyOS instance resides. + +\- Inbound Rules: +"""""""""" + +> - Allow **All Traffic** (`0.0.0.0/0`) for internal connectivity between resources, VPCs, and other trusted networks. + +<figure> +<img src="/_static/images/cloud-aws-sg-04.webp" /> +</figure> + +- (Optional) Add tags to identify the security group: + - **Key**: `Name`, **Value**: `VyOS-Private-SG`. + +- Choose **Create Security Group**. + +<figure> +<img src="/_static/images/cloud-aws-sg-05.webp" /> +</figure> + +For detailed instructions on creating a security group, refer to the official AWS documentation: + +<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/creating-security-group.html> + +For more information, refer to the official AWS documentation: + +<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html> + +Step 3: Create ENIs (Elastic Network Interfaces) +----------- + +Network Interfaces (ENIs) are essential for connecting instances to subnets and managing network traffic. Follow the steps below to create **Public** and **Private** ENIs. + +- Open the **Amazon EC2 Console** at <https://console.aws.amazon.com/ec2/>. +- In the navigation pane, choose **Network Interfaces**. +- Choose **Create Network Interface**. +- **Configure Network Interface Settings**: + +# Public ENI + +> - **Name**: `VyOS-Public-ENI`. +> - **Description**: "Network Interface for Public Subnet." +> - **Subnet**: Select the `VyOS-Public-Subnet` you created earlier. +> - **Private IPv4 Address**: Choose **Auto-assign** to let AWS pick an IP address from the subnet. +> - **Security Group**: Select the `VyOS-Public-SG`. +> +> \- (Optional) Add tags to identify the ENIs: +> **Key**: `Name`, **Value**: `VyOS-Public-ENI`. +> +> - Choose **Create Network Interface**. +> +> <figure> +> <img src="/_static/images/cloud-aws-eni-01.webp" /> +> </figure> + +Private ENI +"""""""""" +- **Name**: `VyOS-Private-ENI`. + +> - **Description**: "Network Interface for Private Subnet." +> - **Subnet**: Select the `VyOS-Private-Subnet` you created earlier. +> - **Private IPv4 Address**: Choose **Auto-assign** to let AWS pick an IP address from the subnet. +> - **Security Group**: Select the `VyOS-Private-SG`. +> +> \- (Optional) Add tags to identify the ENIs: +> **Key**: `Name`, **Value**: `VyOS-Private-ENI`. +> +> - Choose **Create Network Interface**. +> +> <figure> +> <img src="/_static/images/cloud-aws-eni-02.webp" /> +> </figure> + +Step 4: Configure Internet Gateway +----------- + +An **Internet Gateway** allows communication between your VPC and the internet. Follow the steps below to create and attach an Internet Gateway to your VPC. + +1\. Create an Internet Gateway +^^^^^^^^^^^^^^ + +- Open the **Amazon VPC Console** at <https://console.aws.amazon.com/vpc/>. + +- In the navigation pane, choose **Internet Gateways**. + +- Choose **Create Internet Gateway**. + +- **Configure Internet Gateway**: + - (Optional) **Name**: Enter a descriptive name, e.g., `VyOS-IGW`. + +- (Optional) Add a tag to identify the Internet Gateway: + - **Key**: `Name`, **Value**: `VyOS-IGW`. + +- Choose **Create Internet Gateway**. + +<figure> +<img src="/_static/images/cloud-aws-igw-01.webp" /> +</figure> + +2\. Attach the Internet Gateway to Your VPC +^^^^^^^^^^^^^^ + +To enable your VPC to access the internet, attach the Internet Gateway to your VPC: + +- After creating the Internet Gateway, select it from the **Internet Gateways** list. + +- Choose **Actions \> Attach to VPC**. + +- Select the VPC where you want to attach the Internet Gateway: + - Choose <span class="title-ref">VyOS-VPC</span> (the VPC you created earlier). + +- Choose **Attach Internet Gateway**. + +<figure> +<img src="/_static/images/cloud-aws-igw-02.webp" /> +</figure> + +For more details, refer to the official AWS documentation: + +<https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Internet_Gateway.html>. + +Step 5: Configure Route Tables +----------- + +Route tables define the paths for network traffic within your VPC. In this step, we will configure **Public** and **Private** route tables to control traffic flow for their respective subnets. + +1\. Create and Configure the Public Route Table +^^^^^^^^^^^^^^ + +- **Go to the Route Tables Section:** + - Open the **Amazon VPC Console** at <https://console.aws.amazon.com/vpc/>. + - In the left navigation pane, choose **Route Tables**. + +- **Create a New Route Table:** + + > - In the **Route Tables** section, choose **Create Route Table**. + > - Configure the route table: + > - **Name**: `Public RT`. + > - **VPC**: Select the `VyOS-VPC`. + > - Click **Create Route Table**. + > + > <figure> + > <img src="/_static/images/cloud-aws-route-01.webp" /> + > </figure> + +- **Add a Route to the Internet Gateway:** + + > - Go to the **Routes** tab and click **Edit Routes**. + > - Click **Add Route** and enter: + > - **Destination**: `0.0.0.0/0` (Default route to all IPs). + > - **Target**: Select the **Internet Gateway** (`VyOS-IGW`) you created earlier. + > - Click **Save Routes**. + > + > <figure> + > <img src="/_static/images/cloud-aws-route-02.webp" /> + > </figure> + +- **Associate the Public Subnet:** + + > - Go to the **Subnet Associations** tab and click **Edit Subnet Associations**. + > - Select the **Public Subnet** (`VyOS-Public-Subnet`). + > - Click **Save associations**. + > + > <figure> + > <img src="/_static/images/cloud-aws-route-03.webp" /> + > </figure> + +Step 6: Allocate and Attach Elastic IP (EIP) +----------- + +An **Elastic IP (EIP)** is a static, public IPv4 address designed for dynamic cloud computing. Elastic IP addresses can help maintain consistent connectivity to instances, even if they are stopped, rebooted, or replaced. + +- Elastic IP addresses are **public IPv4 addresses** and are reachable from the internet. +- They can be quickly remapped to different instances or network interfaces within your AWS account to mask failures. + +For more details, refer to the official AWS documentation: + +<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html>. + +Steps to Allocate and Attach Elastic IP +^^^^^^^^^^^^^^ + +1\. Allocate Elastic IP +"""""""""" + +- Open the **Amazon EC2 Console** at <https://console.aws.amazon.com/ec2/>. + +- In the navigation pane, choose **Elastic IPs**. + +- Choose **Allocate Elastic IP address**. + +- **Elastic IP address settings**: + - For **Public IPv4 address pool**, select **Amazon's pool of IPv4 addresses**. + +- (Optional) Add a tag: + - **Key**: `Name`, **Value**: `VyOS-EIP`. + +- Choose **Allocate**. + +<figure> +<img src="/_static/images/cloud-aws-eip-01.webp" /> +</figure> + +2\. Attach Elastic IP to Public ENI +"""""""""" + +- Go to **EC2 \> Elastic IPs**. + +- Select the **Elastic IP** you just allocated. + +- Choose **Actions \> Associate Elastic IP address**. + +- **Configure Association**: + + > - **Resource type**: Choose **Network Interface**. + > - **Network Interface**: Select the **VyOS-Public-ENI** created earlier. + > - **Private IPv4 Address**: Ensure it is correctly selected. + +- (Optional) Select **Allow the Elastic IP address to be reassociated** if the EIP is already associated with another resource. + +- Choose **Associate**. + +<figure> +<img src="/_static/images/cloud-aws-eip-02.webp" /> +</figure> + +**Why Use Elastic IP?** + +- **Consistency**: The EIP remains static, even if the instance stops or is replaced. +- **Failover**: If an instance fails, you can remap the EIP to a new instance to restore services quickly. +- **DNS Integration**: You can point your domain to the Elastic IP for consistent public access. + +For additional details, refer to the AWS documentation: + +<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/working-with-eips.html> + +Launch VyOS Instance +======== + +Follow the detailed instructions below to launch a VyOS instance in your AWS environment with two ENIs (Public and Private). + +- Open the **Amazon EC2 Console** at <https://console.aws.amazon.com/ec2/>. + +- In the EC2 dashboard, choose **Launch Instance**. + +- **Configure Instance Details**: + + > - **Name and Tags**: + > + > - Under **Name and tags**, enter a descriptive name for your instance, e.g., `VyOS-Instance`. + > + > <figure> + > <img src="/_static/images/cloud-aws-vyos-01.webp" /> + > </figure> + > + > - **Application and OS Images (AMI)**: + > + > - Choose **Browse more AMIs**. + > - Go to the **AWS Marketplace** tab and search for **VyOS**. + > - Choose the VyOS AMI that matches your requirements and click **Select**. + > + > <figure> + > <img src="/_static/images/cloud-aws-vyos-02.webp" /> + > </figure> + > + > <figure> + > <img src="/_static/images/cloud-aws-vyos-03.webp" /> + > </figure> + > + > - **Instance Type**: + > + > - Select the instance type that fits your workload. For example: + > - `c5n.large` (or larger recommended for VyOS). + > + > > <figure> + > > <img src="/_static/images/cloud-aws-vyos-04.webp" /> + > > </figure> + > + > - **Key pair (login)**: + > + > - For **Key pair name**, select the key pair you created earlier (`vyos-keypair`). + > - If you do not have a key pair, create a new one and download the private key file. + > + > <figure> + > <img src="/_static/images/cloud-aws-vyos-05.webp" /> + > </figure> + > + > - **Network Settings**: + > + > - **VPC**: Select `VyOS-VPC`. + > - **Subnet**: Select the **Public Subnet** (`VyOS-Public-Subnet`). + > - **Auto-assign Public IP**: **Disable**. + > - **Firewall (security groups)**: Select the **Select existing security group**. + > - **Common security groups**: Live empty (Do not select any security groups). + > + > <figure> + > <img src="/_static/images/cloud-aws-vyos-09.webp" /> + > </figure> + > + > - **Advanced network configuration** + > + > > - **Network interface 1** select `VyOS-Public-ENI` + > > + > > <figure> + > > <img src="/_static/images/cloud-aws-vyos-07.webp" /> + > > </figure> + > > + > > - Click to the **Add network interface** button + > > - **Network interface 2** select `VyOS-Private-ENI` + > > + > > <figure> + > > <img src="/_static/images/cloud-aws-vyos-08.webp" /> + > > </figure> + > > + > > - In **Subnet** deselect subnet + > > + > > <figure> + > > <img src="/_static/images/cloud-aws-vyos-10.webp" /> + > > </figure> + +- Review the instance configuration in the **Summary** panel and choose **Launch Instance**. + +- Wait until the instance status changes to **Running**. + +<figure> +<img src="/_static/images/cloud-aws-vyos-11.webp" /> +</figure> + +Connect to the VyOS instance +----------- + +> You can only connect to the VyOS instance via **SSH** protocol. Use the default username **vyos**, **Elastic IP** and **SSH Key Pair** to connect to the VyOS instance via SSH: +> +> ``` none +> ssh -i vyos-keypair.pem vyos@35.152.131.62 +> ``` + +Deployment of VyOS Instance and Required Resources via CloudFormation Template +======== + +These CloudFormation templates automate the deployment of a VyOS instance on AWS, configuring essential components such as: + +- VPC +- Public and private subnets +- Internet Gateway +- Route Tables +- Elastic IPs +- Security Groups + +You can download or clone these templates from the GitHub repository and use them in your environment: + +<https://github.com/vyos/vyos-automation/tree/main/CloudFormation> + +Deployment of VyOS Instance and Required Resources via Terraform +======== + +These Terraform projects automate the deployment of a VyOS instance on AWS, configuring essential components such as: + +- VPC +- Public and private subnets +- Internet Gateway +- Route Tables +- Elastic IPs +- Security Groups + +You can download or clone these templates from the GitHub repository and use them in your environment: + +<https://github.com/vyos/vyos-automation/tree/main/Terraform/AWS/> + +## Amazon CloudWatch Agent Usage + +To use Amazon CloudWatch Agent, configure it within the Amazon SSM Parameter Store. If you don't have a configuration yet, do `configuration_creation`. + +1. Create an `IAM (Identity and Access Management)` role for the `EC2 (Elastic Compute Cloud)` instance to access CloudWatch service, and name it CloudWatchAgentServerRole. The role should contain two default policies: CloudWatchAgentServerPolicy and AmazonSSMManagedInstanceCore. +2. Attach the created role to your VyOS `EC2 (Elastic Compute Cloud)` instance. +3. Ensure that amazon-cloudwatch-agent package is installed. + +> ``` none +> $ sudo apt list --installed | grep amazon-cloudwatch-agent +> ``` +> +> <div class="note"> +> +> <div class="title"> +> +> Note +> +> </div> +> +> The amazon-cloudwatch-agent package is normally included in VyOS 1.3.3+ and 1.4+ +> +> </div> + +3. Retrieve an existing CloudWatch Agent configuration from the `SSM (Systems Manager)` Parameter Store. + +> ``` none +> $ sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -s -c ssm:<your-configuration-name> +> ``` +> +> This step also enables systemd service and runs it. +> +> <div class="note"> +> +> <div class="title"> +> +> Note +> +> </div> +> +> The VyOS platform-specific scripts feature is under development. Thus, this step should be repeated manually after changing system image (`/installation/update`) +> +> </div> + +### CloudWatch SSM Configuration creation + +Creating the Amazon Cloudwatch Agent Configuration in Amazon `SSM (Systems Manager)` Parameter Store. + +1. Create an `IAM (Identity and Access Management)` role for your `EC2 (Elastic Compute Cloud)` instance to access the CloudWatch service. Name it CloudWatchAgentAdminRole. The role should contain at two default policies: CloudWatchAgentAdminPolicy and AmazonSSMManagedInstanceCore. + +> <div class="note"> +> +> <div class="title"> +> +> Note +> +> </div> +> +> CloudWatchAgentServerRole is too permissive and should be used for single configuration creation and deployment. That's why after completion of step \#3 highly recommended to replace instance CloudWatchAgentAdminRole role with CloudWatchAgentServerRole. +> +> </div> + +2. Run Cloudwatch configuration wizard. + +> ``` none +> $ sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-config-wizard +> ``` + +3. When prompted, answer "yes" to the question "Do you want to store the config in the SSM parameter store?". + +## References + +- <https://console.aws.amazon.com/> +- <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/create-iam-roles-for-cloudwatch-agent.html> +- <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-on-EC2-Instance-fleet.html> diff --git a/docs/installation/cloud/md-azure-ha.md b/docs/installation/cloud/md-azure-ha.md new file mode 100644 index 00000000..4a77565d --- /dev/null +++ b/docs/installation/cloud/md-azure-ha.md @@ -0,0 +1,130 @@ +\########## +VyOS High Availability (HA) Deployment on Azure +\########## + +This document describes how to deploy VyOS in a High Availability (HA) configuration on Azure using Terraform and Azure Route Server to provide sub-second failover. + +# Why Use HA on Azure? + +This module provides a robust, repeatable foundation for building **resilient network architectures** in Azure. By combining VyOS routing features with Terraform and Azure-native services, it enables: + +- Rapid deployment of cloud edge routers. +- Full control over BGP route advertisement and filtering. +- Realistic HA and disaster recovery simulations. +- Seamless integration with hybrid or multi-cloud infrastructure. + +The architecture includes: + +- Two VyOS routers in a Transit VNet, configured with BGP. +- Azure Route Server for dynamic route distribution. +- Site-to-Site VPN connections to a simulated on-premises VyOS router. +- An Ubuntu VM for connectivity and routing validation. +- A Data VNet for testing and diagnostics. + +# Key Features + +- **High Availability**: Dual VyOS routers for redundancy and failover. +- **Dynamic Routing**: BGP-based routing via Azure Route Server. +- **Hybrid Connectivity**: Site-to-Site VPN integration with a simulated on-prem VyOS. +- **Testing Environment**: Includes Ubuntu VM for verification and diagnostics. +- **Modular & Flexible**: Easily configurable via variables. + +# HA Architecture Diagram + +<figure> +<img src="/_static/images/cloud-azure-ha-architecture.webp" alt="VyOS HA topology diagram" /> +</figure> + +This deployment architecture simulates a real-world enterprise network scenario for testing and validation purposes. + +# Terraform Automation + +To streamline and standardize the process, we developed a Terraform project that automates the deployment of VyOS in High Availability (HA) mode on Azure. + +This Terraform project automates the deployment of: + +- Two VyOS instances in HA mode. +- Azure Route Server. +- A Transit VNet and a Data VNet containing a test Ubuntu VM for connectivity validation. + +# Prerequisites + +Ensure you have: + +- Active Azure subscription: + +``` none +az account set --subscription "<subscription ID or name>" +``` + +- Azure CLI installed: + + <https://learn.microsoft.com/en-us/cli/azure/install-azure-cli> + +- Logged in with Azure credentials: + +``` none +az version +az login +``` + +- Azure Resource Group (RG) created: + +``` none +az group create --name demoResourceGroup --location westus +az group list +az group show --name demoResourceGroup +``` + +- Terraform installed: + + <https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli> + +- SSH key generated: + +``` none +ssh-keygen -t rsa -b 4096 -f keys/vyos_custom_key.pem +chmod 400 keys/vyos_custom_key.pem +``` + +# Usage + +All variables are defined in `variables.tf`. Adjust them to match your environment. + +Terraform Workflow: + +``` none +terraform init +terraform fmt +terraform validate +terraform plan +terraform apply +``` + +On completion, run: + +``` none +terraform output +``` + +This displays the management IP and connectivity test results. + +To clean up: + +``` none +terraform destroy +``` + +# Management + +SSH into VyOS: + +``` none +ssh adminuser@<vyos_public_ip> -i keys/vyos_custom_key.pem +``` + +# GitHub Repository + +You can clone or download the Terraform project and use them in your environment: + +<https://github.com/vyos/vyos-automation/tree/main/Terraform/Azure/azure-ha-deployment-with-configs> diff --git a/docs/installation/cloud/md-azure.md b/docs/installation/cloud/md-azure.md new file mode 100644 index 00000000..8489a532 --- /dev/null +++ b/docs/installation/cloud/md-azure.md @@ -0,0 +1,449 @@ +\########## +VyOS Deployment on Azure +\########## + +This manual provides detailed step-by-step instructions for deploying a VyOS instance and required resources (Virtual Networks, Network Interfaces, Subnets, Security Groups) on Azure via the Azure Portal. + +Prerequisites for Deploying VyOS on Azure +======== + +Azure Account +----------- + +Ensure you have an active Azure subscription. + +Microsoft Entra ID Permissions +----------- + +To manage resources in **Azure Entra ID** (formerly Azure AD), you need appropriate permissions to handle **Virtual Networks**, **Public IP Addresses**, **Subnets**, and **Virtual Machines**. + +**Reference Documentation:** + +<https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/manage-roles-portal> + +<https://learn.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal> + +<https://learn.microsoft.com/en-us/azure/role-based-access-control/overview> + +Deployment Steps +======== + +Step 1: Create a Resource Group +----------- + +A resource group is a container that holds related resources for an Azure solution. The resource group can include all the resources for the solution, or only those resources that you want to manage as a group. + +Create resource groups +^^^^^^^^^^^^^^ + +- Go to the Azure Portal <https://portal.azure.com/>. +- Sign in with your Azure account credentials. +- In the portal, search for and select **Resource groups**. +- Select **Create**. + +<figure> +<img src="/_static/images/cloud-azure-rg-01.webp" /> +</figure> + +- Enter the following values: +- **Subscription**: Select your Azure subscription. +- **Resource group**: Enter a new resource group name, e.g., `VyOSResourceGroup`. +- **Region**: Select an Azure location, such as Central US. +- Select **Review + Create** +- Select **Create**. It takes a few seconds to create a resource group. + +<figure> +<img src="/_static/images/cloud-azure-rg-02.webp" /> +</figure> + +Step 2: Create a Virtual Network (VNet) and Subnets +----------- + +Sign in to the Azure portal with your Azure account <https://portal.azure.com/> + +- In the portal, search for and select **Virtual networks**. +- On the **Virtual networks** page, select **+ Create**. +- On the **Basics** tab of **Create virtual network**, enter, or select the following information: +- **Subscription**: Select your Subscription +- **Resource Group**: Select e.g., `VyOSResourceGroup` +- **Name**: e.g., `VyOS-VirtualNetwork` +- **Region**: e.g., `West Europe`. + +<figure> +<img src="/_static/images/cloud-azure-vnet-01.webp" /> +</figure> + +**IP addresses**: + +- Address Space: `10.1.0.0/16` + +<figure> +<img src="/_static/images/cloud-azure-vnet-02.webp" /> +</figure> + +**Add two subnets**: + +- Name: e.g., `VyOS-Private-Subnet` + + Starting address: e.g., `10.1.1.0` + + Size: `/24` + +- Name: e.g., `VyOS-Public-Subnet` + + Starting address: e.g., `10.1.11.0` + + Size: `/24` + +<figure> +<img src="/_static/images/cloud-azure-vnet-03.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-azure-vnet-04.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-azure-vnet-05.webp" /> +</figure> + +- Click **Review + Create** and then **Create**. + +Step 3: Create and configure Network Security Group (NSG) +----------- + +- In the Azure Portal, search for and select **Network Security Groups**. +- On the **Network Security Groups** page, select **+ Create**. + +Enter the details: + +- **Subscription**: Select your Subscription +- **Resource Group**: Select `VyOSResourceGroup` +- **Name**: e.g., `VyOS-SecurityGroup` +- **Region**: e.g., `West Europe`. + +<figure> +<img src="/_static/images/cloud-azure-sg-01.webp" /> +</figure> + +- Click **Review + Create** and then **Create**. + +**Add inbound rules**: + +- Navigate to the **Network Security Groups** select **VyOS-SecurityGroup** go to **Inbound security rules** under **Settings** + +<figure> +<img src="/_static/images/cloud-azure-sg-02.webp" /> +</figure> + +**Add Rule Example:** + +- **Rule 1**: AllowSSH + + > - **Port**: 22 + > - **Protocol**: TCP + > - **Source**: Any + > - **Priority**: 1001 + +**Add Additional Rules**: + +You can add inbound rules based on your specific services, such as: + +> - ESP +> - OpenVPN +> - WireGuard, etc. + +<figure> +<img src="/_static/images/cloud-azure-sg-03.webp" /> +</figure> + +**Associate subnets**: + +- Navigate to the **Network Security Groups**, select **Subnets** click **+ Associate** button. Then select your virtual network and the subnet to which you want to associate the NSG. Select **OK**: + +<figure> +<img src="/_static/images/cloud-azure-sg-04.webp" /> +</figure> + +Step 4: Create Public IP Address +----------- + +- In the Azure Portal, search for and select **Public IP Addresses**. +- On the **Public IP Addresses** page, select **+ Create**. +- Provide the following details: +- **Subscription**: Select your Subscription +- **Resource Group**: Select `VyOSResourceGroup` +- **Region**: `West Europe` + +<figure> +<img src="/_static/images/cloud-azure-pub-ip-01.webp" /> +</figure> + +- **Name**: `VyOS-Pub-IP` +- **IP Version**: `IPv4` +- **SKU**: `Standard` +- **Availability zone**: Select Availability Zone + +<figure> +<img src="/_static/images/cloud-azure-pub-ip-02.webp" /> +</figure> + +- **IP address assignment**: `Static` +- **Idle timeout (minutes)** `30` (max) + +<figure> +<img src="/_static/images/cloud-azure-pub-ip-03.webp" /> +</figure> + +- Click **Review + Create**, then **Create**. + +Step 5: Deploy the VyOS Network Virtual Machine (NVA) +----------- + +- In the Azure Portal, search for and select **Virtual Machines**. +- On the **Virtual Machines** page, click **+ Create** and select **Azure virtual machine**. +- Provide the following details: +- **Subscription**: Select your Subscription +- **Resource Group**: Select `VyOSResourceGroup` +- **Virtual machine name**: e.g., `VyOS` +- **Region**: e.g., `West Europe` +- **Security type**: `Standard` +- **Image**: `VyOS` (On the marketplace search `VyOS` and choose the appropriate subscription). + +<figure> +<img src="/_static/images/cloud-azure-vm-01.webp" /> +</figure> + +- **Size**: Select a VM size to support the workload that you want to run. The size that you choose then determines factors such as processing power, memory, and storage capacity. + +<figure> +<img src="/_static/images/cloud-azure-vm-02.webp" /> +</figure> + +- **Password/SSH Key**: Choose whether the administrator account will use username/password or SSH keys for authentication. +- **Username**: The administrator username for the VM, e.g., `vyos`. +- **SSH Key**: You can use your existing SSH key pair or Azure automatically generates it for you and allows you to store it for future use. + +<figure> +<img src="/_static/images/cloud-azure-vm-03.webp" /> +</figure> + +- **Virtual network**: Select `VyOS-VirtualNetwork`. +- **Subnet**: Select `VyOS-Public-Subnet`. +- **Public IP**: Select public IP address which created before `VyOS-Pub-IP`. + +<figure> +<img src="/_static/images/cloud-azure-vm-04.webp" /> +</figure> + +- **Configure network security group**: Select existing Security Group `VyOS-SecurityGroup`. + +<figure> +<img src="/_static/images/cloud-azure-vm-05.webp" /> +</figure> + +- Click **Review + Create**, then **Create**. +- Click **Download the private key and create resource** this will download private key to your computer and start creating Virtual Machine. + +<figure> +<img src="/_static/images/cloud-azure-vm-06.webp" /> +</figure> + +- Wait until deployment is complete. After the deployment complete navigate to **Virtual Machines** click new created Virtual Machine. Check **Public IP address**. + +<figure> +<img src="/_static/images/cloud-azure-vm-07.webp" /> +</figure> + +Step 6: Access the VyOS instance +----------- + +- Access the VyOS instance using **SSH** protocol, **Public IP Address**, **Private Key**: + + ``` none + $ ssh vyos@51.124.120.235 -i vyos_key.pem + vyos@VyOS:~$ + ``` + +Step 7: Enable IP Forwarding in Network Interface +----------- + +This option allows the virtual machine on this network interface to act as a router and receive traffic addressed to other destinations. + +- On the **Virtual Machines** page, select `VyOS` VM, under **Networking** tab select **Network settings**, click network interface. + +<figure> +<img src="/_static/images/cloud-azure-vm-12.webp" /> +</figure> + +- Enable IP forwarding and click the **Apply** button. + +<figure> +<img src="/_static/images/cloud-azure-vm-13.webp" /> +</figure> + +Step 8: Create and attach the second network interface (optional) +------------- + +Now instance has been deployed with one **eth0** `WAN` interface and want to add +new one. To add new interface an example **eth1** `LAN` you need shutdown the +instance. Attach the interface in the Azure portal and then start the instance. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Azure does not allow you attach interface when the instance in the +**Running** state. + +</div> + +Create network interface: +^^^^^^^^^^^^^^ + +- In the Azure Portal, search for and select **Network Interfaces**. +- On the **Network Interfaces** page, select **+ Create**. + +<figure> +<img src="/_static/images/cloud-azure-nic-01.webp" /> +</figure> + +- **Subscription**: Select your Subscription +- **Resource Group**: Select `VyOSResourceGroup` +- **Name**: `VyOS-PRIV-NIC` +- **Subnet**: `VyOS-Private-Subnet` +- **Private IP**: `Dynamic` +- Click **Review + Create**, then **Create** + +<figure> +<img src="/_static/images/cloud-azure-nic-02.webp" /> +</figure> + +- Enable **IP Forwarding** +- Navigate to **Network Interfaces** select `VyOS-PRIV-NIC` + +<figure> +<img src="/_static/images/cloud-azure-nic-03.webp" /> +</figure> + +- Go to **Settings**, select **IP configurations**. Enable IP Forwarding and select **Apply**. + +<figure> +<img src="/_static/images/cloud-azure-nic-04.webp" /> +</figure> + +Attach reate network interface: +^^^^^^^^^^^^^^ + +- Navigate to **Virtual Machines**, click new created Virtual Machine and click the **Stop** button + +<figure> +<img src="/_static/images/cloud-azure-vm-08.webp" /> +</figure> + +- Go to **Networking** select **Network settings** and then select **Attach network interface** + +<figure> +<img src="/_static/images/cloud-azure-vm-09.webp" /> +</figure> + +- Select existing (before created) network interface `VyOS-PRIV-NIC` and click the **OK** button. + +<figure> +<img src="/_static/images/cloud-azure-vm-10.webp" /> +</figure> + +- Now you have attached second interface to your instance and you can start Virtual Machine. +- Go to **Overview** and click the **Start** button. + +<figure> +<img src="/_static/images/cloud-azure-vm-11.webp" /> +</figure> + +Setp 8: Absorbing Routes +---------------- + +To route traffic from your Virtual Network (VNET) through the LAN interface of your VyOS Network Virtual Appliance (NVA), you need to create and configure a custom route table in Azure. + +- Step-by-Step Instructions: +- Navigate to **Route Tables** and click **+ Create**. + +Provide the following details: + +> - **Subscription**: Select your Subscription +> - **Resource Group**: Select `VyOSResourceGroup` +> - **Name**: `Route-VyOS` +> - **Region**: e.g., `West Europe` + +<figure> +<img src="/_static/images/cloud-azure-route-01.webp" /> +</figure> + +- Click **Review + Create**, then **Create**. + +**Add a Route**: + +- Navigate to **Route Tables** and click the new created route (`Route-VyOS`). +- Go to **Routes** and click **+ Add** button. + +<figure> +<img src="/_static/images/cloud-azure-route-02.webp" /> +</figure> + +Add following parameters: + +- **Name**: `Default-Route` +- **Destination type**: `IP Addresses` +- **Destination IP addresses/CIDR ranges**: `0.0.0.0/0` +- **Next Hop Type**: `Virtual Appliance` +- **Next Hop IP Address**: `10.1.11.4` (The private Network Interface Card IP Address) + +<figure> +<img src="/_static/images/cloud-azure-route-03.webp" /> +</figure> + +- Click the **Add** button. + +**Associate the Route Table with subnet**: + +- Navigate to **Route Tables** and click the new created route (`VyOSResourceGroup`). +- Go to **Subnets** and click **+ Associate** button. + +<figure> +<img src="/_static/images/cloud-azure-route-04.webp" /> +</figure> + +- **Virtual network**: Select `VyOS-VirtualNetwork`. +- **Subnet**: Select `VyOS-Public-Subnet`. + +<figure> +<img src="/_static/images/cloud-azure-route-05.webp" /> +</figure> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you want to create a new default route for VMs on the subnet, use **Address Prefix** `0.0.0.0/0` Also note that if you want to use this as a typical edge device, you'll want masquerade NAT for the `WAN` interface. + +</div> + +Deploy VyOS Instance and Required Resources Automatically (via Terraform) +-------------- + +You can deploy a VyOS instance and its associated resources in **Azure** using Terraform modules available in the GitHub repository. +All necessary parameters will be configured automatically, and you will receive **management and access information** from the outputs. + +You can also edit/change these parameters based on your requirements. + +- Download/Clone the Repository following GitHub repository: + +<https://github.com/vyos/vyos-automation/tree/main/Terraform/Azure> diff --git a/docs/installation/cloud/md-gcp.md b/docs/installation/cloud/md-gcp.md new file mode 100644 index 00000000..b30d6494 --- /dev/null +++ b/docs/installation/cloud/md-gcp.md @@ -0,0 +1,298 @@ +\##################### +VyOS Deployment on Google Cloud Platform +\##################### + +This guide provides step-by-step instructions for deploying a VyOS instance with two NICs and the required resources on Google Cloud Platform (GCP). + +Prerequisites +======== + +Before proceeding, ensure the following: + +- A GCP account with billing enabled. +- Permissions to deploy Marketplace images. +- Access to enable APIs and create resources (e.g., Compute Engine Admin, Network Admin). +- An SSH key pair for VyOS instance access. +- GA Google Cloud Project. + +Deployment Steps +======== + +# Step 1: Add SSH Key + +1. If you don’t already have SSH keys, generate an SSH key pair of type `ssh-rsa` on your local machine: + +> Example: +> +> ``` none +> ssh-keygen -t rsa -f ~/.ssh/vyos_gcp -C "vyos@mypc" +> ``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +In the comment `vyos@mypc`, the username must start with vyos. +This is because the default user in the VyOS image is `vyos`, and the Google Cloud API uses this value for SSH access. + +</div> + +2. Open GCP console and navigate to the **Compute Engine** \> **Metadata** \> **SSH Keys**. Choose + **SSH Keys**. + +<figure> +<img src="/_static/images/cloud-gcp-01.webp" /> +</figure> + +3. Click **edit** and **Add item**. +4. Paste your public ssh key and **Save**. + +<figure> +<img src="/_static/images/cloud-gcp-02.webp" /> +</figure> + +For more information, please visit the official Google Cloud documentation: + +<https://cloud.google.com/compute/docs/connect/add-ssh-keys> + +<https://cloud.google.com/compute/docs/connect/create-ssh-keys> + +Step 2: Create a Service Account (If You Don't Have One) +------------------------------- + +1. In the Google Cloud console **IAM & Admin \> Service Accounts**. +2. Select select a project. + +<figure> +<img src="/_static/images/cloud-gcp-proj.webp" /> +</figure> + +3. Click **Create Service Account**: + - Name: e.g., `vyos-test` + - Service account ID: e.g., `vyos-test` + - Description: e.g., `VyOS Test Service Account` +4. Click **Done**. + +<figure> +<img src="/_static/images/cloud-gcp-svc.webp" /> +</figure> + +For more information, please visit the official Google Cloud documentation: + +<https://cloud.google.com/iam/docs/service-accounts-create> + +<https://cloud.google.com/iam/docs/service-account-overview> + +Step 3: Create VPC Networks and Subnets +------------------------------- + +1. In the Google Cloud console **VPC Network \> VPC Networks** <https://console.cloud.google.com/networking/networks/list> +2. Select select a project. + +<figure> +<img src="/_static/images/cloud-gcp-proj.webp" /> +</figure> + +3. Click **Create VPC Network**. + + **Public VPC**: + + - Name: e.g., `vyos-public-vpc` + - Subnet creation mode: `Custom` + - Subnet name: e.g., `vyos-public-subnet` + - Region: e.g., `europe-west1` + - IP range: e.g., `10.0.1.0/24` + - Leave all other settings at default, then click **Create**. + +<figure> +<img src="/_static/images/cloud-gcp-vpc-01.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-gcp-vpc-02.webp" alt="Private VPC:" /> +<figcaption><strong>Private VPC</strong>: +<ul> +<li>Name: <code>vyos-private-vpc</code></li> +<li>Subnet creation mode: <code>Custom</code></li> +<li>Subnet name: <code>vyos-private-subnet</code></li> +<li>Region: e.g., <code>europe-west1</code></li> +<li>IP range: <code>10.0.11.0/24</code></li> +<li>Leave all other settings at default, then click <strong>Create</strong>.</li> +</ul></figcaption> +</figure> + +<figure> +<img src="/_static/images/cloud-gcp-vpc-03.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-gcp-vpc-04.webp" /> +</figure> + +4. Add firewall rules to allow specific network traffic from the Internet if needed. By default, all incoming traffic from outside the network is blocked. Typically, a VyOS deployment from the GCP Marketplace configures this automatically, ensuring that SSH access is enabled after deployment. + +<figure> +<img src="/_static/images/cloud-gcp-vpc-05.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-gcp-vpc-06.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-gcp-vpc-07.webp" /> +</figure> + +For more information, please visit the official Google Cloud documentation: + +<https://cloud.google.com/vpc/docs/create-modify-vpc-networks> + +Step 4: Deploy VyOS instance from Marketplace +--------- + +1. Go to the Google Cloud Marketplace page in the Google Cloud console <https://console.cloud.google.com/marketplace> +2. Choose the project where you want to deploy the VyOS instance. + +<figure> +<img src="/_static/images/cloud-gcp-proj.webp" /> +</figure> + +3. In the search bar, type `vyos` to find the VyOS image in the Marketplace. + +<figure> +<img src="/_static/images/cloud-gcp-market-01.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-gcp-market-02.webp" /> +</figure> + +4. On the next page, review details such as support, pricing, and other details. + +<figure> +<img src="/_static/images/cloud-gcp-market-03.webp" /> +</figure> + +5. Click the `GET STARTED` button to start deployment process. + +<figure> +<img src="/_static/images/cloud-gcp-market-04.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-gcp-market-05.webp" /> +</figure> + +6. General settings. + - Deployment name: e.g., `vyos-test-vm` + - Select a Service Account: Select the service account created earlier. + - Image: Select VyOS image for deployment. + - Zone: e.g., `europe-west1-b` + - Machine type: Choose based on performance and resource needs. + +<figure> +<img src="/_static/images/cloud-gcp-vm-01.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-gcp-vm-02.webp" /> +</figure> + +7. Configure the network interfaces. + + **Public Network interface:** + + Edit the first (default) network interface and select following settings: + + > - Network: `vyos-public-vpc` + > - Subnetwork: `vyos-public-subnet` + > - External IP: `Ephemeral` + > - Private Network interface: + + **Private Network Interface:** + + Click **ADD A NETWORK INTERFACE** button to create a second (private) interface, and select following settings: + + > - Network: `vyos-private-vpc` + > - Subnetwork: `vyos-private-subnet` + > - External IP: `None` + +<figure> +<img src="/_static/images/cloud-gcp-vm-03.webp" /> +</figure> + +8. Deployment automation. + - You can use `cloud-init` `User Data` to automatically inject specific configuration commands into the VyOS instance during deployment. + - Example: + +> ``` none +> #cloud-config +> vyos_config_commands: +> - set system host-name 'VyOS-for-GCP' +> - set system login banner pre-login 'Welcome to the VyOS for on GCP' +> - set interfaces ethernet eth0 description 'WAN' +> - set interfaces ethernet eth1 description 'LAN' +> - set interfaces ethernet eth1 address 'dhcp' +> - set interfaces ethernet eth1 dhcp-options no-default-route +> ``` + +For more information, please visit the documentation: + +<https://docs.vyos.io/en/stable/automation/cloud-init.html#module-vyos-userdata> + +<figure> +<img src="/_static/images/cloud-gcp-vm-09.webp" /> +</figure> + +9. Click `Deploy` button. + +<figure> +<img src="/_static/images/cloud-gcp-vm-06.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-gcp-vm-07.webp" /> +</figure> + +Connect to the VyOS instance +----------- + +To connect to the VyOS instance, use the SSH key that was generated in the first step. + +To retrieve the public IP address, go to the **Google Cloud Console** and navigate to: **Compute Engine** \> **VM instances** <https://console.cloud.google.com/compute/instances?project=vyos-images> + +<figure> +<img src="/_static/images/cloud-gcp-vm-08.webp" /> +</figure> + +Example: + +> ``` none +> ssh vyos@35.233.97.132 -i .ssh/vyos_gcp +> +> The authenticity of host '35.233.97.132 (35.233.97.132)' can't be established. +> ED25519 key fingerprint is SHA256:KCsCnwCGhwX2ba5RcPUAO3ZUSNzS4sXIkujFoScCd0g. +> This key is not known by any other names +> Are you sure you want to continue connecting (yes/no/[fingerprint])? yes +> Warning: Permanently added '35.233.97.132' (ED25519) to the list of known hosts. +> Welcome to the VyOS for on GCP +> Welcome to VyOS! +> +> ┌── ┐ +> . VyOS 1.4.2 +> └ ──┘ sagitta +> +> * Documentation: https://docs.vyos.io/en/sagitta +> * Project news: https://blog.vyos.io +> * Bug reports: https://vyos.dev +> +> You can change this banner using "set system login banner post-login" command. +> +> VyOS is a free software distribution that includes multiple components, +> you can check individual component licenses under /usr/share/doc/*/copyright +> vyos@VyOS-for-GCP:~$ +> ``` diff --git a/docs/installation/cloud/md-index.md b/docs/installation/cloud/md-index.md new file mode 100644 index 00000000..1c1e1ed6 --- /dev/null +++ b/docs/installation/cloud/md-index.md @@ -0,0 +1,13 @@ +# Running VyOS in Cloud Environments + +<div class="toctree" caption="Content"> + +aws +aws-ha +azure +azure-ha +aws-to-azure +gcp +oracle + +</div> diff --git a/docs/installation/cloud/md-oracel.md b/docs/installation/cloud/md-oracel.md new file mode 100644 index 00000000..9ed07ff9 --- /dev/null +++ b/docs/installation/cloud/md-oracel.md @@ -0,0 +1,5 @@ +# Oracle + +## References + +<https://www.oracle.com/cloud/> diff --git a/docs/installation/md-image.md b/docs/installation/md-image.md new file mode 100644 index 00000000..fb57d73f --- /dev/null +++ b/docs/installation/md-image.md @@ -0,0 +1,131 @@ +# Image Management + +The VyOS image-based installation is implemented by creating a directory for +each image on the storage device selected during the install process. + +The directory structure of the boot device: + +``` none +/ +/boot +/boot/grub +/boot/1.2.0-rolling+201810021347 +``` + +The image directory contains the system kernel, a compressed image of the root +filesystem for the OS, and a directory for persistent storage, such as +configuration. On boot, the system will extract the OS image into memory and +mount the appropriate live-rw sub-directories to provide persistent storage +system configuration. + +This process allows for a system to always boot to a known working state, as +the OS image is fixed and non-persistent. It also allows for multiple releases +of VyOS to be installed on the same storage device. The image can be selected +manually at boot if needed, but the system will otherwise boot the image +configured to be the default. + +<div class="opcmd"> + +show system image + +List all available system images which can be booted on the current system. + +``` none +vyos@vyos:~$ show system image +The system currently has the following image(s) installed: + + 1: 1.2.0-rolling+201810021347 (default boot) + 2: 1.2.0-rolling+201810021217 + 3: 1.2.0-rolling+201809252218 +``` + +</div> + +<div class="opcmd"> + +delete system image \[image-name\] + +Delete no longer needed images from the system. You can specify an optional +image name to delete, the image name can be retrieved via a list of available +images can be shown using the `show system image`. + +``` none +vyos@vyos:~$ delete system image +The following image(s) can be deleted: + + 1: 1.3-rolling-201912181733 (default boot) (running image) + 2: 1.3-rolling-201912180242 + 3: 1.2.2 + 4: 1.2.1 + +Select the image to delete: 2 + +Are you sure you want to delete the +"1.3-rolling-201912180242" image? (Yes/No) [No]: y +Deleting the "1.3-rolling-201912180242" image... +Done +``` + +</div> + +<div class="opcmd"> + +show version + +Show current system image version. + +``` none +vyos@vyos:~$ show version +Version: VyOS 1.3-rolling-201912181733 +Built by: autobuild@vyos.net +Built on: Wed 18 Dec 2019 17:33 UTC +Build UUID: bccde2c3-261c-49cc-b421-9b257204e06c +Build Commit ID: f7ce0d8a692f2d + +Architecture: x86_64 +Boot via: installed image +System type: bare metal + +Hardware vendor: VMware, Inc. +Hardware model: VMware Virtual Platform +Hardware S/N: VMware-42 1d 83 b9 fe c1 bd b2-7d 3d 49 db 94 18 f5 c9 +Hardware UUID: b9831d42-c1fe-b2bd-7d3d-49db9418f5c9 + +Copyright: VyOS maintainers and contributors +``` + +</div> + +## System rollback + +If you need to rollback to a previous image, you can easily do so. First +check the available images through the `show system image` +command and then select your image with the following command: + +<div class="opcmd"> + +set system image default-boot \[image-name\] + +Select the default boot image which will be started on the next boot +of the system. + +</div> + +Then reboot the system. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +VyOS automatically associates the configuration to the image, +so you don't need to worry about that. Each image has a unique copy +of its configuration. + +</div> + +If you have access to the console, there is a another way to select +your booting image: reboot and use the GRUB menu at startup. diff --git a/docs/installation/md-index.md b/docs/installation/md-index.md new file mode 100644 index 00000000..2e8e93c9 --- /dev/null +++ b/docs/installation/md-index.md @@ -0,0 +1,34 @@ +# Installation and Image Management + +<div class="note"> + +<div class="title"> + +Note + +</div> + +This is most likely only relevant for virtual installations: + +When installing VyOS ensure that the MAC address selected for your NICs is +not a locally administered MAC address. Locally administered addresses are +distinguished from universally administered addresses by setting (assigning +the value of 1 to) the second-least-significant bit of the first octet of +the address: + +Example: `02:00:00:00:00:01`, where the second-least-significant bit +(`02` in hex) is set to `1`. + +</div> + +<div class="toctree" maxdepth="2" caption="Content"> + +install +virtual/index +cloud/index +vyos-on-baremetal +update +image +migrate-from-vyatta + +</div> diff --git a/docs/installation/md-install.md b/docs/installation/md-install.md new file mode 100644 index 00000000..947d71d7 --- /dev/null +++ b/docs/installation/md-install.md @@ -0,0 +1,504 @@ +# Installation + +VyOS installation requires a downloaded VyOS .iso file. That file is +a live install image that lets you boot a live VyOS. From the live +system, you can proceed to a permanent installation on a hard drive or +any other type of storage. + +<table style="width:98%;"> +<caption>Comparison of VyOS image releases</caption> +<colgroup> +<col style="width: 8%" /> +<col style="width: 29%" /> +<col style="width: 11%" /> +<col style="width: 22%" /> +<col style="width: 13%" /> +<col style="width: 10%" /> +</colgroup> +<thead> +<tr> +<th>Release Type</th> +<th>Description</th> +<th>Release Cycle</th> +<th>Intended Use</th> +<th>Access to Images</th> +<th>Access to Source</th> +</tr> +</thead> +<tbody> +<tr> +<td><strong>Nightly +(Current)</strong></td> +<td>Automatically built from the current branch. +Always up to date with cutting edge development +but guaranteed to contain bugs.</td> +<td>Every night</td> +<td>Developing VyOS, testing new +features, experimenting.</td> +<td>Everyone</td> +<td>Everyone</td> +</tr> +<tr> +<td><strong>Stream</strong></td> +<td>VyOS Stream serves as a technology preview and +a quality gate for the upcoming LTS release. +Allows everyone to try new features and check +if they work well or need improvements</td> +<td>Every quarter</td> +<td>Non-critical production environments, +preparing for the LTS release.</td> +<td>Everyone</td> +<td>Everyone</td> +</tr> +<tr> +<td><strong>Release +Candidate</strong></td> +<td>Rather stable. All development focuses on testing +and hunting down remaining bugs following the +feature freeze.</td> +<td>Irregularly until +EPA comes out</td> +<td>Labs, small offices and non-critical +production systems backed by a +high-availability setup.</td> +<td>Everyone</td> +<td>Everyone</td> +</tr> +<tr> +<td><strong>Early +Production +Access</strong></td> +<td>Highly stable with no known bugs. Needs to be +tested repeatedly under different conditions +before it can become the final release.</td> +<td>Irregularly until +LTS comes out</td> +<td>Non-critical production environments, +preparing for the LTS release.</td> +<td>Everyone</td> +<td>Everyone</td> +</tr> +<tr> +<td><strong>Long-Term +Support</strong></td> +<td>Guaranteed to be stable and carefully maintained +for several years after the release. No features +are introduced but security updates are released +in a timely manner.</td> +<td>Every major +version</td> +<td>Large-scale enterprise networks, +internet service providers, +critical production environments +that call for minimum downtime.</td> +<td>Subscribers, +contributors, +non-profits, +emergency services, +academic institutions</td> +<td>Everyone</td> +</tr> +</tbody> +</table> + +## Hardware requirements + +The minimum system requirements are 4 GB RAM and 10 GB storage. +Depending on your use, you might need additional RAM and CPU resources e.g. +when having multiple BGP full tables in your system. + +## Download + +### Registered Subscribers + +Registered subscribers can log into <https://support.vyos.io/> to access a +variety of different downloads via the "Downloads" link. These downloads +include LTS (Long-Term Support), the associated hot-fix releases, early public +access releases, pre-built VM images, as well as device specific installation +ISOs. See this [article](https://customers.support.vyos.com/servicedesk/customer/portal/1/article/159055913) for more information on downloads. + +<figure> +<img src="/_static/images/vyosnew-downloads.webp" /> +</figure> + +### Rolling Release + +Everyone can download bleeding-edge VyOS rolling images from: +<https://downloads.vyos.io/> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Rolling releases contain all the latest enhancements and fixes. This +means that there will be new bugs of course. If you think you hit a bug +please follow the guide at `bug_report`. We depend on your feedback +to improve VyOS! + +</div> + +The following link contains the list of the most recent VyOS builds for AMD64 +systems from the current branch: +<https://vyos.net/get/nightly-builds/> + +### Download Verification + +LTS images are signed by the VyOS lead package-maintainer private key. With the +official public key, the authenticity of the package can be verified. +Minisign is used for verification. + +#### Minisign verification + +Currently we are using Minisign for release signing which is a simple tool to +sign files and verify signatures. + +In 2015, OpenBSD introduced signify. An alternative implementation of the same +protocol is minisign, which is also available for Windows and macOS, and in most +GNU/Linux distros it's in the repositories now. It is portable, lightweight, and +uses the highly secure Ed25519 public-key signature system. + +`T2108` switched the validation system to prefer minisign over GPG keys. + +To verify a VyOS image starting off with VyOS 1.3.0-rc6 you can run: + +``` none +$ minisign -V -P RWTR1ty93Oyontk6caB9WqmiQC4fgeyd/ejgRxCRGd2MQej7nqebHneP -m vyos-1.3.0-rc6-amd64.iso vyos-1.3.0-rc6-amd64.iso.minisig +Signature and comment signature verified +Trusted comment: timestamp:1629997936 file:vyos-1.3.0-rc6-amd64.iso +``` + +During an image upgrade VyOS performs the following command: + +``` none +$ minisign -V -p /usr/share/vyos/keys/vyos-release.minisign.pub -m vyos-1.3.0-rc6-amd64.iso vyos-1.3.0-rc6-amd64.iso.minisig +Signature and comment signature verified +Trusted comment: timestamp:1629997936 file:vyos-1.3.0-rc6-amd64.iso +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Starting with 1.4.3, VyOS uses Minisign exclusively. This should not +be a problem for anyone because Minisign signature verification has already +been present in all releases for years. But if you see an unexpected verification +error, you can solve that by updating your system to 1.4.2 first. +Removed support for GnuPG signatures(`T7301`). + +</div> + +## Live installation + +<div class="note"> + +<div class="title"> + +Note + +</div> + +A permanent VyOS installation always requires to go first +through a live installation. + +</div> + +VyOS, as other GNU+Linux distributions, can be tested without installing +it in your hard drive. **With your downloaded VyOS .iso file you can +create a bootable USB drive that will let you boot into a fully +functional VyOS system**. Once you have tested it, you can either decide +to begin a `permanent_installation` in your hard drive or power +your system off, remove the USB drive, and leave everything as it was. + +If you have a GNU+Linux system, you can create your VyOS bootable USB +stick with with the `dd` command: + +> 1. Open your terminal emulator. +> 2. Find out the device name of your USB drive (you can use the `lsblk` +> command) +> 3. Unmount the USB drive. Replace X in the example below with the +> letter of your device and keep the asterisk (wildcard) to unmount +> all partitions. +> +> ``` none +> $ umount /dev/sdX* +> ``` +> +> 4. Write the image (your VyOS .iso file) to the USB drive. +> Note that here you want to use the device name (e.g. /dev/sdb), not +> the partition name (e.g. /dev/sdb1). +> +> > **Warning**: This will destroy all data on the USB drive! +> +> ``` none +> # dd if=/path/to/vyos.iso of=/dev/sdX bs=8M; sync +> ``` +> +> 5. Wait until you get the outcome (bytes copied). Be patient, in some +> computers it might take more than one minute. +> 6. Once `dd` has finished, pull the USB drive out and plug it into +> the powered-off computer where you want to install (or test) VyOS. +> 7. Power the computer on, making sure it boots from the USB drive (you +> might need to select booting device or change booting settings). +> 8. Once VyOS is completely loaded, enter the default credentials +> (login: vyos, password: vyos). + +If you find difficulties with this method, prefer to use a GUI program, +or have a different operating system, there are other programs you can +use to create a bootable USB drive, like [balenaEtcher](https://www.balena.io/etcher/) (for GNU/Linux, +macOS and Windows), [Rufus](https://rufus.ie/) (for Windows) and [many others](https://en.wikipedia.org/wiki/List_of_tools_to_create_Live_USB_systems). You can +follow their instructions to create a bootable USB drive from an .iso +file. + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +The default username and password for the live system is *vyos*. + +</div> + +## Permanent installation + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Before a permanent installation, VyOS requires a +`live_installation`. + +</div> + +Unlike general purpose Linux distributions, VyOS uses "image installation" that +mimics the user experience of traditional hardware routers and allows keeping +multiple VyOS versions installed simultaneously. This makes it possible to +switch to a previous version if something breaks or miss-behaves after an image +upgrade. + +Every version is contained in its own squashfs image that is mounted in a union +filesystem together with a directory for mutable data such as configurations, +keys, or custom scripts. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Older versions (prior to VyOS 1.1) used to support non-image +installation (`install system` command). Support for this has been removed +from VyOS 1.2 and newer releases. Older releases can still be upgraded via +the general `add system image <image_path>` upgrade command (consult +`image-mgmt` for further information). + +</div> + +In order to proceed with a permanent installation: + +> 1. Log into the VyOS live system (use the default credentials: vyos, +> vyos) +> 2. Run the `install image` command and follow the wizard: + +<figure> +<img src="/_static/images/permanent_install.webp" alt="3. After the installation is completed, remove the live USB stick or CD." /> +<figcaption>3. After the installation is completed, remove the live USB stick or +CD. +<ol start="4" type="1"> +<li>Reboot the system.</li> +</ol> +<pre class="none"><code>vyos@vyos:~$ reboot +Proceed with reboot? (Yes/No) [No] Yes</code></pre> +<p>You will boot now into a permanent VyOS system.</p></figcaption> +</figure> + +## PXE Boot + +VyOS can also be installed through PXE. This is a more complex +installation method that allows deploying VyOS through the network. + +**Requirements** + +- Clients (where VyOS is to be installed) with a PXE-enabled NIC +- `dhcp-server` +- `tftp-server` +- Webserver (HTTP) - optional, but we will use it to speed up installation +- VyOS ISO image to be installed (do not use images prior to VyOS 1.2.3) +- Files *pxelinux.0* and *ldlinux.c32* [from the Syslinux distribution](https://kernel.org/pub/linux/utils/boot/syslinux/) + +### Configuration + +#### Step 1: DHCP + +Configure a DHCP server to provide the client with: + +- An IP address +- The TFTP server address (DHCP option 66). Sometimes referred as *boot server* +- The *bootfile name* (DHCP option 67), which is *pxelinux.0* + +In this example we configured an existent VyOS as the DHCP server: + +``` none +vyos@vyos# show service dhcp-server + shared-network-name mydhcp { + subnet 192.168.1.0/24 { + bootfile-name pxelinux.0 + bootfile-server 192.168.1.50 + default-router 192.168.1.50 + range 0 { + start 192.168.1.70 + stop 192.168.1.100 + } + } + } +``` + +#### Step 2: TFTP + +Configure a TFTP server so that it serves the following: + +- The *pxelinux.0* file from the Syslinux distribution +- The *ldlinux.c32* file from the Syslinux distribution +- The kernel of the VyOS software you want to deploy. That is the + *vmlinuz* file inside the */live* directory of the extracted + contents from the ISO file. +- The initial ramdisk of the VyOS ISO you want to deploy. That is the + *initrd.img* file inside the */live* directory of the extracted + contents from the ISO file. Do not use an empty (0 bytes) initrd.img + file you might find, the correct file may have a longer name. +- A directory named pxelinux.cfg which must contain the configuration + file. We will use the [configuration](https://wiki.syslinux.org/wiki/index.php?title=Config) file shown below, which we named + [default](https://wiki.syslinux.org/wiki/index.php?title=PXELINUX#Configuration). + +In the example we configured our existent VyOS as the TFTP server too: + +``` none +vyos@vyos# show service tftp-server + directory /config/tftpboot + listen-address 192.168.1.50 +``` + +Example of the contents of the TFTP server: + +``` none +vyos@vyos# ls -hal /config/tftpboot/ +total 29M +drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 . +drwxrwsr-x 9 root vyattacfg 4.0K Oct 18 00:05 .. +-r--r--r-- 1 root vyattacfg 25M Oct 13 23:24 initrd.img-4.19.54-amd64-vyos +-rwxr-xr-x 1 root vyattacfg 120K Oct 13 23:44 ldlinux.c32 +-rw-r--r-- 1 root vyattacfg 46K Oct 13 23:24 pxelinux.0 +drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 pxelinux.cfg +-r--r--r-- 1 root vyattacfg 3.7M Oct 13 23:24 vmlinuz + +vyos@vyos# ls -hal /config/tftpboot/pxelinux.cfg +total 12K +drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 . +drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 .. +-rw-r--r-- 1 root root 191 Oct 14 01:10 default +``` + +Example of simple (no menu) configuration file: + +``` none +vyos@vyos# cat /config/tftpboot/pxelinux.cfg/default +DEFAULT VyOS123 + +LABEL VyOS123 + KERNEL vmlinuz + APPEND initrd=initrd.img-4.19.54-amd64-vyos boot=live nopersistence noautologin nonetworking fetch=http://address:8000/filesystem.squashfs +``` + +#### Step 3: HTTP + +We also need to provide the *filesystem.squashfs* file. That is a heavy +file and TFTP is slow, so you could send it through HTTP to speed up the +transfer. That is how it is done in our example, you can find that in +the configuration file above. + +**First** run a web server - you can use a simple one like +[Python's SimpleHTTPServer](https://docs.python.org/2/library/simplehttpserver.html) and start serving the <span class="title-ref">filesystem.squashfs</span> +file. The file can be found inside the <span class="title-ref">/live</span> directory of the +extracted contents of the ISO file. + +**Second**, edit the configuration file of the `install_from_tftp` +so that it shows the correct URL at +`fetch=http://<address_of_your_HTTP_server>/filesystem.squashfs`. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Do not change the name of the *filesystem.squashfs* file. If +you are working with different versions, you can create different +directories instead. + +</div> + +And **third**, restart the TFTP service. If you are using VyOS as your +TFTP Server, you can restart the service with +`sudo service tftpd-hpa restart`. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Make sure the available directories and files in both TFTP +and HTTP server have the right permissions to be accessed from the +booting clients. + +</div> + +### Client Boot + +Finally, turn on your PXE-enabled client or clients. They will +automatically get an IP address from the DHCP server and start booting +into VyOS live from the files automatically taken from the TFTP and HTTP +servers. + +Once finished you will be able to proceed with the `install image` +command as in a regular VyOS installation. + +## Known Issues + +This is a list of known issues that can arise during installation. + +### Black screen on install + +GRUB attempts to redirect all output to a serial port for ease of installation +on headless hosts. This appears to cause an hard lockup on some hardware that +lacks a serial port, with the result being a black screen after selecting the +<span class="title-ref">Live system</span> option from the installation image. + +The workaround is to type <span class="title-ref">e</span> when the boot menu appears and edit the GRUB boot +options. Specifically, remove the: + +<span class="title-ref">console=ttyS0,115200</span> + +option, and type CTRL-X to boot. + +Installation can then continue as outlined above. diff --git a/docs/installation/md-update.md b/docs/installation/md-update.md new file mode 100644 index 00000000..cff79228 --- /dev/null +++ b/docs/installation/md-update.md @@ -0,0 +1,110 @@ +# Update VyOS + +New system images can be added using the `add system image` +command. The command will extract the chosen image and will prompt you +to use the current system configuration and SSH security keys, allowing +for the new image to boot using the current configuration. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Only LTS releases are PGP-signed. + +</div> + +<div class="opcmd"> + +add system image \<url | path\> \[vrf name\] +\[username user \[password pass\]\] + +Use this command to install a new system image. You can reach the +image from the web (`http://`, `https://`) or from your local system, +e.g. /tmp/vyos-1.2.3-amd64.iso. + +The <span class="title-ref">add system image</span> command also supports installing new versions +of VyOS through an optional given VRF. Also if URL in question requires +authentication, you can specify an optional username and password via +the commandline which will be passed as "Basic-Auth" to the server. + +</div> + +If there is not enough **free disk space available**, the installation +will be canceled. To delete images use the `delete system image` +command. + +VyOS configuration is associated to each image, and **each image has a +unique copy of its configuration**. This is different than a traditional +network router where the configuration is shared across all images. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you have any personal files, like some scripts you created, +and you don't want them to be lost during the upgrade, make sure +those files are stored in `/config` as this directory is always copied +to newer installed images. + +</div> + +You can access files from a previous installation and copy them to your +current image if they were located in the `/config` directory. This +can be done using the `copy` command. So, for instance, in order +to copy `/config/config.boot` from VyOS 1.2.1 image, you would use the +following command: + +``` +copy file 1.2.1://config/config.boot to /tmp/config.boot.1.2.1 +``` + +## Example + +``` none +vyos@vyos:~$ add system image https://s3.amazonaws.com/s3-us.vyos.io/rolling/current/vyos-1.4-rolling-202201120317-amd64.iso +Trying to fetch ISO file from https://s3.amazonaws.com/s3-us.vyos.io/rolling/current/vyos-1.4-rolling-202201120317-amd64.iso + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed +100 338M 100 338M 0 0 3837k 0 0:01:30 0:01:30 --:--:-- 3929k +ISO download succeeded. +Checking for digital signature file... + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0 +curl: (22) The requested URL returned error: 404 Not Found + +Unable to fetch digital signature file. +Do you want to continue without signature check? (yes/no) [yes] +Checking MD5 checksums of files on the ISO image...OK. +Done! + +What would you like to name this image? [vyos-1.3-rolling-201912201452]: + +OK. This image will be named: vyos-1.3-rolling-201912201452 +``` + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +The most up-do-date Rolling Release for AMD64 can be accessed using +the following URL: + +<https://vyos.net/get/nightly-builds/> + +</div> + +After reboot you might want to verify the version you are running with +the `show version` command. diff --git a/docs/installation/md-vyos-on-baremetal.md b/docs/installation/md-vyos-on-baremetal.md new file mode 100644 index 00000000..aaf2c78d --- /dev/null +++ b/docs/installation/md-vyos-on-baremetal.md @@ -0,0 +1,609 @@ +# Running on Bare Metal + +## Supermicro A2SDi (Atom C3000) + +I opted to get one of the new Intel Atom C3000 CPUs to spawn VyOS on it. +Running VyOS on an UEFI only device is supported as of VyOS release 1.2. + +### Supermicro Shopping Cart + +- 1x Supermicro CSE-505-203B (19" 1U chassis, inkl. 200W PSU) +- 1x Supermicro MCP-260-00085-0B (I/O Shield for A2SDi-2C-HLN4F) +- 1x Supermicro A2SDi-2C-HLN4F (Intel Atom C3338, 2C/2T, 4MB cache, Quad LAN + with Intel C3000 SoC 1GbE) +- 1x Crucial CT4G4DFS824A (4GB DDR4 RAM 2400 MT/s, PC4-19200) +- 1x SanDisk Ultra Fit 32GB (USB-A 3.0 SDCZ43-032G-G46 mass storage for OS) +- 1x Supermicro MCP-320-81302-0B (optional FAN tray) + +### Optional (10GE) + +If you want to get additional ethernet ports or even 10GE connectivity +the following optional parts will be required: + +- 1x Supermicro RSC-RR1U-E8 (Riser Card) +- 1x Supermicro MCP-120-00063-0N (Riser Card Bracket) + +Latest VyOS rolling releases boot without any problem on this board. You also +receive a nice IPMI interface realized with an ASPEED AST2400 BMC (no +information about [OpenBMC](https://www.openbmc.org/) so far on this +motherboard). + +### Pictures + +<figure> +<img src="/_static/images/1u_vyos_back.webp" alt="CSE-505-203B Back" /> +</figure> + +<figure> +<img src="/_static/images/1u_vyos_front.webp" alt="CSE-505-203B Front" /> +</figure> + +<figure> +<img src="/_static/images/1u_vyos_front_open_1.webp" alt="CSE-505-203B Open 1" /> +</figure> + +<figure> +<img src="/_static/images/1u_vyos_front_open_2.webp" alt="CSE-505-203B Open 2" /> +</figure> + +<figure> +<img src="/_static/images/1u_vyos_front_open_3.webp" alt="CSE-505-203B Open 3" /> +</figure> + +<figure> +<img src="/_static/images/1u_vyos_front_10ge_open_1.webp" alt="CSE-505-203B w/ 10GE Open 1" /> +</figure> + +<figure> +<img src="/_static/images/1u_vyos_front_10ge_open_2.webp" alt="CSE-505-203B w/ 10GE Open 2" /> +</figure> + +<figure> +<img src="/_static/images/1u_vyos_front_10ge_open_3.webp" alt="CSE-505-203B w/ 10GE Open 3" /> +</figure> + +<figure> +<img src="/_static/images/1u_vyos_front_10ge_open_4.webp" alt="CSE-505-203B w/ 10GE Open" /> +</figure> + +## PC Engines APU4 + +As this platform seems to be quite common in terms of noise, cost, power and +performance it makes sense to write a small installation manual. + +This guide was developed using an APU4C4 board with the following specs: + +- AMD Embedded G series GX-412TC, 1 GHz quad Jaguar core with 64 bit and AES-NI + support, 32K data + 32K instruction cache per core, shared 2MB L2 cache. +- 4 GB DDR3-1333 DRAM, with optional ECC support +- About 6 to 10W of 12V DC power depending on CPU load +- 2 miniPCI express (one with SIM socket for 3G modem). +- 4 Gigabit Ethernet channels using Intel i211AT NICs + +The board can be powered via 12V from the front or via a 5V onboard connector. + +### APU4 Shopping Cart + +- 1x apu4c4 = 4 i211AT LAN / AMD GX-412TC CPU / 4 GB DRAM / dual SIM +- 1x Kingston SUV500MS/120G +- 1x VARIA Group Item 326745 19" dual rack for APU4 + +The 19" enclosure can accommodate up to two APU4 boards - there is a single and +dual front cover. + +#### Extension Modules + +##### WiFi + +Refer to `wireless-interface` for additional information, below listed +modules have been tested successfully on this Hardware platform: + +- Compex WLE900VX mini-PCIe WiFi module, only supported in mPCIe slot 1. +- Intel Corporation AX200 mini-PCIe WiFi module, only supported in mPCIe slot 1. + (see `wireless-interface-intel-ax200`) + +##### WWAN + +Refer to `wwan-interface` for additional information, below listed modules +have been tested successfully on this Hardware platform using VyOS 1.3 +(equuleus): + +- Sierra Wireless AirPrime MC7304 miniPCIe card (LTE) +- Sierra Wireless AirPrime MC7430 miniPCIe card (LTE) +- Sierra Wireless AirPrime MC7455 miniPCIe card (LTE) +- Sierra Wireless AirPrime MC7710 miniPCIe card (LTE) +- Huawei ME909u-521 miniPCIe card (LTE) + +VyOS 1.4 (sagitta) +--------------- + +Depending on the VyOS versions you intend to install there is a difference in +the serial port settings (`T1327`). + +Create a bootable USB pendrive using e.g. [Rufus](https://rufus.ie/) on a Windows machine. + +Connect serial port to a PC through null modem cable (RXD / TXD crossed over). +Set terminal emulator to 115200 8N1. + +``` none +PC Engines apu4 +coreboot build 20171130 +BIOS version v4.6.4 +4080 MB ECC DRAM +SeaBIOS (version rel-1.11.0.1-0-g90da88d) + +Press F10 key now for boot menu: + +Select boot device: + +1. ata0-0: KINGSTON SUV500MS120G ATA-11 Hard-Disk (111 GiBytes) +2. USB MSC Drive Generic Flash Disk 8.07 +3. Payload [memtest] +4. Payload [setup] +``` + +Now boot from the `USB MSC Drive Generic Flash Disk 8.07` media by pressing +`2`, the VyOS boot menu will appear, just wait 10 seconds or press `Enter` +to continue. + +``` none +lqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqk +x VyOS - Boot Menu x +tqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqu +x Live system (amd64-vyos) x +x Live system (amd64-vyos fail-safe mode) x +x Live system (amd64-vyos) - Serial console x +x x +mqqqqqqPress ENAutomatic boot in 10 seconds...nu entryqqqqqqqj +``` + +The image will be loaded and the last lines you will get will be: + +``` none +Loading /live/vmlinuz... ok +Loading /live/initrd.img... +... +Welcome to VyOS - vyos ttyS0 + +vyos login: +``` + +You can now proceed with a regular image installation as described in +`installation`. + +### Pictures + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Both device types operate without any moving parts and emit zero +noise. + +</div> + +#### Rack Mount + +<figure> +<img src="/_static/images/apu4_rack_1.webp" alt="APU4 rack closed" /> +</figure> + +<figure> +<img src="/_static/images/apu4_rack_2.webp" alt="APU4 rack front" /> +</figure> + +<figure> +<img src="/_static/images/apu4_rack_3.webp" alt="APU4 rack module #1" /> +</figure> + +<figure> +<img src="/_static/images/apu4_rack_4.webp" alt="APU4 rack module #2" /> +</figure> + +<figure> +<img src="/_static/images/apu4_rack_5.webp" alt="APU4 rack module #3 with PSU" /> +</figure> + +##### VyOS custom print + +<figure> +<img src="/_static/images/apu4_rack_vyos_print.webp" alt="APU4 custom VyOS powder coat" /> +</figure> + +#### Desktop / Bench Top + +<figure> +<img src="/_static/images/apu4_desk_1.webp" alt="APU4 desktop closed" /> +</figure> + +<figure> +<img src="/_static/images/apu4_desk_2.webp" alt="APU4 desktop closed" /> +</figure> + +<figure> +<img src="/_static/images/apu4_desk_3.webp" alt="APU4 desktop back" /> +</figure> + +<figure> +<img src="/_static/images/apu4_desk_4.webp" alt="APU4 desktop back" /> +</figure> + +## Qotom Q355G4 + +The install on this Q355G4 box is pretty much plug and play. The port numbering +the OS does might differ from the labels on the outside, but the UEFI firmware +has a port blink test built in with MAC addresses so you can very quickly +identify which is which. MAC labels are on the inside as well, and this test +can be done from VyOS or plain Linux too. Default settings in the UEFI will +make it boot, but depending on your installation wishes (i.e. storage type, +boot type, console type) you might want to adjust them. This Qotom company +seems to be the real OEM/ODM for many other relabelling companies like +Protectli. + +### Hardware + +There are a number of other options, but they all seem to be close to Intel +reference designs, with added features like more serial ports, more network +interfaces and the likes. Because they don't deviate too much from standard +designs all the hardware is well-supported by mainline. It accepts one LPDDR3 +SO-DIMM, but chances are that if you need more than that, you'll also want +something even beefier than an i5. There are options for antenna holes, and SIM +slots, so you could in theory add an LTE/Cell modem (not tested so far). + +The chassis is a U-shaped alu extrusion with removable I/O plates and removable +bottom plate. Cooling is completely passive with a heatsink on the SoC with +internal and external fins, a flat interface surface, thermal pad on top of +that, which then directly attaches to the chassis, which has fins as well. It +comes with mounting hardware and rubber feet, so you could place it like a +desktop model or mount it on a VESA mount, or even wall mount it with the +provided mounting plate. The closing plate doubles as internal 2.5" mounting +place for an HDD or SSD, and comes supplied with a small SATA cable and SATA +power cable. + +Power supply is a 12VDC barrel jack, and included switching power supply, which +is why SATA power regulation is on-board. Internally it has a NUC-board-style +on-board 12V input header as well, the molex locking style. + +There are WDT options and auto-boot on power enable, which is great for remote +setups. Firmware is reasonably secure (no backdoors found, BootGuard is enabled +in enforcement mode, which is good but also means no coreboot option), yet has +most options available to configure (so it's not locked out like most firmwares +are). + +An external RS232 serial port is available, internally a GPIO header as well. +It does have Realtek based audio on board for some reason, but you can disable +that. Booting works on both USB2 and USB3 ports. Switching between serial BIOS +mode and HDMI BIOS mode depends on what is connected at startup; it goes into +serial mode if you disconnect HDMI and plug in serial, in all other cases it's +HDMI mode. + +## Partaker i5 + +<figure> +<img src="../_static/images/600px-Partaker-i5.webp" /> +</figure> + +I believe this is actually the same hardware as the Protectli. I purchased it +in June 2018. It came pre-loaded with pfSense. + +[Manufacturer product page](http://www.inctel.com.cn/product/detail/338.html). + +### Installation + +- Write VyOS ISO to USB drive of some sort +- Plug in VGA, power, USB keyboard, and USB drive +- Press "SW" button on the front (this is the power button; I don't know what + "SW" is supposed to mean). +- Begin rapidly pressing delete on the keyboard. The boot prompt is very quick, + but with a few tries you should be able to get into the BIOS. +- Chipset \> South Bridge \> USB Configuration: set XHCI to Disabled and USB 2.0 + (EHCI) to Enabled. Without doing this, the USB drive won't boot. +- Boot to the VyOS installer and install as usual. + +Warning the interface labels on my device are backwards; the left-most "LAN4" +port is eth0 and the right-most "LAN1" port is eth3. + +## Acrosser AND-J190N1 + +<figure> +<img src="../_static/images/480px-Acrosser_ANDJ190N1_Front.webp" /> +</figure> + +<figure> +<img src="../_static/images/480px-Acrosser_ANDJ190N1_Back.webp" /> +</figure> + +This microbox network appliance was build to create OpenVPN bridges. It can +saturate a 100Mbps link. It is a small (serial console only) PC with 6 Gb LAN + +You may have to add your own RAM and HDD/SSD. There is no VGA connector. But +Acrosser provides a DB25 adapter for the VGA header on the motherboard (not +used). + +### BIOS Settings: + +First thing you want to do is getting a more user friendly console to configure +BIOS. Default VT100 brings a lot of issues. Configure VT100+ instead. + +For practical issues change speed from 115200 to 9600. 9600 is the default +speed at which both linux kernel and VyOS will reconfigure the serial port +when loading. + +Connect to serial (115200bps). Power on the appliance and press Del in the +console when requested to enter BIOS settings. + +Advanced \> Serial Port Console Redirection \> Console Redirection Settings: + +- Terminal Type : VT100+ +- Bits per second : 9600 + +Save, reboot and change serial speed to 9600 on your client. + +Some options have to be changed for VyOS to boot correctly. With XHCI enabled +the installer can’t access the USB key. Enable EHCI instead. + +Reboot into BIOS, Chipset \> South Bridge \> USB Configuration: + +- Disable XHCI +- Enable USB 2.0 (EHCI) Support + +Perform Image installation using <span class="title-ref">install image</span> CLI command. + +## Gowin GW-FN-1UR1-10G + +A platform utilizing an Intel Alder Lake-N100 CPU with 6M cache, TDP 6W. +Onboard LPDDR5 16GB RAM and 128GB eMMC (can be used for image installation). + +The appliance comes with 2 \* 2.5GbE Intel I226-V and 3 \* 1GbE Intel I210 +where one supports IEEE802.3at PoE+ (Typical 30W). + +In addition there is a Mellanox ConnectX-3 2\* 10GbE SFP+ NIC available. + +**NOTE:** This is the entry level platform. Other derivates exists with +i3-N305 CPU and 2x 25GbE! + +### Gowin Shopping Cart + +- 1x Gowin GW-FN-1UR1-10G +- 2x 128GB M.2 NVMe SSDs + +### Optional (WiFi + WWAN) + +- 1x MediaTek 7921E M.2 NGFF WIFI module (not tested as this currently leads to + a Kernel crash) +- 1x HP LT4120 Snapdragon X5 LTE WWAN module + +### Pictures + +<figure> +<img src="../_static/images/gowin-01.webp" /> +</figure> + +<figure> +<img src="../_static/images/gowin-02.webp" /> +</figure> + +<figure> +<img src="../_static/images/gowin-03.webp" /> +</figure> + +<figure> +<img src="../_static/images/gowin-04.webp" /> +</figure> + +### Cooling + +The device itself is passivly cooled, whereas the power supply has an active fan. +Even if the main processor is powered off, the power supply fan is operating and +the entire chassis draws 7.5W. During operation the chassis drew arround 38W. + +### BIOS Settings + +No settings needed to be altered, everything worked out of the box! + +### Installation + +The system provides a regular RS232 console port using 115200,8n1 setting which +is sufficient to install VyOS from a USB pendrive. + +### First Boot + +Please note that there is a weirdness on the network interface mapping. +The interface \<-\> MAC mapping is going upwards but the NICs are placed +somehow swapped on the mainboard/MACs programmed in a swapped order. + +See interface description for more detailed mapping. + +``` none +vyos@vyos:~$ show interfaces +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address MAC VRF MTU S/L Description +----------- -------------- ----------------- ------- ----- ----- ------------- +eth0 - 00:f0:cb:00:00:99 default 1500 u/D Intel I226-V - Front eth2 +eth1 - 00:f0:cb:00:00:9a default 1500 u/D Intel I226-V - Front eth1 +eth2 - 00:f0:cb:00:00:9b default 1500 u/D Intel I210 - Front eth4 +eth3 - 00:f0:cb:00:00:9c default 1500 u/D Intel I210 - Front eth3 +eth4 - 00:f0:cb:00:00:9d default 1500 u/D Intel I210 - Front POE +eth5 - 00:02:c9:00:00:30 default 1500 u/D Mellanox ConnectX-3 - SFP2 +eth6 - 00:02:c9:00:00:31 default 1500 u/D Mellanox ConnectX-3 - SFP1 +lo 127.0.0.1/8 00:00:00:00:00:00 default 65536 u/u + ::1/128 +wwan0 - d2:39:76:8e:05:12 default 1500 A/D +``` + +#### VyOS 1.4 (sagitta) + +Connect serial port to a PC through a USB \<-\> RJ45 console cable. Set terminal +emulator to 115200 8N1. You can also perform the installation using VGA or HDMI +ports. + +In this example I choose to install VyOS as RAID-1 on both NVMe drives. However, +a previous installation on the 128GB eMMC storage worked without any issues, +too. + +``` none +Welcome to VyOS - vyos ttyS0 + +vyos login: +``` + +Perform Image installation using <span class="title-ref">install image</span> CLI command. This installation +uses two 128GB NVMe disks setup as RAID1. + +``` none +Welcome to VyOS! + + ┌── ┐ + . VyOS 1.4.0 + └ ──┘ sagitta + +* Support portal: https://support.vyos.io +* Documentation: https://docs.vyos.io/en/sagitta +* Project news: https://blog.vyos.io +* Bug reports: https://vyos.dev + +You can change this banner using "set system login banner post-login" command. + +VyOS is a free software distribution that includes multiple components, +you can check individual component licenses under /usr/share/doc/*/copyright +Use of this pre-built image is governed by the EULA you can find in +/usr/share/vyos/EULA + +vyos@vyos:~$ install image + +Welcome to VyOS installation! +This command will install VyOS to your permanent storage. +Would you like to continue? [y/N] y + +What would you like to name this image? (Default: 1.4.0) + +Please enter a password for the "vyos" user: +Please confirm password for the "vyos" user: + +What console should be used by default? (K: KVM, S: Serial)? (Default: S) + +Probing disks +4 disk(s) found +Would you like to configure RAID-1 mirroring? [Y/n] y + +The following disks were found: + /dev/sda (14.4 GB) + /dev/mmcblk0 (116.5 GB) +Would you like to configure RAID-1 mirroring on them? [Y/n] n + +Would you like to choose two disks for RAID-1 mirroring? [Y/n] y +Disks available: + 1: /dev/sda (14.4 GB) + 2: /dev/mmcblk0 (116.5 GB) + 3: /dev/nvme1n1 (119.2 GB) + 4: /dev/nvme0n1 (119.2 GB) +Select first disk: 3 + +Remaining disks: + 1: /dev/sda (14.4 GB) + 2: /dev/mmcblk0 (116.5 GB) + 3: /dev/nvme0n1 (119.2 GB) +Select second disk: 3 + +Installation will delete all data on both drives. Continue? [y/N] y + +Searching for data from previous installations +No previous installation found +Creating partitions on /dev/nvme1n1 +Creating partition table... +Creating partitions on /dev/nvme0n1 +Creating partition table... +Creating RAID array +Updating initramfs +Creating filesystem on RAID array +The following config files are available for boot: + 1: /opt/vyatta/etc/config/config.boot + 2: /opt/vyatta/etc/config.boot.default + +Which file would you like as boot config? (Default: 1) +Creating temporary directories +Mounting new partitions +Creating a configuration file +Copying system image files +Installing GRUB configuration files +Installing GRUB to the drives +Cleaning up +Unmounting target filesystems +Removing temporary files +The image installed successfully; please reboot now. +``` + +### Hardware + +``` none +vyos@vyos:~$ lspci +00:00.0 Host bridge: Intel Corporation Device 461c +00:02.0 VGA compatible controller: Intel Corporation Alder Lake-N [UHD Graphics] +00:0a.0 Signal processing controller: Intel Corporation Platform Monitoring Technology (rev 01) +00:0d.0 USB controller: Intel Corporation Device 464e +00:14.0 USB controller: Intel Corporation Device 54ed +00:14.2 RAM memory: Intel Corporation Device 54ef +00:15.0 Serial bus controller: Intel Corporation Device 54e8 +00:16.0 Communication controller: Intel Corporation Device 54e0 +00:1a.0 SD Host controller: Intel Corporation Device 54c4 +00:1c.0 PCI bridge: Intel Corporation Device 54b8 +00:1c.2 PCI bridge: Intel Corporation Device 54ba +00:1c.3 PCI bridge: Intel Corporation Device 54bb +00:1c.6 PCI bridge: Intel Corporation Device 54be +00:1d.0 PCI bridge: Intel Corporation Device 54b0 +00:1f.0 ISA bridge: Intel Corporation Device 5481 +00:1f.4 SMBus: Intel Corporation Device 54a3 +00:1f.5 Serial bus controller: Intel Corporation Device 54a4 +01:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +02:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +02:02.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +02:06.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +02:0e.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +03:00.0 Ethernet controller: Intel Corporation Ethernet Controller I226-V (rev 04) +04:00.0 Ethernet controller: Intel Corporation Ethernet Controller I226-V (rev 04) +05:00.0 Network controller: MEDIATEK Corp. MT7922 802.11ax PCI Express Wireless Network Adapter +06:00.0 SATA controller: ASMedia Technology Inc. Device 0622 (rev 01) +07:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +08:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +08:02.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +08:06.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +08:0e.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +09:00.0 Ethernet controller: Intel Corporation I210 Gigabit Network Connection (rev 03) +0a:00.0 Ethernet controller: Intel Corporation I210 Gigabit Network Connection (rev 03) +0b:00.0 Ethernet controller: Intel Corporation I210 Gigabit Network Connection (rev 03) +0d:00.0 Non-Volatile memory controller: Device 1ed0:2283 +0f:00.0 Non-Volatile memory controller: Device 1ed0:2283 +11:00.0 Ethernet controller: Mellanox Technologies MT27500 Family [ConnectX-3] +``` + +``` none +vyos@vyos:~$ lsusb +Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub +Bus 003 Device 005: ID 0e8d:c616 MediaTek Inc. Wireless_Device +Bus 003 Device 003: ID 413c:2113 Dell Computer Corp. KB216 Wired Keyboard +Bus 003 Device 004: ID 03f0:9d1d HP, Inc HP lt4120 Snapdragon X5 LTE +Bus 003 Device 002: ID 05e3:0610 Genesys Logic, Inc. Hub +Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub +Bus 002 Device 002: ID 05e3:0620 Genesys Logic, Inc. GL3523 Hub +Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub +Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub +``` + +#### WWAN + +The LTE module can be enabled as simple as this config snippet: + +``` none +interfaces { + wwan wwan0 { + address "dhcp" + apn "YOUR-APN-GOES-HERE" + } +} +``` + +For more information please refer to chapter: `wwan-interface` diff --git a/docs/installation/virtual/md-docker.md b/docs/installation/virtual/md-docker.md new file mode 100644 index 00000000..964b9f64 --- /dev/null +++ b/docs/installation/virtual/md-docker.md @@ -0,0 +1,65 @@ +# Running in Docker Container + +Docker is an open-source project for deploying applications as standardized +units called containers. Deploying VyOS in a container provides a simple and +lightweight mechanism for both testing and packet routing for container +workloads. + +## IPv6 Support for docker + +VyOS requires an IPv6-enabled docker network. Currently linux distributions +do not enable docker IPv6 support by default. You can enable IPv6 support in +two ways. + +### Method 1: Create a docker network with IPv6 support + +Here is a example using the macvlan driver. + +``` none +docker network create --ipv6 -d macvlan -o parent=eth0 --subnet 2001:db8::/64 --subnet 192.0.2.0/24 mynet +``` + +### Method 2: Add IPv6 support to the docker daemon + +Edit /etc/docker/daemon.json to set the `ipv6` key to `true` and to specify +the `fixed-cidr-v6` to your desired IPv6 subnet. + +``` none +{ + "ipv6": true, + "fixed-cidr-v6": "2001:db8::/64" +} +``` + +Reload the docker configuration. + +``` none +$ sudo systemctl reload docker +``` + +## Deploy container from ISO + +Download the ISO on which you want to base the container. In this example, +the name of the ISO is `vyos-1.4-rolling-202308240020-amd64.iso`. If you +created a custom IPv6-enabled network, the `docker run` command below +will require that this network be included as the `--net` parameter to +`docker run`. + +``` none +$ mkdir vyos && cd vyos +$ curl -o vyos-1.4-rolling-202308240020-amd64.iso https://github.com/vyos/vyos-rolling-nightly-builds/releases/download/1.4-rolling-202308240020/vyos-1.4-rolling-202308240020-amd64.iso +$ mkdir rootfs +$ sudo mount -o loop vyos-1.4-rolling-202308240020-amd64.iso rootfs +$ sudo apt-get install -y squashfs-tools +$ mkdir unsquashfs +$ sudo unsquashfs -f -d unsquashfs/ rootfs/live/filesystem.squashfs +$ sudo tar -C unsquashfs -c . | docker import - vyos:1.4-rolling-202111281249 +$ sudo umount rootfs +$ cd .. +$ sudo rm -rf vyos +$ docker run -d --rm --name vyos --privileged -v /lib/modules:/lib/modules \ +> vyos:1.4-rolling-202111281249 /sbin/init +$ docker exec -ti vyos su - vyos +``` + +You can execute `docker stop vyos` when you are finished with the container. diff --git a/docs/installation/virtual/md-eve-ng.md b/docs/installation/virtual/md-eve-ng.md new file mode 100644 index 00000000..3e32e61f --- /dev/null +++ b/docs/installation/virtual/md-eve-ng.md @@ -0,0 +1,5 @@ +# EVE-NG + +## References + +<https://www.eve-ng.net/> diff --git a/docs/installation/virtual/md-gns3.md b/docs/installation/virtual/md-gns3.md new file mode 100644 index 00000000..b1bb2a1d --- /dev/null +++ b/docs/installation/virtual/md-gns3.md @@ -0,0 +1,208 @@ +# Running on GNS3 + +Sometimes you may want to test VyOS in a lab environment. +[GNS3](http://www.gns3.com) is a network emulation software you +might use for it. + +This guide will provide the necessary steps for installing +and setting up VyOS on GNS3. + +## Requirements + +The following items are required: + +- A VyOS installation image (.iso file). You + can find how to get it on the `installation` page +- A working GNS3 installation. For further information see the + [GNS3 documentation](https://docs.gns3.com/). + +## VM setup + +First, a virtual machine (VM) for the VyOS installation must be created +in GNS3. + +Go to the GNS3 **File** menu, click **New template** and choose select +**Manually create a new Template**. + +<figure> +<img src="/_static/images/gns3-01.webp" /> +</figure> + +Select **Quemu VMs** and then click on the `New` button. + +<figure> +<img src="/_static/images/gns3-02.webp" /> +</figure> + +Write a name for your VM, for instance "VyOS", and click `Next`. + +<figure> +<img src="/_static/images/gns3-03.webp" /> +</figure> + +Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM +and click `Next`. + +<figure> +<img src="/_static/images/gns3-04.webp" /> +</figure> + +Select **telnet** as your console type and click `Next`. + +<figure> +<img src="/_static/images/gns3-05.webp" /> +</figure> + +Select **New image** for the base disk image of your VM and click +`Create`. + +<figure> +<img src="/_static/images/gns3-06.webp" /> +</figure> + +Use the defaults in the **Binary and format** window and click +`Next`. + +<figure> +<img src="/_static/images/gns3-07.webp" /> +</figure> + +Use the defaults in the **Qcow2 options** window and click `Next`. + +<figure> +<img src="/_static/images/gns3-08.webp" /> +</figure> + +Set the disk size to 2000 MiB, and click `Finish` to end the **Quemu +image creator**. + +<figure> +<img src="/_static/images/gns3-09.webp" /> +</figure> + +Click `Finish` to end the **New QEMU VM template** wizard. + +<figure> +<img src="/_static/images/gns3-10.webp" /> +</figure> + +Now the VM settings have to be edited. + +Being again at the **Preferences** window, having **Qemu VMs** +selected and having our new VM selected, click the `Edit` button. + +<figure> +<img src="/_static/images/gns3-11.webp" /> +</figure> + +In the **General settings** tab of your **QEMU VM template +configuration**, do the following: + +- Click on the `Browse...` button to choose the **Symbol** you want to + have representing your VM. +- In **Category** select in which group you want to find your VM. +- Set the **Boot priority** to **CD/DVD-ROM**. + +<figure> +<img src="/_static/images/gns3-12.webp" /> +</figure> + +At the **HDD** tab, change the Disk interface to **sata** to speed up +the boot process. + +<figure> +<img src="/_static/images/gns3-13.webp" /> +</figure> + +At the **CD/DVD** tab click on `Browse...` and locate the VyOS image +you want to install. + +<figure> +<img src="/_static/images/gns3-14.webp" /> +</figure> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +You probably will want to accept to copy the .iso file to your +default image directory when you are asked. + +</div> + +In the **Network** tab, set **0** as the number of adapters, set the +**Name format** to **eth{0}** and the **Type** to **Paravirtualized +Network I/O (virtio-net-pci)**. + +<figure> +<img src="/_static/images/gns3-15.webp" /> +</figure> + +In the **Advanced** tab, unmark the checkbox **Use as a linked base +VM** and click `OK`, which will save and close the **QEMU VM template +configuration** window. + +<figure> +<img src="/_static/images/gns3-16.webp" /> +</figure> + +At the general **Preferences** window, click `OK` to save and close. + +<figure> +<img src="/_static/images/gns3-17.webp" /> +</figure> + +## VyOS installation + +- Create a new project. +- Drag the newly created VyOS VM into it. +- Start the VM. +- Open a console. + The console should show the system booting. It will ask for the login + credentials, you are at the VyOS live system. +- `Install VyOS <installation>` + as normal (that is, using the `install image` command). +- After a successful installation, shutdown the VM with the `poweroff` + command. +- **Delete the VM** from the GNS3 project. + +The *VyOS-hda.qcow2* file now contains a working VyOS image and can be +used as a template. But it still needs some fixes before we can deploy +VyOS in our labs. + +## VyOS VM configuration + +To turn the template into a working VyOS machine, further steps are +necessary as outlined below: + +**General settings** tab: Set the boot priority to **HDD** + +<figure> +<img src="/_static/images/gns3-20.webp" /> +</figure> + +**CD/DVD** tab: Unmount the installation image file by clearing the +**Image** entry field. + +<figure> +<img src="/_static/images/gns3-21.webp" /> +</figure> + +Set the number of required network adapters, for example **4**. + +<figure> +<img src="/_static/images/gns3-215.webp" /> +</figure> + +**Advanced** settings tab: Mark the checkbox **Use as a linked +base VM** and click `OK` to save the changes. + +<figure> +<img src="/_static/images/gns3-22.webp" /> +</figure> + +The VyOS VM is now ready to be deployed. diff --git a/docs/installation/virtual/md-index.md b/docs/installation/virtual/md-index.md new file mode 100644 index 00000000..7ed572e4 --- /dev/null +++ b/docs/installation/virtual/md-index.md @@ -0,0 +1,12 @@ +# Running VyOS in Virtual Environments + +<div class="toctree" caption="Content"> + +libvirt +proxmox +vmware +gns3 +eve-ng +docker + +</div> diff --git a/docs/installation/virtual/md-libvirt.md b/docs/installation/virtual/md-libvirt.md new file mode 100644 index 00000000..04a05ad0 --- /dev/null +++ b/docs/installation/virtual/md-libvirt.md @@ -0,0 +1,176 @@ +# Running on Libvirt Qemu/KVM + +Libvirt is an open-source API, daemon and management tool for managing platform +virtualization. There are several ways to deploy VyOS on libvirt kvm. +Use Virt-manager and native CLI. In an example we will be use use 4 gigabytes +of memory, 2 cores CPU and default network virbr0. + +## CLI + +### Deploy from ISO + +Create VM name `vyos_r1`. You must specify the path to the `ISO` image, +the disk `qcow2` will be created automatically. The `default` network is +the virtual network (type Virtio) created by the hypervisor with NAT. + +``` none +$ virt-install -n vyos_r1 \ + --ram 4096 \ + --vcpus 2 \ + --cdrom /var/lib/libvirt/images/vyos.iso \ + --os-type linux \ + --os-variant debian10 \ + --network network=default \ + --graphics vnc \ + --hvm \ + --virt-type kvm \ + --disk path=/var/lib/libvirt/images/vyos_r1.qcow2,bus=virtio,size=8 \ + --noautoconsole +``` + +Connect to VM with command `virsh console vyos_r1` + +``` none +$ virsh console vyos_r1 + +Connected to domain vyos_r1 +Escape character is ^] + +vyos login: vyos +Password: + +vyos@vyos:~$ install image +``` + +After installation - exit from the console using the key combination +`Ctrl + ]` and reboot the system. + +### Deploy from qcow2 + +The convenience of using `KVM (Kernel-based Virtual Machine)` +images is that they don't need to be installed. +Download predefined VyOS.qcow2 image for `KVM` + +``` none +curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 +``` + +Create VM with `import` qcow2 disk option. + +``` none +$ virt-install -n vyos_r2 \ + --ram 4096 \ + --vcpus 2 \ + --os-type linux \ + --os-variant debian10 \ + --network network=default \ + --graphics vnc \ + --hvm \ + --virt-type kvm \ + --disk path=/var/lib/libvirt/images/vyos_kvm.qcow2,bus=virtio \ + --import \ + --noautoconsole +``` + +Connect to VM with command `virsh console vyos_r2` + +``` none +$ virsh console vyos_r2 + +Connected to domain vyos_r2 +Escape character is ^] + +vyos login: vyos +Password: + +vyos@vyos:~$ +``` + +The system is fully operational. + +## Virt-manager + +The virt-manager application is a desktop user interface for managing virtual +machines through libvirt. On the linux open +`VMM (Virtual Machine Manager)`. + +### Deploy from ISO + +1. Open `VMM (Virtual Machine Manager)` and Create a new + `VM (Virtual Machine)` +2. Choose `Local install media` (ISO) + +<figure> +<img src="/_static/images/virt-libvirt-01.webp" /> +</figure> + +3. Choose path to iso vyos.iso. Operating System can be any Debian based. + +<figure> +<img src="/_static/images/virt-libvirt-02.webp" /> +</figure> + +4. Choose Memory and CPU + +<figure> +<img src="/_static/images/virt-libvirt-03.webp" /> +</figure> + +5. Disk size + +<figure> +<img src="/_static/images/virt-libvirt-04.webp" /> +</figure> + +6. Name of VM and network selection + +<figure> +<img src="/_static/images/virt-libvirt-05.webp" /> +</figure> + +7. Then you will be taken to the console. + +<figure> +<img src="/_static/images/virt-libvirt-06.webp" /> +</figure> + +### Deploy from qcow2 + +Download predefined VyOS.qcow2 image for `KVM` + +``` none +curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 +``` + +1. Open `VMM (Virtual Machine Manager)` and Create a new + `VM (Virtual Machine)` +2. Choose `Import existing disk` image + +<figure> +<img src="/_static/images/virt-libvirt-qc-01.webp" /> +</figure> + +3. Choose the path to the image `vyos_kvm.qcow2` that was previously + downloaded . Operation System can be any Debian based. + +<figure> +<img src="/_static/images/virt-libvirt-qc-02.webp" /> +</figure> + +4. Choose Memory and CPU + +<figure> +<img src="/_static/images/virt-libvirt-03.webp" /> +</figure> + +5. Name of VM and network selection + +<figure> +<img src="/_static/images/virt-libvirt-05.webp" /> +</figure> + +6. Then you will be taken to the console. + +<figure> +<img src="/_static/images/virt-libvirt-qc-03.webp" /> +</figure> diff --git a/docs/installation/virtual/md-proxmox.md b/docs/installation/virtual/md-proxmox.md new file mode 100644 index 00000000..da4bd03b --- /dev/null +++ b/docs/installation/virtual/md-proxmox.md @@ -0,0 +1,43 @@ +# Running on Proxmox + +Proxmox is an open-source platform for virtualization. Please visit +<https://vyos.io> to see how to get a qcow2 image that can be imported +into Proxmox. + +## Deploy VyOS from CLI with qcow2 image + +1. Copy the qcow2 image to a temporary directory on the Proxmox server. +2. The commands below assume that virtual machine ID 200 is unused and that the user wants the disk stored in a storage pool called <span class="title-ref">local-lvm</span>. + +``` none +$ qm create 200 --name vyos2 --memory 2048 --net0 virtio,bridge=vmbr0 +$ qm importdisk 200 /path/to/image/vyos-1.2.8-proxmox-2G.qcow2 local-lvm +$ qm set 200 --virtio0 local-lvm:vm-200-disk-0 +$ qm set 200 --boot order=virtio0 +``` + +3. Optionally, the user can attach a CDROM with an ISO as a cloud-init data source. The below command assumes the ISO has been uploaded to the <span class="title-ref">local</span> storage pool with the name <span class="title-ref">seed.iso</span>. + +``` none +$ qm set 200 --ide2 media=cdrom,file=local:iso/seed.iso +``` + +4. Start the virtual machine in the proxmox GUI or CLI using `qm start 200`. + +## Deploy VyOS from CLI with rolling release ISO + +1. Download the rolling release iso from <https://vyos.net/get/nightly-builds/>. Non-subscribers can always get the LTS release by building it from source. Instructions can be found in the `build` section of this manual. VyOS source code repository is available <https://github.com/vyos/vyos-build>. +2. Prepare VM for installation from ISO media. The commands below assume that your iso is available in a storage pool 'local', that you want it to have a VM ID '200' and want to create a new disk on storage pool 'local-lvm' of size 15GB. + +``` none +qm create 200 --name vyos --memory 2048 --net0 virtio,bridge=vmbr0 --ide2 media=cdrom,file=local:iso/live-image-amd64.hybrid.iso --virtio0 local-lvm:15 +``` + +3. Start the VM using the command `qm start 200` or using the start button located in the proxmox GUI. +4. Using the proxmox webGUI, open the virtual console for your newly created vm. Login username/password is `vyos/vyos`. +5. Once booted into the live system, type `install image` into the command line and follow the prompts to install VyOS to the virtual drive. +6. After installation has completed, remove the installation iso using the GUI or `qm set 200 --ide2 none`. +7. Reboot the virtual machine using the GUI or `qm reboot 200`. + +Visit <https://www.proxmox.com/en/> for more information about the download +and installation of this hypervisor. diff --git a/docs/installation/virtual/md-vmware.md b/docs/installation/virtual/md-vmware.md new file mode 100644 index 00000000..6d693455 --- /dev/null +++ b/docs/installation/virtual/md-vmware.md @@ -0,0 +1,35 @@ +# Running on VMware ESXi + +## ESXi 5.5 or later + +.ova files are available for supporting users, and a VyOS can also be stood up +using a generic Linux instance, and attaching the bootable ISO file and +installing from the ISO using the normal process around <span class="title-ref">install image</span>. + +:::{note} +There have been previous documented issues with GRE/IPSEC tunneling +using the E1000 adapter on the VyOS guest, and use of the VMXNET3 has been +advised. +::: + +### Memory Contention Considerations + +When the underlying ESXi host is approaching ~92% memory utilisation it will +start the balloon process in a 'soft' state to start reclaiming memory from +guest operating systems. This causes an artificial pressure using the vmmemctl +driver on memory usage on the virtual guest. As VyOS by default does not have +a swap file, this vmmemctl pressure is unable to force processes to move in +memory data to the paging file, and blindly consumes memory forcing the +virtual guest into a low memory state with no way to escape. The balloon +can expand to 65% of guest allocated memory, so a VyOS guest running \>35% of +memory usage, can encounter an out of memory situation, and trigger the kernel +oom_kill process. At this point a weighted lottery favouring memory hungry +processes will be run with the unlucky winner being terminated by the kernel. + +It is advised that VyOS routers are configured in a resource group with +adequate memory reservations so that ballooning is not inflicted on +virtual VyOS guests. + +### References + +<https://muralidba.blogspot.com/2018/03/how-does-linux-out-of-memory-oom-killer.html> diff --git a/docs/introducing/md-about.md b/docs/introducing/md-about.md new file mode 100644 index 00000000..51e09857 --- /dev/null +++ b/docs/introducing/md-about.md @@ -0,0 +1,23 @@ +# About + +VyOS is an open source network operating system based on Debian GNU/Linux. + +VyOS provides a free routing platform that competes directly with other +commercially available solutions from well known network providers. Because +VyOS runs on standard amd64, i586 and ARM systems, it is able to be used +as a router and firewall platform for cloud deployments. + +We use multiple live versions of our manual, hosted thankfully by +<https://readthedocs.org>. We will provide one version of the manual for every +VyOS major version starting with VyOS 1.2 which will receive Long-term support +(LTS). + +The manual version is selected/specified by it's Git branch name. You can +switch between versions of the documentation by selecting the appropriate +branch on the bottom left corner. + +VyOS CLI syntax may change between major (and sometimes minor) versions. Please +always refer to the documentation matching your current, running installation. +If a change in the CLI is required, VyOS will ship a so called migration script +which will take care of adjusting the syntax. No action needs to be taken by +you. diff --git a/docs/introducing/md-history.md b/docs/introducing/md-history.md new file mode 100644 index 00000000..c97b59d4 --- /dev/null +++ b/docs/introducing/md-history.md @@ -0,0 +1,122 @@ +# History + +## In the beginning... + +There once was a network operating system based on Debian GNU/Linux, +called Vyatta.[1] 2006 onwards, it was a great free software +alternative to Cisco IOS and Jupiter JUNOS. It came in two editions: +Vyatta Core (previously Vyatta Community Edition) that was completely +free software, and Vyatta Subscription Edition that had proprietary +features and was only available to paying customers.[2] + +Vyatta was acquired by Brocade Communication Systems in 2012. Shortly +after, Brocade renamed Vyatta Subscription Edition to Brocade vRouter, +discontinued Vyatta Core and shut down the community forum without a +notice. The bug tracker and Git repositories followed next year. + +It's worth noting that by the time Brocade acquired Vyatta, +development of Vyatta Core was already stagnated. Vyatta Subscription +Edition (and thus, Vyatta development as a whole) had been replacing +core components with proprietary software, meaning few features made +it to Vyatta Core, and those that did were bug-ridden and hamstrung. + +In 2013, soon after Vyatta Core was abandoned, the community forked +the last Vyatta Core version (6.6R1) and VyOS Project came into being. +[Sentrium SL](https://blog.vyos.io/sentrium-what-sentrium) was +established by VyOS maintainers in 2014 to fund VyOS development by +selling support, consulting services and prebuilt long-term support +images. + +Brocade was acquired by Broadcom in 2016 and sold what remains of +erstwhile Vyatta to AT&T in 2017, who in turn sold it to Ciena in 2021. + +## Major releases + +VyOS major versions used to be named after elements in order of atomic +numbers. With 1.2, this naming scheme was replaced with the much +cooler scheme of Latin names of [IAU](https://en.wikipedia.org/wiki/IAU_designated_constellations_by_area) +designated constellations by solid angle area, starting from the smallest. + +### Hydrogen (1.0) + +Released just in time for holidays on 22 December 2013, Hydrogen was +the first major VyOS release. It fixed features that were broken in +Vyatta Core 6.6 (such as IPv4 BGP peer groups and DHCPv6 relay) and +introduced command scripting, a task scheduler and web proxy LDAP +authentication. + +### Helium (1.1) + +Helium was released on 9 October 2014, exactly on the day VyOS Project +first came into being in the previous year. Helium came with a lot of +new features, including an event handler and support for L2TPv3, +802.1ad QinQ and IGMP proxy, as well as experimental support for VXLAN +and DMVPN (the latter of which was also broken in Vyatta Core due to +its reliance on a proprietary NHRP implementation). + +### Crux (1.2) + +Crux (the Southern Cross) came out on 28 January 2019 and was the +first major release of VyOS as we know it today. The underlying +Debian base was upgraded from Squeeze (6) to Jessie (8). + +Although Crux came with too many new features to mention here, some +noteworthy ones are: an mDNS repeater, a broadcast relay, +a high-performance PPPoE server, an HFSC scheduler, as well as support +for Wireguard, unicast VRRP, RPKI for BGP and fully 802.1ad-compliant +QinQ ethertype. The telnet server and support for P2P filtering were +removed. + +Crux is the first version to feature the modular image build system. +CLI definitions began to be written in the modern, verifiable XML +templates. Python APIs were introduced for command scripting and +configuration migration. Introduction of new Perl and shell code was +proscribed and the rewriting of legacy Perl code in pure Python began +with Crux. + +As of 2022, Crux is still supported and maintained. + +### Equuleus (1.3) + +The current long-term support version of VyOS, Equuleus (the Pony) +came out on 21 December 2021, once again in time for the winter +holidays. + +Equuleus brought many long-desired features with it, most notably +an SSTP VPN server, an IPoE server, an OpenConnect VPN server and +a serial console server, in addition to reworked support for WWAN +interfaces, support for GENEVE and MACSec interfaces, VRF, IS-IS +routing, preliminary support for MPLS and LDP, and many other +initialisms. + +As of 2022, Equuleus is in the stable. + +### Sagitta (1.4) + +Sagitta (the Arrow) is the codename of the current development +branch, so there's no VyOS 1.4 yet. + +### Circinus (1.5) + +Circinus (the Compass) is the codename of the upcoming development +branch, so there's no VyOS 1.5 yet. + +## A note on copyright + +Unlike Vyatta, VyOS never had (nor will ever have) proprietary code. +The only proprietary material in VyOS is non-code assets, such as +graphics and the trademark "VyOS".[3] This means you can build your +own long-term support images (as the entire toolchain we use is free +software) and even distribute them, given you rename it and remove +such assets before building. Although note that we do not provide +support for images distributed by a third-party. See the +[artwork license](https://github.com/vyos/vyos-build/blob/current/LICENSE.artwork) +and the end-user license agreement at `/usr/share/vyos/EULA` in +any pre-built image for more precise information. + +[1] From the Sanskrit adjective "Vyātta" (व्यात्त), meaning opened. + +[2] A business model comparable to that of Redis, rather than that +of VyOS today. + +[3] This is not unlike how Linus Torvalds owns the trademark "Linux". diff --git a/docs/md-404.md b/docs/md-404.md new file mode 100644 index 00000000..102a00b9 --- /dev/null +++ b/docs/md-404.md @@ -0,0 +1,11 @@ +orphan + +# Page Not Found + +Sorry, We could not find a page. +Try using the search box or go to the release homepage: + +> - [1.2.x (crux)](https://docs.vyos.io/en/crux/) +> - [1.3.x (equuleus)](https://docs.vyos.io/en/equuleus/) +> - [1.4.x (sagitta)](https://docs.vyos.io/en/sagitta/) +> - [rolling release (circinus)](https://docs.vyos.io/en/latest/) diff --git a/docs/md-cli.md b/docs/md-cli.md new file mode 100644 index 00000000..7a5af126 --- /dev/null +++ b/docs/md-cli.md @@ -0,0 +1,1178 @@ +# Command Line Interface + +The VyOS `CLI (Command-Line Interface)` comprises an operational and a +configuration mode. + +## Operational Mode + +Operational mode allows for commands to perform operational system tasks and +view system and service status, while configuration mode allows for the +modification of system configuration. + +The CLI provides a built-in help system. In the CLI the `?` key may be used +to display available commands. The `TAB` key can be used to auto-complete +commands and will present the help system upon a conflict or unknown value. + +For example typing `sh` followed by the `TAB` key will complete to +`show`. Pressing `TAB` a second time will display the possible +sub-commands of the `show` command. + +``` none +vyos@vyos:~$ s[tab] +set show +``` + +Example showing possible show commands: + +``` none +vyos@vyos:~$ show [tab] +Possible completions: + arp Show Address Resolution Protocol (ARP) information + bridge Show bridging information + cluster Show clustering information + configuration Show running configuration + conntrack Show conntrack entries in the conntrack table + conntrack-sync + Show connection syncing information + date Show system date and time + dhcp Show Dynamic Host Configuration Protocol (DHCP) information + dhcpv6 Show status related to DHCPv6 + disk Show status of disk device + dns Show Domain Name Server (DNS) information + file Show files for a particular image + firewall Show firewall information + flow-accounting + Show flow accounting statistics + hardware Show system hardware details + history show command history + host Show host information + incoming Show ethernet input-policy information +: q +``` + +You can scroll up with the keys `[Shift]+[PageUp]` and scroll down with +`[Shift]+[PageDown]`. + +When the output of a command results in more lines than can be displayed on the +terminal screen the output is paginated as indicated by a `:` prompt. + +When viewing in page mode the following commands are available: +- `q` key can be used to cancel output +- `space` will scroll down one page +- `b` will scroll back one page +- `return` will scroll down one line +- `up-arrow` and `down-arrow` will scroll up or down one line at a + time respectively +- `left-arrow` and `right-arrow` can be used to scroll left or right + in the event that the output has lines which exceed the terminal size. + +### Operational mode command families + +Many operational mode commands in VyOS are placed in families such as +`show`, `clear`, or `reset`. Every such family has a specific +meaning to allow the user to guess how the command is going to behave — +in particular, whether it will be disruptive to the system or not. + +Note that this convention was not always followed with perfect +consistency and some commands may still be in wrong families, so you +should always check the command help and documentation if you are not +sure what exactly it does. + +#### clear + +"Clear" commands are completely non-disruptive to any system operations. +Generally, they can be used freely without hesitation. + +Most often their purpose is to remove or reset various debug and +diagnostic information such as system logs and packet counters. + +Examples: + +- `clear console` — clears the screen. +- `clear interfaces ethernet eth0 counters` — zeroes packet counters + on `eth0`. +- `clear log` — deletes all system log entries. + +#### reset + +"Reset" commands can be locally-disruptive. They may, for example, +terminate a single user session or a session with a dynamic routing +protocol peer. + +They should be used with caution since they may have a significant +impact on a particular users in the network. + +- `reset pppoe-server username jsmith` — terminate all PPPoE sessions + from user `jsmith`. +- `reset bgp 192.0.2.54` — terminates the BGP session with neighbor + 192.0.2.54. +- `reset vpn ipsec site-to-site peer vpn.example.com` — terminates + IPsec tunnels to `vpn.example.com`. + +#### restart + +"Restart" operations may disrupt an entire subsystem. Most often they +initiate a restart of a server process, which causes it to be +unavailable for a brief period and resets all the process state. + +They should be used with extreme caution. + +- `restart dhcp server` — restarts the IPv4 DHCP server process (DHCP + requests are not served while it is restarting). +- `restart ipsec` — restarts the IPsec process (which forces all + sessions and all IPsec process state to reset). + +#### force + +"Force" commands force the system to perform an action that it might +perform by itself at a later point. + +Examples: + +- `force arp request interface eth1 address 10.3.0.2` — send a + gratuitious ARP request. +- `force root-partition-auto-resize` — grow the root filesystem to + the size of the system partition (this is also done on startup, but + this command can do it without a reboot). + +#### execute + +"Execute" commands are for executing various diagnostic and auxilliary +actions that the system would never perform by itself. + +Examples: + +- `execute wake-on-lan interface <intf> host <MAC>` — send a + Wake-On-LAN packet to a host. + +#### show + +"Show" commands display various system information. They may +occasionally use a pager for long outputs, that you can quit by pressing +the Q button. Their output is always finite, however. + +Examples: + +- `show system login` — displays current system users. +- `show ip route` — displays the IPv4 routing table. + +#### monitor + +"Monitor" commands initiate various monitoring operations that may +output information continuously, until terminated with `Ctrl-C` or +disabled. + +Examples: + +- `monitor log` — continuously outputs latest system logs. + +## Configuration Mode + +To enter configuration mode use the `configure` command: + +``` none +vyos@vyos:~$ configure +[edit] +vyos@vyos:~# +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Prompt changes from `$` to `#`. To exit configuration mode, +type `exit`. + +</div> + +``` none +vyos@vyos:~# exit +exit +vyos@vyos:~$ +``` + +See the configuration section of this document for more information on +configuration mode. + +# Configuration Overview + +VyOS makes use of a unified configuration file for the entire system's +configuration: `/config/config.boot`. This allows easy template +creation, backup, and replication of system configuration. A system can +thus also be easily cloned by simply copying the required configuration +files. + +## Terminology + +A VyOS system has three major types of configurations: + +- **Active** or **running configuration** is the system configuration + that is loaded and currently active (used by VyOS). Any change in + the configuration will have to be committed to belong to the + active/running configuration. +- **Working configuration** is the one that is currently being modified + in configuration mode. Changes made to the working configuration do + not go into effect until the changes are committed with the + `commit` command. At which time the working configuration will + become the active or running configuration. +- **Saved configuration** is the one saved to a file using the + `save` command. It allows you to keep safe a configuration for + future uses. There can be multiple configuration files. The default or + "boot" configuration is saved and loaded from the file + `/config/config.boot`. + +##### Seeing and navigating the configuration + +<div class="opcmd"> + +show configuration + +View the current active configuration, also known as the running +configuration, from the operational mode. + +``` none +vyos@vyos:~$ show configuration +interfaces { + ethernet eth0 { + address dhcp + hw-id 00:53:00:00:aa:01 + } + loopback lo { + } +} +service { + ssh { + port 22 + } +} +system { + config-management { + commit-revisions 20 + } + console { + device ttyS0 { + speed 9600 + } + } + login { + user vyos { + authentication { + encrypted-password **************** + } + level admin + } + } + ntp { + server 0.pool.ntp.org { + } + server 1.pool.ntp.org { + } + server 2.pool.ntp.org { + } + } + syslog { + global { + facility all { + level notice + } + facility protocols { + level debug + } + } + } +} +``` + +</div> + +By default, the configuration is displayed in a hierarchy like the above +example, this is only one of the possible ways to display the +configuration. When the configuration is generated and the device is +configured, changes are added through a collection of `set` and +`delete` commands. + +<div class="opcmd"> + +show configuration commands + +Get a collection of all the set commands required which led to the +running configuration. + +``` none +vyos@vyos:~$ show configuration commands +set interfaces ethernet eth0 address 'dhcp' +set interfaces ethernet eth0 hw-id '00:53:dd:44:3b:0f' +set interfaces loopback 'lo' +set service ssh port '22' +set system config-management commit-revisions '20' +set system console device ttyS0 speed '9600' +set system login user vyos authentication encrypted-password '$6$Vt68...QzF0' +set system login user vyos level 'admin' +set system ntp server '0.pool.ntp.org' +set system ntp server '1.pool.ntp.org' +set system ntp server '2.pool.ntp.org' +set system syslog global facility all level 'notice' +set system syslog global facility protocols level 'debug' +``` + +</div> + +Both these `show` commands should be executed when in operational +mode, they do not work directly in configuration mode. There is a +special way on how to `run_opmode_from_config_mode`. + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +Use the `show configuration commands | strip-private` +command when you want to hide private data. You may want to do so if +you want to share your configuration on the [forum](https://forum.vyos.io). + +</div> + +<div class="opcmd"> + +show configuration json + +View the current active configuration in JSON format. + +``` none +{"interfaces": {"ethernet": {"eth0": {"address": ["192.0.2.11/24", "192.0.2.35/24"], "hw-id": "52:54:00:48:a0:c6"}, "eth1": {"address": ["203.0.113.1/24"], "hw-id": "52:54:00:fc:50:0b"}}, "loopback": {"lo": {}}}, "protocols": {"static": {"route": {"0.0.0.0/0": {"next-hop": {"192.0.2.254": {}}}}}}, "service": {"ssh": {"disable-host-validation": {}}}, "system": {"config-management": {"commit-revisions": "100"}, "console": {"device": {"ttyS0": {"speed": "115200"}}}, "host-name": "r11-vyos", "login": {"user": {"vyos": {"authentication": {"encrypted-password": "$6$Vt68...F0", "plaintext-password": "", "public-keys": {"vyos@vyos": {"key": "AAAAxxx=", "type": "ssh-rsa"}}}}}}, "name-server": ["203.0.113.254"], "ntp": {"server": {"time1.vyos.net": {}, "time2.vyos.net": {}, "time3.vyos.net": {}}}, "syslog": {"global": {"facility": {"all": {"level": "info"}, "protocols": {"level": "debug"}}}}, "time-zone": "America/New_York"}} +``` + +</div> + +<div class="opcmd"> + +show configuration json pretty + +View the current active configuration in readable JSON format. + +``` none +{ + "interfaces": { + "ethernet": { + "eth0": { + "address": [ + "192.0.2.11/24", + "192.0.2.35/24" + ], + "hw-id": "52:54:00:48:a0:c6" + }, + "eth1": { + "address": [ + "203.0.113.1/24" + ], + "hw-id": "52:54:00:fc:50:0b" + } + }, + "loopback": { + "lo": {} + } + }, + "protocols": { + "static": { + "route": { + "0.0.0.0/0": { + "next-hop": { + "192.0.2.254": {} + } + } + } + } + }, + "service": { + "ssh": { + "disable-host-validation": {} + } + }, + "system": { + "config-management": { + "commit-revisions": "100" + }, + "console": { + "device": { + "ttyS0": { + "speed": "115200" + } + } + }, + "host-name": "r11-vyos", + "login": { + "user": { + "vyos": { + "authentication": { + "encrypted-password": "$6$Vt68...F0", + "plaintext-password": "", + "public-keys": { + "vyos@vyos": { + "key": "AAAAxxx=", + "type": "ssh-rsa" + } + } + } + } + } + }, + "name-server": [ + "203.0.113.254" + ], + "ntp": { + "server": { + "time1.vyos.net": {}, + "time2.vyos.net": {}, + "time3.vyos.net": {} + } + }, + "syslog": { + "global": { + "facility": { + "all": { + "level": "info" + }, + "protocols": { + "level": "debug" + } + } + } + }, + "time-zone": "America/New_York" + } +} +``` + +</div> + +###### The config mode + +When entering the configuration mode you are navigating inside a tree +structure, to enter configuration mode enter the command +`configure` when in operational mode. + +``` none +vyos@vyos$ configure +[edit] +vyos@vyos# +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +When going into configuration mode, prompt changes from +`$` to `#`. + +</div> + +All commands executed here are relative to the configuration level you +have entered. You can do everything from the top level, but commands +will be quite lengthy when manually typing them. + +The current hierarchy level can be changed by the `edit` +command. + +``` none +[edit] +vyos@vyos# edit interfaces ethernet eth0 + +[edit interfaces ethernet eth0] +vyos@vyos# +``` + +You are now in a sublevel relative to `interfaces ethernet eth0`, all +commands executed from this point on are relative to this sublevel. Use +either the `top` or `exit` command to go back to the top +of the hierarchy. You can also use the `up` command to move only +one level up at a time. + +<div class="cfgcmd"> + +show + +</div> + +The `show` command within configuration mode will show the +working configuration indicating line changes with `+` for additions, +`>` for replacements and `-` for deletions. + +**Example:** + +``` none +vyos@vyos:~$ configure +[edit] +vyos@vyos# show interfaces + ethernet eth0 { + description MY_OLD_DESCRIPTION + disable + hw-id 00:53:dd:44:3b:03 + } + loopback lo { + } +[edit] +vyos@vyos# set interfaces ethernet eth0 address dhcp +[edit] +vyos@vyos# set interfaces ethernet eth0 description MY_NEW_DESCRIPTION +[edit] +vyos@vyos# delete interfaces ethernet eth0 disable +[edit] +vyos@vyos# show interfaces + ethernet eth0 { ++ address dhcp +> description MY_NEW_DESCRIPTION +- disable + hw-id 00:53:dd:44:3b:03 + } + loopback lo { + } +``` + +It is also possible to display all `set` commands within configuration +mode using `show | commands` + +``` none +vyos@vyos# show interfaces ethernet eth0 | commands +set address dhcp +set hw-id 00:53:ad:44:3b:03 +``` + +These commands are also relative to the level you are inside and only +relevant configuration blocks will be displayed when entering a +sub-level. + +``` none +[edit interfaces ethernet eth0] +vyos@vyos# show + address dhcp + hw-id 00:53:ad:44:3b:03 +``` + +Exiting from the configuration mode is done via the `exit` +command from the top level, executing `exit` from within a +sub-level takes you back to the top level. + +``` none +[edit interfaces ethernet eth0] +vyos@vyos# exit +[edit] +vyos@vyos# exit +Warning: configuration changes have not been saved. +``` + +##### Editing the configuration + +The configuration can be edited by the use of `set` and +`delete` commands from within configuration mode. + +<div class="cfgcmd"> + +set + +Use this command to set the value of a parameter or to create a new +element. + +</div> + +Configuration commands are flattened from the tree into 'one-liner' +commands shown in `show configuration commands` from operation +mode. Commands are relative to the level where they are executed and all +redundant information from the current level is removed from the command +entered. + +``` none +[edit] +vyos@vyos# set interface ethernet eth0 address 192.0.2.100/24 +``` + +``` none +[edit interfaces ethernet eth0] +vyos@vyos# set address 203.0.113.6/24 +``` + +These two commands above are essentially the same, just executed from +different levels in the hierarchy. + +<div class="cfgcmd"> + +delete + +To delete a configuration entry use the `delete` command, +this also deletes all sub-levels under the current level you've +specified in the `delete` command. Deleting an entry will +also result in the element reverting back to its default value if one +exists. + +``` none +[edit interfaces ethernet eth0] +vyos@vyos# delete address 192.0.2.100/24 +``` + +</div> + +<div class="cfgcmd"> + +commit + +Any change you do on the configuration, will not take effect until +committed using the `commit` command in configuration mode. + +``` none +vyos@vyos# commit +[edit] +vyos@vyos# exit +Warning: configuration changes have not been saved. +vyos@vyos:~$ +``` + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +You can specify a commit message with +`commit comment <message>`. + +</div> + +<div id="save"> + +<div class="cfgcmd"> + +save + +Use this command to preserve configuration changes upon reboot. By +default it is stored at */config/config.boot*. In the case you want +to store the configuration file somewhere else, you can add a local +path, a SCP address, a FTP address or a TFTP address. + +``` none +vyos@vyos# save +Saving configuration to '/config/config.boot'... +Done +``` + +``` none +vyos@vyos# save [tab] +Possible completions: + <Enter> Save to system config file + <file> Save to file on local machine + scp://<user>:<passwd>@<host>:/<file> Save to file on remote machine + ftp://<user>:<passwd>@<host>/<file> Save to file on remote machine + tftp://<host>/<file> Save to file on remote machine +vyos@vyos# save tftp://192.168.0.100/vyos-test.config.boot +Saving configuration to 'tftp://192.168.0.100/vyos-test.config.boot'... +######################################################################## 100.0% +Done +``` + +</div> + +</div> + +<div class="cfgcmd"> + +exit \[discard\] + +Configuration mode can not be exited while uncommitted changes exist. +To exit configuration mode without applying changes, the +`exit discard` command must be used. + +All changes in the working config will thus be lost. + +``` none +vyos@vyos# exit +Cannot exit: configuration modified. +Use 'exit discard' to discard the changes and exit. +[edit] +vyos@vyos# exit discard +``` + +</div> + +<div class="cfgcmd"> + +commit-confirm \<minutes\> + +Use this command to temporarily commit your changes and set the +number of minutes available for validation. `confirm` must +be entered within those minutes, otherwise the system will reboot +into the previous configuration. The default value is 10 minutes. + +What if you are doing something dangerous? Suppose you want to setup +a firewall, and you are not sure there are no mistakes that will lock +you out of your system. You can use confirmed commit. If you issue +the `commit-confirm` command, your changes will be committed, and if +you don't issue the `confirm` command in 10 minutes, your +system will reboot into previous config revision. + +``` none +vyos@router# set firewall interface eth0 local name FromWorld +vyos@router# commit-confirm +commit confirm will be automatically reboot in 10 minutes unless confirmed +Proceed? [confirm]y +[edit] +vyos@router# confirm +[edit] +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +A reboot because you did not enter `confirm` will not +take you necessarily to the *saved configuration*, but to the +point before the unfortunate commit. + +</div> + +</div> + +<div class="cfgcmd"> + +copy + +Copy a configuration element. + +You can copy and remove configuration subtrees. Suppose you set up a +firewall ruleset `FromWorld` with one rule that allows traffic from +specific subnet. Now you want to setup a similar rule, but for +different subnet. Change your edit level to +`firewall name FromWorld` and use `copy rule 10 to rule 20`, then +modify rule 20. + +``` none +vyos@router# show firewall name FromWorld + default-action drop + rule 10 { + action accept + source { + address 203.0.113.0/24 + } + } +[edit] +vyos@router# edit firewall name FromWorld +[edit firewall name FromWorld] +vyos@router# copy rule 10 to rule 20 +[edit firewall name FromWorld] +vyos@router# set rule 20 source address 198.51.100.0/24 +[edit firewall name FromWorld] +vyos@router# commit +[edit firewall name FromWorld] +``` + +</div> + +<div class="cfgcmd"> + +rename + +Rename a configuration element. + +You can also rename config subtrees: + +``` none +vyos@router# rename rule 10 to rule 5 +[edit firewall name FromWorld] +vyos@router# commit +[edit firewall name FromWorld] +``` + +Note that `show` command respects your edit level and from this +level you can view the modified firewall ruleset with just `show` +with no parameters. + +``` none +vyos@router# show + default-action drop + rule 5 { + action accept + source { + address 203.0.113.0/24 + } + } + rule 20 { + action accept + source { + address 198.51.100.0/24 + } + } +``` + +</div> + +<div class="cfgcmd"> + +comment \<config node\> "comment text" + +Add comment as an annotation to a configuration node. + +The `comment` command allows you to insert a comment above the +`<config node>` configuration section. When shown, comments are +enclosed with `/*` and `*/` as open/close delimiters. Comments +need to be committed, just like other config changes. + +To remove an existing comment from your current configuration, +specify an empty string enclosed in double quote marks (`""`) as +the comment text. + +Example: + +``` none +vyos@vyos# comment firewall all-ping "Yes I know this VyOS is cool" +vyos@vyos# commit +vyos@vyos# show + firewall { + /* Yes I know this VyOS is cool */ + all-ping enable + broadcast-ping disable + ... + } +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +An important thing to note is that since the comment is +added on top of the section, it will not appear if the `show <section>` command is used. With the above example, the <span class="title-ref">show +firewall</span> command would return starting after the `firewall {` line, hiding the comment. + +</div> + +</div> + +##### Access opmode from config mode + +When inside configuration mode you are not directly able to execute +operational commands. + +<div class="cfgcmd"> + +run + +Access to these commands are possible through the use of the +`run [command]` command. From this command you will have access to +everything accessible from operational mode. + +Command completion and syntax help with `?` and `[tab]` will also +work. + +``` none +[edit] +vyos@vyos# run show interfaces +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +eth0 0.0.0.0/0 u/u +``` + +</div> + +##### Managing configurations + +VyOS comes with an integrated versioning system for the system +configuration. It automatically maintains a backup of every previous +configuration which has been committed to the system. The configurations +are versioned locally for rollback but they can also be stored on a +remote host for archiving/backup reasons. + +###### Local Archive + +Revisions are stored on disk. You can view, compare and rollback them to +any previous revisions if something goes wrong. + +<div class="opcmd"> + +show system commit + +View all existing revisions on the local system. + +``` none +vyos@vyos:~$ show system commit +0 2015-03-30 08:53:03 by vyos via cli +1 2015-03-30 08:52:20 by vyos via cli +2 2015-03-26 21:26:01 by root via boot-config-loader +3 2015-03-26 20:43:18 by root via boot-config-loader +4 2015-03-25 11:06:14 by root via boot-config-loader +5 2015-03-25 01:04:28 by root via boot-config-loader +6 2015-03-25 00:16:47 by vyos via cli +7 2015-03-24 23:43:45 by root via boot-config-loader +``` + +</div> + +<div class="cfgcmd"> + +set system config-management commit-revisions \<N\> + +You can specify the number of revisions stored on disk. N can be in +the range of 0 - 65535. When the number of revisions exceeds the +configured value, the oldest revision is removed. The default setting +for this value is to store 100 revisions locally. + +</div> + +###### Compare configurations + +VyOS lets you compare different configurations. + +<div class="cfgcmd"> + +compare \<saved | N\> \<M\> + +Use this command to spot what the differences are between different +configurations. + +``` none +vyos@vyos# compare [tab] +Possible completions: + <Enter> Compare working & active configurations + saved Compare working & saved configurations + <N> Compare working with revision N + <N> <M> Compare revision N with M + Revisions: + 0 2013-12-17 20:01:37 root by boot-config-loader + 1 2013-12-13 15:59:31 root by boot-config-loader + 2 2013-12-12 21:56:22 vyos by cli + 3 2013-12-12 21:55:11 vyos by cli + 4 2013-12-12 21:27:54 vyos by cli + 5 2013-12-12 21:23:29 vyos by cli + 6 2013-12-12 21:13:59 root by boot-config-loader + 7 2013-12-12 16:25:19 vyos by cli + 8 2013-12-12 15:44:36 vyos by cli + 9 2013-12-12 15:42:07 root by boot-config-loader + 10 2013-12-12 15:42:06 root by init +``` + +The command `compare` allows you to compare different type of +configurations. It also lets you compare different revisions through +the `compare N M` command, where N and M are revision +numbers. The output will describe how the configuration N is when +compared to M indicating with a plus sign (`+`) the additional +parts N has when compared to M, and indicating with a minus sign +(`-`) the lacking parts N misses when compared to M. + +``` none +vyos@vyos# compare 0 6 +[edit interfaces] ++dummy dum1 { ++ address 10.189.0.1/31 ++} +[edit interfaces ethernet eth0] ++vif 99 { ++ address 10.199.0.1/31 ++} +-vif 900 { +- address 192.0.2.4/24 +-} +``` + +</div> + +<div class="opcmd"> + +show system commit diff \<number\> + +Show commit revision difference. + +</div> + +The command above also lets you see the difference between two commits. +By default the difference with the running config is shown. + +``` none +vyos@router# run show system commit diff 4 +[edit system] ++ipv6 { ++ disable-forwarding ++} +``` + +This means four commits ago we did `set system ipv6 disable-forwarding`. + +###### Rollback Changes + +You can rollback configuration changes using the rollback command. This +will apply the selected revision and trigger a system reboot. + +<div class="cfgcmd"> + +rollback \<N\> + +Rollback to revision N (currently requires reboot) + +``` none +vyos@vyos# compare 1 +[edit system] +>host-name vyos-1 +[edit] + +vyos@vyos# rollback 1 +Proceed with reboot? [confirm][y] +Broadcast message from root@vyos-1 (pts/0) (Tue Dec 17 21:07:45 2013): +The system is going down for reboot NOW! +``` + +</div> + +###### Remote Archive + +VyOS can upload the configuration to a remote location after each call +to `commit`. You will have to set the commit-archive location. +TFTP, FTP, SCP and SFTP servers are supported. Every time a +`commit` is successful the `config.boot` file will be copied +to the defined destination(s). The filename used on the remote host will +be `config.boot-hostname.YYYYMMDD_HHMMSS`. + +<div class="cfgcmd"> + +set system config-management commit-archive location \<URI\> + +Specify remote location of commit archive as any of the below +`URI (Uniform Resource Identifier)` + +- `http://<user>:<passwd>@<host>:/<dir>` +- `https://<user>:<passwd>@<host>:/<dir>` +- `ftp://<user>:<passwd>@<host>/<dir>` +- `sftp://<user>:<passwd>@<host>/<dir>` +- `scp://<user>:<passwd>@<host>:/<dir>` +- `tftp://<host>/<dir>` +- `git+https://<user>:<passwd>@<host>/<path>` + +Since username and password are part of the URI, they need to be +properly url encoded if containing special characters. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The number of revisions don't affect the commit-archive. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +When using Git as destination for the commit archive the +`source-address` CLI option has no effect. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +You may find VyOS not allowing the secure connection because +it cannot verify the legitimacy of the remote server. You can use +the workaround below to quickly add the remote host's SSH +fingerprint to your `~/.ssh/known_hosts` file: + +</div> + +``` none +vyos@vyos# ssh-keyscan <host> >> ~/.ssh/known_hosts +``` + +</div> + +###### Saving and loading manually + +You can use the `save` and `load` commands if you want to manually +manage specific configuration files. + +When using the [save](#save) command, you can add a specific location where +to store your configuration file. And, when needed it, you will be able +to load it with the `load` command: + +<div class="cfgcmd"> + +load \<URI\> + +Use this command to load a configuration which will replace the +running configuration. Define the location of the configuration file +to be loaded. You can use a path to a local file, an SCP address, an +SFTP address, an FTP address, an HTTP address, an HTTPS address or a +TFTP address. + +``` none +vyos@vyos# load +Possible completions: + <Enter> Load from system config file + <file> Load from file on local machine + scp://<user>:<passwd>@<host>:/<file> Load from file on remote machine + sftp://<user>:<passwd>@<host>/<file> Load from file on remote machine + ftp://<user>:<passwd>@<host>/<file> Load from file on remote machine + http://<host>/<file> Load from file on remote machine + https://<host>/<file> Load from file on remote machine + tftp://<host>/<file> Load from file on remote machine +``` + +</div> + +###### Restore Default + +In the case you want to completely delete your configuration and restore +the default one, you can enter the following command in configuration +mode: + +``` none +load /opt/vyatta/etc/config.boot.default +``` + +You will be asked if you want to continue. If you accept, you will have +to use `commit` if you want to make the changes active. + +Then you may want to `save` in order to delete the saved +configuration too. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you are remotely connected, you will lose your connection. +You may want to copy first the config, edit it to ensure +connectivity, and load the edited config. + +</div> diff --git a/docs/md-coverage.md b/docs/md-coverage.md new file mode 100644 index 00000000..370f35ce --- /dev/null +++ b/docs/md-coverage.md @@ -0,0 +1,51 @@ +# Coverage + +Overview over all commands, which are documented in the +`.. cfgcmd::` or `.. opcmd::` Directives. + +The build process take all xml definition files +from [vyos-1x](https://github.com/vyos/vyos-1x) and a periodical export of +all VyOS commands and extract each leaf command or executable command. +After this the commands are compare and shown in +the following two tables. The script compare only the fixed part of a command. +All varables or values will be erase and then compare: + +for example there are these two commands: + +> - documentation: `interfaces ethernet <interface> address <address | dhcp | dhcpv6>` +> - xml: `interfaces ethernet <ethernet> address <address>` +> - VyOS: `interfaces ethernet <text> address <value>` + +Now the script earse all in between `<` and `>` and simply compare +the strings. + +**There are 3 kind of problems:** + +`Not documented yet` + +> - A XML command are not found in `.. cfgcmd::` or `.. opcmd::` Commands +> - The command should be documented + +`Nothing found in XML Definitions` + +> - `.. cfgcmd::` or `.. opcmd::` Command are not found in a XML command +> - Maybe the command where changed in the XML Definition, the feature is +> not anymore in VyOS, or there is a typo + +`Nothing found in VyOS` + +> - `.. cfgcmd::` or `.. opcmd::` Command are not found in a VyOS command +> - Maybe the command where changed, the feature is +> not anymore in VyOS, or there is a typo + +## Configuration Commands + +<div class="cfgcmdlist" show-coverage=""> + +</div> + +## Operational Commands + +<div class="opcmdlist" show-coverage=""> + +</div> diff --git a/docs/md-documentation.md b/docs/md-documentation.md new file mode 100644 index 00000000..4603a49b --- /dev/null +++ b/docs/md-documentation.md @@ -0,0 +1,430 @@ +lastproofread +2021-06-25 + +# Write Documentation + +We encourage every VyOS user to help us improve our documentation as we have +a deficit like most software projects. This not only helps you when reading +but also everyone else. + +If you are willing to contribute to our documentation this is the definite +guide how to do so. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +In contrast to submitting code patches, there is no requirement that +you open up a [Phabricator]() task prior to submitting a Pull-Request to the +documentation. + +</div> + +VyOS documentation is written in reStructuredText and generated to Read the Docs +pages with Sphinx, as per the Python tradition, as well as PDF files for offline +use through LaTeX. We welcome all sorts of contributions to the documentation. +Not just new additions but also corrections to existing documentation. + +The documentation source is kept in the Git repository at +<https://github.com/vyos/vyos-documentation> and you can follow the instructions +in the [README.md](https://github.com/vyos/vyos-documentation/blob/master/README.md) to build and test your changes. + +You can either install Sphinx (and TeX Live for PDF output) and build the +documentation locally, or use the [Dockerfile](https://github.com/vyos/vyos-documentation/blob/master/docker/Dockerfile) to build it in a container. + +## Guidelines + +There are a few things to keep in mind when contributing to the +documentation, for the sake of consistency and readability. + +Take a look at the `/documentation` page for an intricate explanation +of the documentation process. + +The following is a quick summary of the rules: + +- Use American English at all times. It's always a good idea to run + your text through a grammar and spell checker, such as [Grammarly](https://www.grammarly.com/). +- Don't forget to update `index.rst` when adding a new node. +- Try not to exceed 80 characters per line, but don't break URLs over this. +- Properly quote commands, filenames and brief code snippets with double backticks. +- Use literal blocks for longer snippets. +- Leave a newline before and after a header. +- Indent with two spaces. +- When in doubt, follow the style of existing documentation. + +And finally, remember that the reStructuredText files aren't +exclusively for generating HTML and PDF. They should be human-readable +and easily perused from a console. + +## Forking Workflow + +The Forking Workflow is fundamentally different from other popular Git +workflows. Instead of using a single server-side repository to act as the +"central" codebase, it gives every developer their own server-side repository. +This means that each contributor has not one, but two Git repositories: a +private local one and a public server-side one. + +The main advantage of the Forking Workflow is that contributions can be +integrated without the need for everybody to push to a single central +repository. Developers push to their own server-side repositories, and only the +project maintainer can push to the official repository. This allows the +maintainer to accept commits from any developer without giving them write +access to the official codebase. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Updates to our documentation should be delivered by a GitHub +pull-request. This requires you already have a GitHub account. + +</div> + +- Fork this project on GitHub <https://github.com/vyos/vyos-documentation/fork> + +- Clone fork to local machine, then change to that directory + `$ cd vyos-documentation` + +- Install the requirements `$ pip install -r requirements.txt` + (or something similar) + +- Create a new branch for your work, use a descriptive name of your work: + `$ git checkout -b <branch-name>` + +- Make all your changes - please keep our commit rules in mind + (`prepare_commit`). This mainly applies to proper commit messages + describing your change (how and why). Please check out the documentation of + [Sphinx-doc](https://www.sphinx-doc.org) or [reStructuredText](http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html) if you are not familiar with it. This is used + for writing our docs. Additional directives how to write in RST can be + obtained from [reStructuredTextDirectives](https://docutils.sourceforge.io/docs/ref/rst/directives.html). + +- Check your changes by locally building the documentation `$ make livehtml`. + Sphinx will build the html files in the `docs/_build` folder. We provide + you with a Docker container for an easy-to-use user experience. Check the + [README.md](https://github.com/vyos/vyos-documentation/blob/master/README.md) file of this repository. + +- View modified files by calling `$ git status`. You will get an overview of + all files modified by you. You can add individual files to the Git Index in + the next step. + +- Add modified files to Git index `$ git add path/to/filename` or add all + unstaged files `$ git add .`. All files added to the Git index will be part + of you following Git commit. + +- Commit your changes with the message, `$ git commit -m "<commit message>"` + or use `$ git commit -v` to have your configured editor launched. You can + type in a commit message. Again please make yourself comfortable without + rules (`prepare_commit`). + +- Push commits to your GitHub project: `$ git push -u origin <branch-name>` + +- Submit pull-request. In GitHub visit the main repository and you should + see a banner suggesting to make a pull request. Fill out the form and + describe what you do. + +- Once pull requests have been approved, you may want to locally update + your forked repository too. First you'll have to add a second remote + called <span class="title-ref">upstream</span> which points to our main repository. `$ git remote add upstream https://github.com/vyos/vyos-documentation.git` + + Check your configured remote repositories: + + ``` none + $ git remote -v + origin https://github.com/<username>/vyos-documentation.git (fetch) + origin https://github.com/<username>/vyos.documentation.git (push) + upstream https://github.com/vyos/vyos-documentation.git (fetch) + upstream https://github.com/vyos/vyos-documentation.git (push) + ``` + + Your remote repo on Github is called `origin`, while the original repo you + have forked is called `upstream`. Now you can locally update your forked + repo. + + ``` none + $ git fetch upstream + $ git checkout master + $ git merge upstream/master + ``` + +- If you also want to update your fork on GitHub, use the following: `$ git push origin master` + +## Style Guide + +Formatting and Sphinxmarkup +-------------------------- + +### TOC Level + +We use the following syntax for Headlines. + +``` none +##### +Title +##### + +******** +Chapters +******** + +Sections +======== + +Subsections +----------- + +Subsubsections +^^^^^^^^^^^^^^ + +Paragraphs +"""""""""" +``` + +### Cross-References + +A plugin will be used to generate a reference label for each headline. +To reference a page or a section in the documentation use the +`{ref}` command. + +For example, you want to reference the headline **VLAN** in the +**ethernet.rst** page. The plugin generates the label based on +the headline and the file path. + +`` {ref}`configuration/interfaces/ethernet:vlan `` + +to use an alternative hyperlink use it this way: + +`` {ref}`Check out VLAN<configuration/interfaces/ethernet:vlan> `` + +#### handle build errors + +The plugin will warn on build if a headline has a duplicate name in the +same document. To prevent this warning, you have to put a custom link on +top of the headline. + +``` none +Section A +========== + +Lorem ipsum dolor sit amet, consetetur sadipscing elitr + +Example +------- + +Lorem ipsum dolor sit amet, consetetur sadipscing elitr + +Section B +========== + +Lorem ipsum dolor sit amet, consetetur sadipscing elitr + +.. _section B example: + +Example +------- + +Lorem ipsum dolor sit amet, consetetur sadipscing elitr +``` + +### Address space + +Note the following RFCs (`5737`, `3849`, `5389` and +`7042`), which describe the reserved public IP addresses and autonomous +system numbers for the documentation: + +> - `192.0.2.0/24` +> - `198.51.100.0/24` +> - `203.0.113.0/24` +> - `2001:db8::/32` +> - 16bit ASN: `64496 - 64511` +> - 32bit ASN: `65536 - 65551` +> - Unicast MAC Addresses: `00-53-00` to `00-53-FF` +> - Multicast MAC-Addresses: `90-10-00` to `90-10-FF` + +Please do not use other public address space. + +### Line length + +Limit all lines to a maximum of 80 characters. + +Except in `.. code-block::` because it uses the html tag `<pre>` and +renders the same line format from the source rst file. + +### Autolinter + +Each GitHub pull request is automatically linted to check the address space and +line length. + +Sometimes it is necessary to provide real IP addresses like in the +`examples`. For this, please use the sphinx comment syntax +`.. stop_vyoslinter` to stop the linter and `.. start_vyoslinter` to start. + +### Custom Sphinx-doc Markup + +Custom commands have been developed for writing the documentation. Please +make yourself comfortable with those commands as this eases the way we +render the documentation. + +#### cfgcmd + +When documenting CLI commands, use the `.. cfgcmd::` directive +for all configuration mode commands. An explanation of the described command +should be added below this statement. +Replace all variable contents with \<value\> or something similar. + +With those custom commands, it will be possible to render them in a more +descriptive way in the resulting HTML/PDF manual. + +``` none +.. cfgcmd:: protocols static arp <ipaddress> hwaddr <macaddress> + + This will configure a static ARP entry, always resolving `192.0.2.100` to + `00:53:27:de:23:aa`. +``` + +For an inline configuration level command, use `{cfgcmd}` + +``` none +{cfgcmd}`set interface ethernet eth0` +``` + +To extract a defaultvalue from the XML definitions add a `:defaultvalue:` +to `.. cfgcmd::` directive. +To have this feature locally, the vyos-1x submodule must be initialized before. +Please be aware to not update the submodule in your PR. + +``` none +.. cfgcmd:: set system conntrack table-size <1-50000000> + :defaultvalue: + + The connection tracking table contains one entry for each connection being + tracked by the system. +``` + +#### opcmd + +When documenting operational level commands, use the `.. opcmd::` directive. +An explanation of the described command should be added below this statement. + +With those custom commands, it is possible to render them in a more +descriptive way in the resulting HTML/PDF manual. + +``` none +.. opcmd:: show protocols static arp + + Display all known ARP table entries spanning across all interfaces +``` + +For an inline operational level command, use `{opcmd}` + +``` none +{opcmd}`add system image` +``` + +#### cmdinclude + +To minimize redundancy, there is a special include directive. It includes a txt +file and replace the `{{ var0 }}` - `{{ var9 }}` with the correct value. + +``` none +.. cmdincludemd:: /_include/interface-address.txt + :var0: ethernet + :var1: eth1 +``` + +the content of interface-address.txt looks like this + +``` none +.. cfgcmd:: set interfaces {{ var0 }} <interface> address <address | dhcp | + dhcpv6> + + Configure interface `<interface>` with one or more interface + addresses. + + * **address** can be specified multiple times as IPv4 and/or IPv6 + address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64 + * **dhcp** interface address is received by DHCP from a DHCP server + on this segment. + * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 + server on this segment. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} address 192.0.2.1/24 + set interfaces {{ var0 }} {{ var1 }} address 192.0.2.2/24 + set interfaces {{ var0 }} {{ var1 }} address 2001:db8::ffff/64 + set interfaces {{ var0 }} {{ var1 }} address 2001:db8:100::ffff/64 +``` + +#### vytask + +When referencing to VyOS Phabricator Tasks, there is a custom Sphinx Markup +command called `vytask` that automatically renders to a proper Phabricator +URL. This is heavily used in the `release-notes` section. + +``` none +* {vytask}`T1605` Fixed regression in L2TP/IPsec server +* {vytask}`T1613` Netflow/sFlow captures IPv6 traffic correctly +``` + +##### Page content + +The documentation has 3 different types of pages. The same kind of pages must +have the same structure to achieve a recognition factor. + +All RST files must follow the same TOC Level syntax and have to start with + +``` +##### +Title +##### +``` + +### Configuration mode pages + +The configuration mode folder and the articles cover the specific level of +the commands. The exact level depends on the command. This should provide +stability for URLs used in the forum or blogpost. + +For example: + +> - `set firewall zone` is written in `firewall/zone.rst` +> - `set interfaces ethernet` is written in `interfaces/ethernet.rst` + +The article starts with a short introduction about the command or the +technology. Please include some helpful links or background information. + +An optional section follows. Some commands have requirements like compatible +hardware (e.g. Wifi) or some commands you have to set before. For +example, it is recommended to set a route-map before configuring BGP. + +In the configuration part of the page, all possible configuration options +should be documented. Use `.. cfgcmd::` described above. + +Related operation command must be documented in the next part of the article. +Use `::opcmd..` for these commands. + +If there some troubleshooting guides related to the commands. Explain it in the +next optional part. + +### Operation mode pages + +Operation mode commands that do not fit in a related configuration mode command +must be documented in this part of the documentation. + +General concepts for troubleshooting and detailed process descriptions belong +here. + +### Anything else + +Anything else that is not a configuration or an operation command has no +predefined structure. diff --git a/docs/md-index.md b/docs/md-index.md new file mode 100644 index 00000000..cc2067b3 --- /dev/null +++ b/docs/md-index.md @@ -0,0 +1,110 @@ +# VyOS User Guide + +<div class="grid" gutter="2"> + +3 + +<div class="grid-item-card"> + +Get / Build VyOS + +Quickly `Build<contributing/build-vyos:build vyos>` your own Image or take a look at how to `download<installation/install:download>` a free or supported version. + +</div> + +<div class="grid-item-card"> + +Install VyOS + +Read about how to install VyOS on `Bare Metal<installation/install:installation>` or in a +`Virtual Environment<installation/virtual/index:running vyos in virtual environments>` and +how to use an image with the usual `cloud<installation/cloud/index:running VyOS in Cloud Environments>` providers + +</div> + +<div class="grid-item-card"> + +Configuration and Operation + +Use the `Quickstart Guide<quick-start:Quick Start>`, to have a fast overview. Or go deeper and +set up `advanced routing<configuration/protocols/index:protocols>`, +`VRFs<configuration/vrf/index:vrf>`, or +`VPNs<configuration/vpn/index:vpn>` for example. + +</div> + +<div class="grid-item-card"> + +Automate + +Integrate VyOS in your automation Workflow with +`Ansible<vyos-ansible>`, +have your own `local scripts<command-scripting>`, or configure VyOS with the `HTTPS-API<vyosapi>`. + +</div> + +<div class="grid-item-card"> + +Examples + +Get some inspiration from the `Configuration Blueprints<configexamples/index:Configuration Blueprints>` +to build your infrastructure. + +</div> + +<div class="grid-item-card"> + +Contribute and Community + +There are many ways to contribute to the project.\ +Add missing parts or improve the `Documentation<documentation:Write Documentation>`.\ +Discuss in [Slack](https://slack.vyos.io/) or the [Forum](https://forum.vyos.io).\ +Or you can pick up a [Task](https://vyos.dev/) and fix the `code<contributing/development:development>`. + +</div> + +</div> + +<div class="toctree" hidden="" maxdepth="1"> + +introducing/about +introducing/history + +</div> + +<div class="toctree" maxdepth="2" hidden="" caption="First Steps"> + +installation/index +quick-start +cli + +</div> + +<div class="toctree" maxdepth="2" hidden="" caption="Adminguide"> + +configuration/index +operation/index +automation/index +troubleshooting/index +configexamples/index + +</div> + +<div class="toctree" maxdepth="2" hidden="" caption="Development"> + +contributing/build-vyos +contributing/development +contributing/issues-features +contributing/upstream-packages +contributing/debugging +contributing/testing + +</div> + +<div class="toctree" maxdepth="2" hidden="" caption="Misc"> + +documentation +coverage +copyright + +</div> diff --git a/docs/md-quick-start.md b/docs/md-quick-start.md new file mode 100644 index 00000000..36140bc5 --- /dev/null +++ b/docs/md-quick-start.md @@ -0,0 +1,362 @@ +# Quick Start + +This chapter will guide you on how to get up to speed quickly using your new +VyOS system. It will show you a very basic configuration example that will +provide a `nat` gateway for a device with two network interfaces +(`eth0` and `eth1`). + +## Configuration Mode + +By default, VyOS is in operational mode, and the command prompt displays +a `$`. To configure VyOS, you will need to enter configuration mode, resulting +in the command prompt displaying a `#`, as demonstrated below: + +``` none +vyos@vyos$ configure +vyos@vyos# +``` + +## Commit and Save + +After every configuration change, you need to apply the changes by using the +following command: + +``` none +commit +``` + +Once your configuration works as expected, you can save it permanently by using +the following command: + +``` none +save +``` + +## Interface Configuration + +- Your outside/WAN interface will be `eth0`. It will receive its interface + address via DHCP. +- Your internal/LAN interface will be `eth1`. It will use a static IP address + of `192.168.0.1/24`. + +After switching to `quick-start-configuration-mode` issue the following +commands: + +``` none +set interfaces ethernet eth0 address dhcp +set interfaces ethernet eth0 description 'OUTSIDE' +set interfaces ethernet eth1 address '192.168.0.1/24' +set interfaces ethernet eth1 description 'LAN' +``` + +## SSH Management + +After switching to `quick-start-configuration-mode` issue the following +commands, and your system will listen on every interface for incoming SSH +connections. You might want to check the `ssh` chapter on how to listen +on specific addresses only. + +``` none +set service ssh port '22' +``` + +## DHCP/DNS quick-start + +The following settings will configure DHCP and DNS services on +your internal/LAN network, where VyOS will act as the default gateway and +DNS server. + +- The default gateway and DNS recursor address will be `192.168.0.1/24` +- The address range `192.168.0.2/24 - 192.168.0.8/24` will be reserved for + static assignments +- DHCP clients will be assigned IP addresses within the range of + `192.168.0.9 - 192.168.0.254` and have a domain name of `internal-network` +- DHCP leases will hold for one day (86400 seconds) +- VyOS will serve as a full DNS recursor, replacing the need to utilize Google, + Cloudflare, or other public DNS servers (which is good for privacy) +- Only hosts from your internal/LAN network can use the DNS recursor + +``` none +set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 default-router '192.168.0.1' +set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 name-server '192.168.0.1' +set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 domain-name 'vyos.net' +set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 lease '86400' +set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 range 0 start '192.168.0.9' +set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 range 0 stop '192.168.0.254' + +set service dns forwarding cache-size '0' +set service dns forwarding listen-address '192.168.0.1' +set service dns forwarding allow-from '192.168.0.0/24' +``` + +## NAT + +The following settings will configure `source-nat` rules for our +internal/LAN network, allowing hosts to communicate through the outside/WAN +network via IP masquerade. + +``` none +set nat source rule 100 outbound-interface name 'eth0' +set nat source rule 100 source address '192.168.0.0/24' +set nat source rule 100 translation address masquerade +``` + +## Firewall + +A new firewall structure—which uses the `nftables` backend, rather +than `iptables`—is available on all installations starting from +VyOS `1.4-rolling-202308040557`. The firewall supports creation of distinct, +interlinked chains for each [Netfilter hook](https://wiki.nftables.org/wiki-nftables/index.php/Netfilter_hooks) +and allows for more granular control over the packet filtering process. + +The firewall begins with the base `filter` tables you define for each of the +`forward`, `input`, and `output` Netfiter hooks. Each of these tables is +populated with rules that are processed in order and can jump to other chains +for more granular filtering. + +### Configure Firewall Groups + +To make firewall configuration easier, we can create groups of interfaces, +networks, addresses, ports, and domains that describe different parts of +our network. We can then use them for filtering within our firewall rulesets, +allowing for more concise and readable configuration. + +In this case, we will create two interface groups — a `WAN` group for our +interfaces connected to the public internet and a `LAN` group for the +interfaces connected to our internal network. Additionally, we will create a +network group, `NET-INSIDE-v4`, that contains our internal subnet. + +``` none +set firewall group interface-group WAN interface eth0 +set firewall group interface-group LAN interface eth1 +set firewall group network-group NET-INSIDE-v4 network '192.168.0.0/24' +``` + +### Configure Stateful Packet Filtering + +With the new firewall structure, we have have a lot of flexibility in how we +group and order our rules, as shown by the three alternative approaches below. + +#### Option 1: Global State Policies + +Using options defined in `set firewall global-options state-policy`, state +policy rules that applies for both IPv4 and IPv6 are created. These global +state policies also applies for all traffic that passes through the router +(transit) and for traffic originated/destinated to/from the router itself, and +will be evaluated before any other rule defined in the firewall. + +Most installations would choose this option, and will contain: + +``` none +set firewall global-options state-policy established action accept +set firewall global-options state-policy related action accept +set firewall global-options state-policy invalid action drop +``` + +#### Option 2: Common/Custom Chain + +We can create a common chain for stateful connection filtering of multiple +interfaces (or multiple netfilter hooks on one interface). Those individual +chains can then jump to the common chain for stateful connection filtering, +returning to the original chain for further rule processing if no action is +taken on the packet. + +The chain we will create is called `CONN_FILTER` and has three rules: + +- A default action of `return`, which returns the packet back to the original + chain if no action is taken. +- A rule to `accept` packets from established and related connections. +- A rule to `drop` packets from invalid connections. + +``` none +set firewall ipv4 name CONN_FILTER default-action 'return' + +set firewall ipv4 name CONN_FILTER rule 10 action 'accept' +set firewall ipv4 name CONN_FILTER rule 10 state established +set firewall ipv4 name CONN_FILTER rule 10 state related + +set firewall ipv4 name CONN_FILTER rule 20 action 'drop' +set firewall ipv4 name CONN_FILTER rule 20 state invalid +``` + +Then, we can jump to the common chain from both the `forward` and `input` +hooks as the first filtering rule in the respective chains: + +``` none +set firewall ipv4 forward filter rule 10 action 'jump' +set firewall ipv4 forward filter rule 10 jump-target CONN_FILTER + +set firewall ipv4 input filter rule 10 action 'jump' +set firewall ipv4 input filter rule 10 jump-target CONN_FILTER +``` + +#### Option 3: Per-Hook Chain + +Alternatively, you can take the more traditional stateful connection +filtering approach by creating rules on each base hook's chain: + +``` none +set firewall ipv4 forward filter rule 5 action 'accept' +set firewall ipv4 forward filter rule 5 state established +set firewall ipv4 forward filter rule 5 state related +set firewall ipv4 forward filter rule 10 action 'drop' +set firewall ipv4 forward filter rule 10 state invalid + +set firewall ipv4 input filter rule 5 action 'accept' +set firewall ipv4 input filter rule 5 state established +set firewall ipv4 input filter rule 5 state related +set firewall ipv4 input filter rule 10 action 'drop' +set firewall ipv4 input filter rule 10 state invalid +``` + +### Block Incoming Traffic + +Now that we have configured stateful connection filtering to allow traffic from +established and related connections, we can block all other incoming traffic +addressed to our local network. + +Create a new chain (`OUTSIDE-IN`) which will drop all traffic that is not +explicitly allowed at some point in the chain. Then, we can jump to that chain +from the `forward` hook when traffic is coming from the `WAN` interface +group and is addressed to our local network. + +``` none +set firewall ipv4 name OUTSIDE-IN default-action 'drop' + +set firewall ipv4 forward filter rule 100 action jump +set firewall ipv4 forward filter rule 100 jump-target OUTSIDE-IN +set firewall ipv4 forward filter rule 100 inbound-interface group WAN +set firewall ipv4 forward filter rule 100 destination group network-group NET-INSIDE-v4 +``` + +We should also block all traffic destinated to the router itself that isn't +explicitly allowed at some point in the chain for the `input` hook. As +we've already configured stateful packet filtering above, we only need to +set the default action to `drop`: + +``` none +set firewall ipv4 input filter default-action 'drop' +``` + +### Allow Management Access + +We can now configure access to the router itself, allowing SSH +access from the inside/LAN network and rate limiting SSH access from the +outside/WAN network. + +First, create a new dedicated chain (`VyOS_MANAGEMENT`) for management +access, which returns to the parent chain if no action is taken. Add a rule +to accept traffic from the `LAN` interface group: + +``` none +set firewall ipv4 name VyOS_MANAGEMENT default-action 'return' +``` + +Configure a rule on the `input` hook filter to jump to the `VyOS_MANAGEMENT` +chain when new connections are addressed to port 22 (SSH) on the router itself: + +``` none +set firewall ipv4 input filter rule 20 action jump +set firewall ipv4 input filter rule 20 jump-target VyOS_MANAGEMENT +set firewall ipv4 input filter rule 20 destination port 22 +set firewall ipv4 input filter rule 20 protocol tcp +``` + +Finally, configure the `VyOS_MANAGEMENT` chain to accept connection from the +`LAN` interface group while limiting requests coming from the `WAN` +interface group to 4 per minute: + +``` none +set firewall ipv4 name VyOS_MANAGEMENT rule 15 action 'accept' +set firewall ipv4 name VyOS_MANAGEMENT rule 15 inbound-interface group 'LAN' + +set firewall ipv4 name VyOS_MANAGEMENT rule 20 action 'drop' +set firewall ipv4 name VyOS_MANAGEMENT rule 20 recent count 4 +set firewall ipv4 name VyOS_MANAGEMENT rule 20 recent time minute +set firewall ipv4 name VyOS_MANAGEMENT rule 20 state new +set firewall ipv4 name VyOS_MANAGEMENT rule 20 inbound-interface group 'WAN' + +set firewall ipv4 name VyOS_MANAGEMENT rule 21 action 'accept' +set firewall ipv4 name VyOS_MANAGEMENT rule 21 state new +set firewall ipv4 name VyOS_MANAGEMENT rule 21 inbound-interface group 'WAN' +``` + +### Allow Access to Services + +Here we're allowing the router to respond to pings. Then, we can allow access to +the DNS recursor we configured earlier, accepting traffic bound for port 53 from +all hosts on the `NET-INSIDE-v4` network: + +``` none +set firewall ipv4 input filter rule 30 action 'accept' +set firewall ipv4 input filter rule 30 icmp type-name 'echo-request' +set firewall ipv4 input filter rule 30 protocol 'icmp' +set firewall ipv4 input filter rule 30 state new + +set firewall ipv4 input filter rule 40 action 'accept' +set firewall ipv4 input filter rule 40 destination port '53' +set firewall ipv4 input filter rule 40 protocol 'tcp_udp' +set firewall ipv4 input filter rule 40 source group network-group NET-INSIDE-v4 +``` + +Finally, we can now configure access to the services running on this router, +allowing all connections coming from localhost: + +``` none +set firewall ipv4 input filter rule 50 action 'accept' +set firewall ipv4 input filter rule 50 source address 127.0.0.0/8 +``` + +Commit changes, save the configuration, and exit configuration mode: + +``` none +vyos@vyos# commit +vyos@vyos# save +Saving configuration to '/config/config.boot'... +Done +vyos@vyos# exit +vyos@vyos$ +``` + +## Hardening + +Especially if you are allowing SSH remote access from the outside/WAN +interface, there are a few additional configuration steps that should be taken. + +Replace the default `vyos` system user: + +``` none +set system login user myvyosuser authentication plaintext-password mysecurepassword +``` + +Set up `ssh_key_based_authentication`: + +``` none +set system login user myvyosuser authentication public-keys myusername@mydesktop type ssh-rsa +set system login user myvyosuser authentication public-keys myusername@mydesktop key contents_of_id_rsa.pub +``` + +Finally, try and SSH into the VyOS install as your new user. Once you have +confirmed that your new user can access your router without a password, delete +the original `vyos` user and completely disable password authentication for +`ssh`: + +``` none +delete system login user vyos +set service ssh disable-password-authentication +``` + +As above, commit your changes, save the configuration, and exit +configuration mode: + +``` none +vyos@vyos# commit +vyos@vyos# save +Saving configuration to '/config/config.boot'... +Done +vyos@vyos# exit +vyos@vyos$ +``` + +You now should have a simple yet secure and functioning router to experiment +with further. Enjoy! diff --git a/docs/operation/md-boot-options.md b/docs/operation/md-boot-options.md new file mode 100644 index 00000000..73a8f62f --- /dev/null +++ b/docs/operation/md-boot-options.md @@ -0,0 +1,56 @@ +# Boot Options + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +This function may be highly disruptive. +It may cause major service interruption, so make sure you really +need it and verify your input carefully. + +</div> + +VyOS has several kernel command line options to modify the normal boot +process. +To add an option, select the desired image in GRUB menu at load +time, press **e**, edit the first line, and press **Ctrl-x** to boot when +ready. + +<img src="/_static/images/boot-options.webp" class="align-center" style="width:80.0%" alt="image" /> + +## Specify custom config file + +Tells the system to use specified file instead of `/config/config.boot`. +If specified file does not exist or is not readable, fall back to +default config. No additional verification is performed, so make sure +you specify a valid config file. + +``` none +vyos-config=/path/to/file +``` + +To load the *factory default* config, use: + +``` none +vyos-config=/opt/vyatta/etc/config.boot.default +``` + +## Disable specific boot process steps + +These options disable some boot steps. Make sure you understand the +`boot process <boot-steps>` well before using them! + +<div class="glossary"> + +no-vyos-migrate +Do not perform config migration. + +no-vyos-firewall +Do not initialize default firewall chains, renders any firewall +configuration unusable. + +</div> diff --git a/docs/operation/md-index.md b/docs/operation/md-index.md new file mode 100644 index 00000000..eed21dcd --- /dev/null +++ b/docs/operation/md-index.md @@ -0,0 +1,10 @@ +# Operation Mode + +<div class="toctree" maxdepth="1" includehidden=""> + +information +boot-options +password-recovery +raid + +</div> diff --git a/docs/operation/md-information.md b/docs/operation/md-information.md new file mode 100644 index 00000000..c6f663a5 --- /dev/null +++ b/docs/operation/md-information.md @@ -0,0 +1,171 @@ +lastproofread +2021-07-07 + +# Information + +VyOS features a rich set of operational level commands to retrieve arbitrary +information about your running system. + +## Hardware + +### USB + +In the past serial interface have been defined as ttySx and ttyUSBx where x was +an instance number of the serial interface. It was discovered that from system +boot to system boot the mapping of USB based serial interfaces will differ, +depending which driver was loaded first by the operating system. This will +become rather painful if you not only have serial interfaces for a console +server connected but in addition also a serial backed `wwan-interface`. + +To overcome this issue and the fact that in almost 50% of all cheap USB to +serial converters there is no serial number programmed, the USB to serial +interface is now directly identified by the USB root bridge and bus it connects +to. This somehow mimics the new network interface definitions we see in recent +Linux distributions. + +For additional details you can refer to <https://vyos.dev/T2490>. + +<div class="opcmd"> + +show hardware usb + +Retrieve a tree like representation of all connected USB devices. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If a device is unplugged and re-plugged it will receive a new +Port, Dev, If identification. + +</div> + +``` none +vyos@vyos:~$ show hardware usb +/: Bus 03.Port 1: Dev 1, Class=root_hub, Driver=ehci-pci/2p, 480M + |__ Port 1: Dev 2, If 0, Class=Hub, Driver=hub/4p, 480M + |__ Port 3: Dev 4, If 0, Class=Vendor Specific Class, Driver=qcserial, 480M + |__ Port 3: Dev 4, If 2, Class=Vendor Specific Class, Driver=qcserial, 480M + |__ Port 3: Dev 4, If 3, Class=Vendor Specific Class, Driver=qcserial, 480M + |__ Port 3: Dev 4, If 8, Class=Vendor Specific Class, Driver=qmi_wwan, 480M +/: Bus 02.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/2p, 5000M +/: Bus 01.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/2p, 480M + |__ Port 1: Dev 2, If 0, Class=Vendor Specific Class, Driver=pl2303, 12M + |__ Port 2: Dev 3, If 0, Class=Hub, Driver=hub/4p, 480M + |__ Port 4: Dev 5, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 5, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 5, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 5, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 3: Dev 4, If 0, Class=Hub, Driver=hub/4p, 480M + |__ Port 3: Dev 6, If 0, Class=Hub, Driver=hub/4p, 480M + |__ Port 4: Dev 8, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 8, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 8, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 8, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 7, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 7, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 7, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 7, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M +``` + +</div> + +<div class="opcmd"> + +show hardware usb serial + +Retrieve a list and description of all connected USB serial devices. The +device name displayed, e.g. <span class="title-ref">usb0b2.4p1.0</span> can be directly used when accessing +the serial console as console-server device. + +``` none +vyos@vyos$ show hardware usb serial +Device Model Vendor +------ ------ ------ +usb0b1.3p1.0 MC7710 Sierra Wireless, Inc. +usb0b1.3p1.2 MC7710 Sierra Wireless, Inc. +usb0b1.3p1.3 MC7710 Sierra Wireless, Inc. +usb0b1p1.0 USB-Serial_Controller_D Prolific Technology, Inc. +usb0b2.3.3.4p1.0 Quad_RS232-HS Future Technology Devices International, Ltd +usb0b2.3.3.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd +usb0b2.3.3.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd +usb0b2.3.3.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd +usb0b2.3.4p1.0 Quad_RS232-HS Future Technology Devices International, Ltd +usb0b2.3.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd +usb0b2.3.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd +usb0b2.3.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd +usb0b2.4p1.0 Quad_RS232-HS Future Technology Devices International, Ltd +usb0b2.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd +usb0b2.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd +usb0b2.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd +``` + +</div> + +## Version + +<div class="opcmd"> + +show version + +Return the current running VyOS version and build information. This includes +also the name of the release train which is `crux` on VyOS 1.2, `equuleus` +on VyOS 1.3 and `sagitta` on VyOS 1.4. + +``` none +vyos@vyos:~$ show version + +Version: VyOS 1.4-rolling-202106270801 +Release Train: sagitta + +Built by: autobuild@vyos.net +Built on: Sun 27 Jun 2021 09:50 UTC +Build UUID: ab43e735-edcb-405a-9f51-f16a1b104e52 +Build Commit ID: f544d75eab758f + +Architecture: x86_64 +Boot via: installed image +System type: KVM guest + +Hardware vendor: QEMU +Hardware model: Standard PC (i440FX + PIIX, 1996) +Hardware S/N: +Hardware UUID: Unknown + +Copyright: VyOS maintainers and contributors +``` + +</div> + +<div class="opcmd"> + +show version kernel + +Return version number of the Linux Kernel used in this release. + +``` none +vyos@vyos:~$ show version kernel +5.10.46-amd64-vyos +``` + +</div> + +<div class="opcmd"> + +show version frr + +Return version number of FRR (Free Range Routing - <https://frrouting.org/>) +used in this release. This is the routing control plane and a successor to GNU +Zebra and Quagga. + +> ``` none +> vyos@vyos:~$ show version frr +> FRRouting 7.5.1-20210625-00-gf07d935a2 (vyos). +> Copyright 1996-2005 Kunihiro Ishiguro, et al. +> ``` + +</div> diff --git a/docs/operation/md-password-recovery.md b/docs/operation/md-password-recovery.md new file mode 100644 index 00000000..295de05c --- /dev/null +++ b/docs/operation/md-password-recovery.md @@ -0,0 +1,22 @@ +# Password Recovery + +Using the console, restart the VyOS router. The GRUB menu appears. +Select the relevant option from the GRUB menu and press Enter. +The option must start with “Lost password change.” + +<figure> +<img src="/_static/images/password-recovery-01.webp" width="600" /> +</figure> + +The stand-alone user-password recovery tool starts running and prompts +you to reset the local system user password. + +``` console +Do you wish to reset the admin password? (y or n) +y +Which admin account do you want to reset?[vyos] +my_username +Enter my_username password: +Retype my_username password: +System will reboot in 10 seconds... +``` diff --git a/docs/operation/md-raid.md b/docs/operation/md-raid.md new file mode 100644 index 00000000..2009779d --- /dev/null +++ b/docs/operation/md-raid.md @@ -0,0 +1,265 @@ +# RAID-1 + +A Redundant Array of Independent Disks (RAID) uses two or more hard disk drives +to improve disk speed, store more data, and/or provide fault tolerance. +There are several storage schemes possible in a RAID array, each offering a +different combination of storage, reliability, and/or performance. +The VyOS system supports a “RAID 1” deployment. RAID 1 allows two or more +disks to mirror one another to provide system fault tolerance. In a RAID 1 +solution, every sector of one disk is duplicated onto every sector of all +disks in the array. Provided even one disk in the RAID 1 set is operational, +the system continues to run, even through disk replacement (provided that the +hardware supports in-service replacement of drives). +RAID 1 can be implemented using special hardware or it can be implemented in +software. The VyOS system supports software RAID 1 on two disks. +The VyOS implementation of RAID 1 allows the following: + +- Detection and reporting of disk failure +- The ability to maintain system operation with one failed disk +- The ability to boot the system with one failed disk +- The ability to replace a failed disk and initiate re-mirroring +- The ability to monitor the status of remirroring + +## Installation Implications + +The VyOS systems installation utility provides several options for installing +to a RAID 1 set. You can: + +- Use the install system to create the RAID 1 set +- Use the underlying Linux commands to create a RAID 1 set before running the + install system command. +- Use a previously-created RAID 1 set. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Before a permanent installation, VyOS runs a live installation + +</div> + +## Configuration + +### Single disk, install as normal + +When the VyOS system is installed, it automatically detects the presence of two +disks not currently part of a RAID array. In these cases, the VyOS +installation utility automatically offers you the option of configuring RAID 1 +mirroring for the drives, with the following prompt. + +``` none +Would you like to configure RAID 1 mirroring on them? +``` + +- If you do not want to configure RAID 1 mirroring, enter “No” at the prompt + and continue with installation in the normal way. + +### Empty 2+ Disk + +If VyOS system detect two identical disks that are not currently part of a +RAID-1 set, the VyOS installation utility automatically offers you the option +of configuring RAID 1 mirroring for the drives, with the following prompt. + +``` none +Would you like to configure RAID 1 mirroring on them? +``` + +1 - To create a new RAID 1 array, enter “Yes” at the prompt. If the system +detects a filesystem on the partitions being used for RAID 1 it will prompt you +to indicate whether you want to continue creating the RAID 1 array. + +``` none +Continue creating array? +``` + +2 - To overwrite the old filesystem, enter “Yes”. + +3 - The system informs you that all data on both drives will be erased. You are +prompted to confirm that you want to continue + +``` none +Are you sure you want to do this? +``` + +4 - Enter “Yes” at the prompt to retain the current VyOS configuration once +installation is complete. Enter “No” to delete the current VyOS +configuration. + +``` none +Would you like me to save the data on it before I delete it? +``` + +5 - Enter “Yes” at the prompt to retain the current VyOS configuration once +installation is complete. Enter “No” to delete the current VyOS configuration. + +6 - Continue with installation in the normal way. + +### Present RAID-1 + +When the VyOS software on a system with a RAID 1 set already configured, +the installation utility will detect the array and will display the following +prompt: + +``` none +Would you like to use this one? +``` + +1 - To break apart the current RAID 1 set, enter “No” at the prompt. The + +installation utility detects that there are two identical disks and offers you +the option of configuring RAID 1 mirroring on them, displaying the following +prompt: + +``` none +Would you like to configure RAID 1 mirroring on them? +``` + +2 - To decline to set up a new RAID 1 configuration on the disks, enter “No” +at the prompt. The system prompts you to indicate which partition you would +like the system installed on. + +``` none +Which partition should I install the root on? [sda1]: +``` + +3 - Enter the partition where you would like the system installed. The system +then prompts you to indicate whether you want to save the old configuration +data. This represents the current VyOS configuration. + +``` none +Would you like me to save the data on it before I delete it? +``` + +4 - Enter “Yes” at the prompt to retain the current VyOS configuration once +installation is complete. Enter “No” to delete the current VyOS configuration. + +5 - Continue with installation in the normal way. + +### Detecting and Replacing a Failed RAID 1 Disk + +The VyOS system automatically detects a disk failure within a RAID 1 set and +reports it to the system console. You can verify the failure by issuing the +show raid command. + +To replace a bad disk within a RAID 1 set, perform the following steps: + +1 - Remove the failed disk from the RAID 1 set by issuing the following +command: + +<div class="opcmd"> + +delete raid \<RAID‐1‐device\> member \<disk‐partition\> + +where RAID-1-device is the name of the RAID 1 device (for example, md0) and +disk-partition is the name of the failed disk partition (for example, sdb2). + +</div> + +2- Physically remove the failed disk from the system. If the drives are not +hot-swappable, then you must shut down the system before removing the disk. + +3 - Replace the failed drive with a drive of the same size or larger. + +4 - Format the new disk for RAID 1 by issuing the following command: + +<div class="opcmd"> + +format disk \<disk‐device1\> like \<disk‐device2\> + +where disk-device1 is the replacement disk (for example, sdb) and +disk-device2 is the existing healthy disk (for example, sda). + +</div> + +5-Add the replacement disk to the RAID 1 set by issuing the following command: + +<div class="opcmd"> + +add raid \<RAID‐1‐device\> member \<disk‐partition\> + +where RAID-1-device is the name of the RAID 1 device (for example, md0) and +disk-partition is the name of the replacement disk partition +(for example, sdb2). + +</div> + +## Operation + +This part introduces how to add a disk partition to a RAID-1 set initiates +mirror synchronization, check and display information. + +<div class="opcmd"> + +add raid \<RAID‐1‐device\> member \<disk‐partition\> + +Use this command to add a member disk partition to the RAID 1 set. Adding a +disk partition to a RAID 1 set initiates mirror synchronization, where all +data on the existing member partition is copied to the new partition. + +</div> + +<div class="opcmd"> + +format disk \<disk‐device1\> like \<disk‐device2\> + +This command is typically used to prepare a disk to be added to a preexisting +RAID 1 set (of which disk-device2 is already a member). + +</div> + +<div class="opcmd"> + +show raid \<RAID‐1‐device\> + +shows output for show raid md0 as sdb1 is being added to the RAID 1 +set and is in the process of being resynchronized. + +``` none +vyos@vyos:~$ show raid md0 +/dev/md0: + Version : 00.90 +Creation Time : Wed Oct 29 09:19:09 2008 + Raid Level : raid1 + Array Size : 1044800 (1020.48 MiB 1069.88 MB) +Used Dev Size : 1044800 (1020.48 MiB 1069.88 MB) + Raid Devices : 2 +Total Devices : 2 +Preferred Minor : 0 + Persistence : Superblock is persistent + Update Time : Wed Oct 29 19:34:23 2008 + State : active, degraded, recovering +Active Devices : 1 +Working Devices : 2 +Failed Devices : 0 +Spare Devices : 1 +Rebuild Status : 17% complete + UUID : 981abd77:9f8c8dd8:fdbf4de4:3436c70f + Events : 0.103 + Number Major Minor RaidDevice State + 0 8 1 0 active sync /dev/sda1 + 2 8 17 1 spare rebuilding /dev/sdb1 +``` + +</div> + +<div class="opcmd"> + +show raid \<RAID‐1‐device\> + +Use this command to display the formatting of a hard disk. + +``` none +vyos@vyos:~$ show disk sda format +Disk /dev/sda: 1073 MB, 1073741824 bytes +85 heads, 9 sectors/track, 2741 cylinders +Units = cylinders of 765 * 512 = 391680 bytes +Disk identifier: 0x000b7179 + Device Boot Start End Blocks Id System +/dev/sda1 6 2737 1044922+ fd Linux raid autodetect +``` + +</div> diff --git a/docs/troubleshooting/md-index.md b/docs/troubleshooting/md-index.md new file mode 100644 index 00000000..f3756c26 --- /dev/null +++ b/docs/troubleshooting/md-index.md @@ -0,0 +1,436 @@ +# Troubleshooting + +Sometimes things break or don't work as expected. This section describes +several troubleshooting tools provided by VyOS that can help when something +goes wrong. + +## Connectivity Tests + +### Basic Connectivity Tests + +Verifying connectivity can be done with the familiar <span class="title-ref">ping</span> and <span class="title-ref">traceroute</span> +commands. The options for each are shown (the options for each command were +displayed using the built-in help as described in the `cli` +section and are omitted from the output here): + +<div class="opcmd"> + +ping \<destination\> + +Send ICMP echo requests to destination host. There are multiple options to +ping, inkl. VRF support. + +``` none +vyos@vyos:~$ ping 10.1.1.1 +Possible completions: + <Enter> Execute the current command + adaptive Ping options + allow-broadcast + audible + bypass-route + count + deadline + do-not-fragment + flood + interface + interval + mark + no-loopback + numeric + pattern + quiet + record-route + size + timestamp + tos + ttl + verbose + vrf +``` + +</div> + +<div class="opcmd"> + +traceroute \<destination\> + +Trace path to target. + +``` none +vyos@vyos:~$ traceroute +Possible completions: + <hostname> Track network path to specified node + <x.x.x.x> + <h:h:h:h:h:h:h:h> + ipv4 Track network path to <hostname|IPv4 address> + ipv6 Track network path to <hostname|IPv6 address> +``` + +</div> + +### Advanced Connectivity Tests + +<div class="opcmd"> + +monitor traceroute \<destination\> + +However, another helper is available which combines ping and traceroute +into a single tool. An example of its output is shown: + +``` none +vyos@vyos:~$ mtr 10.62.212.12 + + My traceroute [v0.85] +vyos (0.0.0.0) +Keys: Help Display mode Restart statistics Order of fields quit + Packets Pings +Host Loss% Snt Last Avg Best Wrst StDev +1. 10.11.110.4 0.0% 34 0.5 0.5 0.4 0.8 0.1 +2. 10.62.255.184 0.0% 34 1.1 1.0 0.9 1.4 0.1 +3. 10.62.255.71 0.0% 34 1.4 1.4 1.3 2.0 0.1 +4. 10.62.212.12 0.0% 34 1.6 1.6 1.6 1.7 0.0 +``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +The output consumes the screen and will replace your command +prompt. + +</div> + +Several options are available for changing the display output. Press <span class="title-ref">h</span> to +invoke the built in help system. To quit, just press <span class="title-ref">q</span> and you'll be +returned to the VyOS command prompt. + +</div> + +### IPv6 Topology Discovery + +IPv6 uses different techniques to discover its Neighbors/topology. + +#### Router Discovery + +<div class="opcmd"> + +force ipv6-rd interface \<interface\> \[address \<ipv6-address\>\] + +Discover routers via eth0. + +Example: + +``` none +vyos@vyos:~$ force ipv6-rd interface eth0 +Soliciting ff02::2 (ff02::2) on eth0... + +Hop limit : 60 ( 0x3c) +Stateful address conf. : No +Stateful other conf. : No +Mobile home agent : No +Router preference : high +Neighbor discovery proxy : No +Router lifetime : 1800 (0x00000708) seconds +Reachable time : unspecified (0x00000000) +Retransmit time : unspecified (0x00000000) + Prefix : 240e:fe:8ca7:ea01::/64 + On-link : Yes + Autonomous address conf.: Yes + Valid time : 2592000 (0x00278d00) seconds + Pref. time : 14400 (0x00003840) seconds + Prefix : fc00:470:f1cd:101::/64 + On-link : Yes + Autonomous address conf.: Yes + Valid time : 2592000 (0x00278d00) seconds + Pref. time : 14400 (0x00003840) seconds + Recursive DNS server : fc00:470:f1cd::ff00 + DNS server lifetime : 600 (0x00000258) seconds + Source link-layer address: 00:98:2B:F8:3F:11 + from fe80::298:2bff:fef8:3f11 +``` + +</div> + +#### Neighbor Discovery + +<div class="opcmd"> + +force ipv6-nd interface \<interface\> address \<ipv6-address\> + +Example: + +``` none +vyos@vyos:~$ force ipv6-nd interface eth0 address fc00:470:f1cd:101::1 + +Soliciting fc00:470:f1cd:101::1 (fc00:470:f1cd:101::1) on eth0... +Target link-layer address: 00:98:2B:F8:3F:11 from fc00:470:f1cd:101::1 +``` + +</div> + +## Interface names + +If you find the names of your interfaces have changed, this could be because +your MAC addresses have changed. + +- For example, you have a VyOS VM with 4 Ethernet interfaces named + eth0, eth1, eth2 and eth3. Then, you migrate your VyOS VM to a different + host and find your interfaces now are eth4, eth5, eth6 and eth7. + + One way to fix this issue **taking control of the MAC addresses** is: + + Log into VyOS and run this command to display your interface settings. + + ``` none + show interfaces detail + ``` + + Take note of MAC addresses. + + Now, in order to update a MAC address in the configuration, run this command + specifying the interface name and MAC address you want. + + ``` none + set interfaces eth0 hw-id 00:0c:29:da:a4:fe + ``` + + If it is a VM, go into the settings of the host and set the MAC address to + the settings found in the config.boot file. You can also set the MAC to + static if the host allows so. + +- Another example could be when cloning VyOS VMs in GNS3 and you get into the + same issue: interface names have changed. + + And **a more generic way to fix it** is just deleting every MAC address at + the configuration file of the cloned machine. They will be correctly + regenerated automatically. + +## Monitoring + +VyOS features several monitoring tools. + +``` none +vyos@vyos:~$ monitor +Possible completions: + bandwidth Monitor interface bandwidth in real time + bandwidth-test + Initiate or wait for bandwidth test + cluster Monitor clustering service + command Monitor an operational mode command (refreshes every 2 seconds) + conntrack-sync + Monitor conntrack-sync + content-inspection + Monitor Content-Inspection + dhcp Monitor Dynamic Host Control Protocol (DHCP) + dns Monitor a Domain Name Service (DNS) daemon + firewall Monitor Firewall + https Monitor the Secure Hypertext Transfer Protocol (HTTPS) service + lldp Monitor Link Layer Discovery Protocol (LLDP) daemon + log Monitor last lines of messages file + nat Monitor network address translation (NAT) + ndp Monitor the NDP information received by the router through the device + openvpn Monitor OpenVPN + protocol Monitor routing protocols + snmp Monitor Simple Network Management Protocol (SNMP) daemon + stop-all Stop all current background monitoring processes + traceroute Monitor the path to a destination in realtime + traffic Monitor traffic dumps + vpn Monitor VPN + vrrp Monitor Virtual Router Redundancy Protocol (VRRP) + webproxy Monitor Webproxy service +``` + +### Traffic Dumps + +To monitor interface traffic, issue the `monitor traffic interface <name>` +command, replacing <span class="title-ref">\<name\></span> with your chosen interface. + +``` none +vyos@vyos:~$ monitor traffic interface eth0 +tcpdump: verbose output suppressed, use -v or -vv for full protocol decode +listening on eth0, link-type EN10MB (Ethernet), capture size 262144 bytes +15:54:28.581601 IP 192.168.0.1 > vyos: ICMP echo request, id 1870, seq 3848, length 64 +15:54:28.581660 IP vyos > 192.168.0.1: ICMP echo reply, id 1870, seq 3848, length 64 +15:54:29.583399 IP 192.168.0.1 > vyos: ICMP echo request, id 1870, seq 3849, length 64 +15:54:29.583454 IP vyos > 192.168.0.1: ICMP echo reply, id 1870, seq 3849, length 64 +^C +4 packets captured +4 packets received by filter +0 packets dropped by kernel +vyos@vyos:~$ +``` + +To quit monitoring, press <span class="title-ref">Ctrl-c</span> and you'll be returned to the VyOS command +prompt. + +Traffic can be filtered and saved. + +``` none +vyos@vyos:~$ monitor traffic interface eth0 +Possible completions: + <Enter> Execute the current command + filter Monitor traffic matching filter conditions + save Save traffic dump from an interface to a file +``` + +### Interface Bandwidth Usage + +to take a quick view on the used bandwidth of an interface use the `monitor bandwidth` command + +``` none +vyos@vyos:~$ monitor bandwidth interface eth0 +``` + +show the following: + +``` none +B (RX Bytes/second) +198.00 .|....|..................................................... +165.00 .|....|..................................................... +132.00 ||..|.|..................................................... +99.00 ||..|.|..................................................... +66.00 |||||||..................................................... +33.00 |||||||..................................................... + 1 5 10 15 20 25 30 35 40 45 50 55 60 + +KiB (TX Bytes/second) +3.67 ......|..................................................... +3.06 ......|..................................................... +2.45 ......|..................................................... +1.84 ......|..................................................... +1.22 ......|..................................................... +0.61 :::::||..................................................... + 1 5 10 15 20 25 30 35 40 45 50 55 60 +``` + +### Interface Performance + +To take a look on the network bandwidth between two nodes, the `monitor bandwidth-test` command is used to run iperf. + +``` none +vyos@vyos:~$ monitor bandwidth-test +Possible completions: + accept Wait for bandwidth test connections (port TCP/5001) + initiate Initiate a bandwidth test +``` + +- The `accept` command opens a listening iperf server on TCP Port 5001 +- The `initiate` command connects to that server to perform the test. + +``` none +vyos@vyos:~$ monitor bandwidth-test initiate +Possible completions: + <hostname> Initiate a bandwidth test to specified host (port TCP/5001) + <x.x.x.x> + <h:h:h:h:h:h:h:h> +``` + +### Monitor command + +The `monitor command` command allows you to repeatedly run a command to view +a continuously refreshed output. The command is run and output every 2 seconds, +allowing you to monitor the output continuously without having to re-run the +command. This can be useful to follow routing adjacency formation. + +``` none +vyos@router:~$ monitor command "show interfaces" +``` + +Will clear the screen and show you the output of `show interfaces` every +2 seconds. + +``` none +Every 2.0s: /opt/vyatta/bin/vyatta-op-cmd-wrapper Sun Mar 26 02:49:46 2019 + +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +eth0 192.168.1.1/24 u/u +eth0.5 198.51.100.4/24 u/u WAN +lo 127.0.0.1/8 u/u + ::1/128 +vti0 172.25.254.2/30 u/u +vti1 172.25.254.9/30 u/u +``` + +## Terminal/Console + +Sometimes you need to clear counters or statistics to troubleshoot better. + +To do this use the `clear` command in Operational mode. + +to clear the console output + +``` none +vyos@vyos:~$ clear console +``` + +to clear interface counters + +``` none +# clear all interfaces +vyos@vyos:~$ clear interface ethernet counters +# clear specific interface +vyos@vyos:~$ clear interface ethernet eth0 counters +``` + +The command follow the same logic as the `set` command in configuration mode. + +``` none +# clear all counters of a interface type +vyos@vyos:~$ clear interface <interface_type> counters +# clear counter of a interface in interface_type +vyos@vyos:~$ clear interface <interface_type> <interace_name> counters +``` + +to clear counters on firewall rulesets or single rules + +``` none +vyos@vyos:~$ clear firewall name <ipv4 ruleset name> counters +vyos@vyos:~$ clear firewall name <ipv4 ruleset name> rule <rule#> counters + +vyos@vyos:~$ clear firewall ipv6-name <ipv6 ruleset name> counters +vyos@vyos:~$ clear firewall ipv6-name <ipv6 ruleset name> rule <rule#> counters +``` + +## System Information + +### Boot Steps + +VyOS 1.2 uses [Debian Jessie](https://www.debian.org/releases/jessie/) as the base Linux operating system. Jessie was +the first version of Debian that uses [systemd](https://freedesktop.org/wiki/Software/systemd/) as the default init system. + +These are the boot steps for VyOS 1.2 + +1. The BIOS loads Grub (or isolinux for the Live CD) +2. Grub then starts the Linux boot and loads the Linux Kernel `/boot/vmlinuz` +3. Kernel Launches Systemd `/lib/systemd/systemd` +4. Systemd loads the VyOS service file + `/lib/systemd/system/vyos-router.service` +5. The service file launches the VyOS router init script + `/usr/libexec/vyos/init/vyos-router` - this is part of the [vyatta-cfg](https://github.com/vyos/vyatta-cfg) + Debian package + +> 1. Starts [FRR](https://frrouting.org/) - successor to [GNU Zebra](https://www.gnu.org/software/zebra/) and [Quagga](https://www.quagga.net/) +> 2. Initialises the boot configuration file - copies over +> `config.boot.default` if there is no configuration +> 3. Runs the configuration migration, if the configuration is for an older +> version of VyOS +> 4. Runs The pre-config script, if there is one +> `/config/scripts/vyos-preconfig-bootup.script` +> 5. If the config file was upgraded, runs any post upgrade scripts +> `/config/scripts/post-upgrade.d` +> 6. Starts `rl-system` and `firewall` +> 7. Mounts the `/boot` partition +> 8. The boot configuration file is then applied by `/opt/vyatta/sbin/ vyatta-boot-config-loader/opt/vyatta/etc/config/config.boot` +> +> > 1. The config loader script writes log entries to +> > `/var/log/vyatta-config-loader.log` +> +> 9. Runs `telinit q` to tell the init system to reload `/etc/inittab` +> 10. Finally it runs the post-config script +> `/config/scripts/vyos-postconfig-bootup.script` diff --git a/scripts/import_myst.py b/scripts/import_myst.py new file mode 100644 index 00000000..b9dd7898 --- /dev/null +++ b/scripts/import_myst.py @@ -0,0 +1,270 @@ +#!/usr/bin/env python3 +"""import_myst.py — Import converted MD files from myst/* branches. + +Usage +----- + python scripts/import_myst.py --source myst/current --all + python scripts/import_myst.py --source myst/current --pages quick-start configuration/firewall/zone + python scripts/import_myst.py --source myst/current --all --force + python scripts/import_myst.py --source myst/current --all --dry-run + +Each imported file is written as md-{name}.md alongside the existing RST +file. Importing does not activate a page — use swap_sources.py for that. +""" + +import argparse +import subprocess +import sys +import warnings +from pathlib import Path +from typing import Optional + + +# --------------------------------------------------------------------------- +# Constants +# --------------------------------------------------------------------------- + +REPO_ROOT = Path(__file__).resolve().parent.parent +DOCS_DIR = REPO_ROOT / "docs" + + +# --------------------------------------------------------------------------- +# Core helpers +# --------------------------------------------------------------------------- + +def git_show(ref: str, path: str) -> Optional[bytes]: + """Run `git show {ref}:{path}` and return raw bytes, or None on error.""" + result = subprocess.run( + ["git", "show", f"{ref}:{path}"], + capture_output=True, + cwd=REPO_ROOT, + ) + if result.returncode != 0: + return None + return result.stdout + + +def list_myst_files(source: str) -> list[str]: + """Return list of MD stems from `git ls-tree -r --name-only {source} -- docs/`. + + Stems are relative to docs/ with the .md extension stripped. + Only .md files are returned. + """ + result = subprocess.run( + ["git", "ls-tree", "-r", "--name-only", source, "--", "docs/"], + capture_output=True, + text=True, + cwd=REPO_ROOT, + ) + if result.returncode != 0: + raise SystemExit( + f"import_myst: git ls-tree {source!r} failed " + f"(exit {result.returncode}): {result.stderr.strip()}" + ) + + stems = [] + for line in result.stdout.splitlines(): + line = line.strip() + if not line.endswith(".md"): + continue + # Strip leading "docs/" prefix and .md extension + rel = line[len("docs/"):] if line.startswith("docs/") else line + stem = rel[:-3] # strip ".md" + stems.append(stem) + return stems + + +def list_rst_files(docs_dir: Path) -> set[str]: + """Return set of stems (relative to docs_dir, no extension) for all *.rst files.""" + build_dir = (docs_dir / "_build").resolve() + stems = set() + for rst in docs_dir.rglob("*.rst"): + try: + rst.resolve().relative_to(build_dir) + continue # inside _build/, skip + except ValueError: + pass + rel = rst.relative_to(docs_dir) + stem = str(rel)[:-4] # strip ".rst" + stems.add(stem) + return stems + + +def import_page(stem: str, md_content: bytes, docs_dir: Path, force: bool) -> bool: + """Write md-{name}.md for the given stem. + + - Creates parent dirs as needed. + - Skips (returns False) if identical content already exists. + - Without --force: warns and skips (returns False) if different content exists. + - With --force: overwrites (returns True). + - Returns True on successful write. + + Refuses (raises ValueError) if *stem* would resolve outside *docs_dir*. + """ + p = Path(stem) + if p.is_absolute() or ".." in p.parts: + raise ValueError(f"import_myst: refusing unsafe stem {stem!r}") + name = p.name + parent = p.parent + if str(parent) == ".": + target_dir = docs_dir + else: + target_dir = docs_dir / parent + + dest = target_dir / f"md-{name}.md" + docs_root = docs_dir.resolve() + if not dest.resolve().parent.is_relative_to(docs_root): + raise ValueError(f"import_myst: refusing stem {stem!r} — escapes docs/") + + if dest.exists(): + existing = dest.read_bytes() + if existing == md_content: + return False # identical — skip silently + if not force: + warnings.warn( + f"import_myst: {dest} exists with different content; " + f"use --force to overwrite", + stacklevel=2, + ) + return False + # force=True — fall through to write + + target_dir.mkdir(parents=True, exist_ok=True) + dest.write_bytes(md_content) + return True + + +# --------------------------------------------------------------------------- +# do_import +# --------------------------------------------------------------------------- + +def do_import( + source: str, + pages: Optional[list], + all_pages: bool, + force: bool, + dry_run: bool, + docs_dir: Path, +) -> None: + """Orchestrate import from source branch. + + If --all: list MD files from source, intersect with RST stems in docs_dir, + import only those that have an RST counterpart. + If --pages: import only the listed stems. + """ + docs_dir = Path(docs_dir) + + if all_pages: + myst_stems = list_myst_files(source) + rst_stems = list_rst_files(docs_dir) + candidate_stems = [s for s in myst_stems if s in rst_stems] + else: + candidate_stems = list(pages or []) + + imported = 0 + skipped = 0 + would_import = 0 + + for stem in candidate_stems: + # Path inside the branch: docs/{stem}.md + ref_path = f"docs/{stem}.md" + content = git_show(source, ref_path) + if content is None: + print( + f"import_myst: WARNING — could not fetch {source}:{ref_path}", + file=sys.stderr, + ) + skipped += 1 + continue + + if dry_run: + print(f" (dry-run) would import {stem}") + would_import += 1 + continue + + wrote = import_page(stem, content, docs_dir, force) + if wrote: + imported += 1 + else: + skipped += 1 + + if dry_run: + print( + f"import_myst: (dry-run) would import {would_import}, " + f"skipped {skipped}.", + file=sys.stderr, + ) + else: + print( + f"import_myst: imported {imported}, skipped {skipped}.", + file=sys.stderr, + ) + + +# --------------------------------------------------------------------------- +# CLI +# --------------------------------------------------------------------------- + +def main(argv=None): + parser = argparse.ArgumentParser( + description="Import MyST MD files from a myst/* branch with md- prefix." + ) + parser.add_argument( + "--source", + required=True, + help="Git ref to import from (e.g. myst/current)", + ) + + pages_group = parser.add_mutually_exclusive_group(required=True) + pages_group.add_argument( + "--pages", + nargs="+", + metavar="STEM", + help="Specific page stems to import (e.g. quick-start configuration/firewall/zone)", + ) + pages_group.add_argument( + "--all", + action="store_true", + dest="all_pages", + help="Import all MD files that have a matching RST counterpart", + ) + + parser.add_argument( + "--force", + action="store_true", + help="Overwrite existing md- files even if content differs", + ) + parser.add_argument( + "--dry-run", + action="store_true", + help="Print what would be imported without writing files", + ) + parser.add_argument( + "--docs-dir", + type=Path, + default=None, + help="Path to docs/ directory (default: auto-detected from script location)", + ) + + args = parser.parse_args(argv) + + if args.docs_dir is None: + docs_dir = DOCS_DIR + else: + docs_dir = args.docs_dir.resolve() + + if not docs_dir.is_dir(): + parser.error(f"docs directory not found: {docs_dir}") + + do_import( + source=args.source, + pages=args.pages, + all_pages=args.all_pages, + force=args.force, + dry_run=args.dry_run, + docs_dir=docs_dir, + ) + + +if __name__ == "__main__": + main() diff --git a/scripts/swap_sources.py b/scripts/swap_sources.py new file mode 100644 index 00000000..683d5ef9 --- /dev/null +++ b/scripts/swap_sources.py @@ -0,0 +1,327 @@ +#!/usr/bin/env python3 +"""swap_sources.py — Pre-build swap/restore for incremental RST-to-MyST migration. + +Usage +----- + python scripts/swap_sources.py --swap # rename md-{name}.md → {name}.md + python scripts/swap_sources.py --restore # undo renames + python scripts/swap_sources.py --dry-run # show what would be swapped + python scripts/swap_sources.py --status # show current swap state + python scripts/swap_sources.py --swap --docs-dir /path/to/docs + +Swap list +--------- + docs/_swap.txt — one stem per line, relative to docs/, comments (#) skipped. + Example: + # migrated pages + configuration/firewall/zone + quick-start + +State files (in docs/_build/, gitignored) +----------------------------------------- + _swap_state.json — records completed renames + _swap_exclude.txt — RST paths to pass to Sphinx exclude_patterns +""" + +import argparse +import json +import os +import sys +from pathlib import Path + + +# --------------------------------------------------------------------------- +# Constants +# --------------------------------------------------------------------------- + +STATE_FILE = "_swap_state.json" +EXCLUDE_FILE = "_swap_exclude.txt" +SWAP_LIST_FILE = "_swap.txt" +STATE_VERSION = 1 + + +# --------------------------------------------------------------------------- +# Core helpers +# --------------------------------------------------------------------------- + +def parse_swap_list(path: Path) -> list: + """Read *path* and return a list of stems (comments/blanks skipped). + + Returns [] if the file does not exist. + """ + if not path.exists(): + return [] + stems = [] + for line in path.read_text(encoding="utf-8").splitlines(): + stripped = line.strip() + if stripped and not stripped.startswith("#"): + stems.append(stripped) + return stems + + +def _build_dir(docs_dir: Path) -> Path: + build = docs_dir / "_build" + build.mkdir(parents=True, exist_ok=True) + return build + + +def _state_path(docs_dir: Path) -> Path: + return docs_dir / "_build" / STATE_FILE + + +def _exclude_path(docs_dir: Path) -> Path: + return docs_dir / "_build" / EXCLUDE_FILE + + +def _resolve_stem_paths(docs_dir: Path, stem: str): + """Return (md_from, md_to, rst_path) as absolute Paths for a given stem.""" + p = Path(stem) + name = p.name + parent = p.parent # may be PosixPath('.') + if str(parent) == ".": + target_dir = docs_dir + else: + target_dir = docs_dir / parent + + md_from = target_dir / f"md-{name}.md" # source: md-prefixed + md_to = target_dir / f"{name}.md" # destination: plain .md + rst_path = target_dir / f"{name}.rst" # RST that will be excluded + return md_from, md_to, rst_path + + +# --------------------------------------------------------------------------- +# do_swap +# --------------------------------------------------------------------------- + +def do_swap(docs_dir: Path) -> None: + """Rename md-{name}.md → {name}.md for each stem in _swap.txt. + + Validates collisions, records state, writes exclude file. + Rolls back all completed renames on any failure. + """ + docs_dir = Path(docs_dir) + swap_list = parse_swap_list(docs_dir / SWAP_LIST_FILE) + if not swap_list: + print("swap_sources: no stems in swap list, nothing to do.", file=sys.stderr) + return + + # Stale state: warn and auto-restore first + state_path = _state_path(docs_dir) + if state_path.exists(): + print( + "swap_sources: WARNING — stale swap state detected. Auto-restoring before new swap.", + file=sys.stderr, + ) + do_restore(docs_dir) + + # Validate all stems before touching the filesystem + planned = [] # list of (md_from, md_to, rst_path, stem) + for stem in swap_list: + md_from, md_to, rst_path = _resolve_stem_paths(docs_dir, stem) + + if not md_from.exists(): + print( + f"swap_sources: skipping {stem!r} — md- source file not found: {md_from}", + file=sys.stderr, + ) + continue + + if not rst_path.exists(): + print( + f"swap_sources: skipping {stem!r} — RST file not found: {rst_path}", + file=sys.stderr, + ) + continue + + if md_to.exists(): + raise RuntimeError( + f"collision: both RST and unprefixed .md exist for stem {stem!r}. " + f"Remove {md_to} before swapping." + ) + + planned.append((md_from, md_to, rst_path, stem)) + + # Execute renames with rollback on failure + completed = [] # list of (md_from, md_to) that succeeded + try: + for md_from, md_to, rst_path, stem in planned: + os.rename(md_from, md_to) + completed.append((md_from, md_to)) + except Exception as exc: + # Rollback completed renames in reverse order + for from_path, to_path in reversed(completed): + try: + os.rename(to_path, from_path) + except Exception as rollback_exc: + print( + f"swap_sources: ROLLBACK ERROR for {to_path}: {rollback_exc}", + file=sys.stderr, + ) + raise RuntimeError(f"swap_sources: rename failed, rolled back. Cause: {exc}") from exc + + if not completed: + return + + # Build state and exclude data using relative paths (relative to docs_dir) + _build_dir(docs_dir) + swaps = [] + exclude_lines = [] + for md_from, md_to, rst_path, stem in planned: + rel_from = md_from.relative_to(docs_dir) + rel_to = md_to.relative_to(docs_dir) + rel_rst = rst_path.relative_to(docs_dir) + swaps.append({ + "stem": stem, + "md_from": str(rel_from), + "md_to": str(rel_to), + "rst_excluded": str(rel_rst), + }) + exclude_lines.append(str(rel_rst)) + + state = {"version": STATE_VERSION, "swaps": swaps} + state_path.write_text(json.dumps(state, indent=2), encoding="utf-8") + _exclude_path(docs_dir).write_text("\n".join(exclude_lines) + "\n", encoding="utf-8") + + print(f"swap_sources: swapped {len(completed)} file(s).", file=sys.stderr) + + +# --------------------------------------------------------------------------- +# do_restore +# --------------------------------------------------------------------------- + +def do_restore(docs_dir: Path) -> None: + """Undo all renames recorded in _swap_state.json (reverse order).""" + docs_dir = Path(docs_dir) + state_path = _state_path(docs_dir) + + if not state_path.exists(): + return # no-op + + try: + state = json.loads(state_path.read_text(encoding="utf-8")) + except (json.JSONDecodeError, OSError) as exc: + raise RuntimeError( + f"swap_sources: cannot read state file {state_path}: {exc}. " + f"Inspect or delete it manually." + ) from exc + + version = state.get("version") + if version != STATE_VERSION: + raise RuntimeError( + f"swap_sources: state file version {version!r} does not match " + f"expected {STATE_VERSION!r}. Inspect {state_path} manually." + ) + + swaps = state.get("swaps", []) + + for entry in reversed(swaps): + if not isinstance(entry, dict) or "md_from" not in entry or "md_to" not in entry: + raise RuntimeError( + f"swap_sources: malformed entry in {state_path}: {entry!r}. " + f"Inspect manually." + ) + md_from = docs_dir / entry["md_from"] # original source (md-prefixed) + md_to = docs_dir / entry["md_to"] # current location (plain .md) + if md_to.exists(): + os.rename(md_to, md_from) + else: + print( + f"swap_sources: WARNING — expected swapped file not found: {md_to}", + file=sys.stderr, + ) + + # Clean up state and exclude files + state_path.unlink(missing_ok=True) + exclude_path = _exclude_path(docs_dir) + exclude_path.unlink(missing_ok=True) + + print(f"swap_sources: restored {len(swaps)} file(s).", file=sys.stderr) + + +# --------------------------------------------------------------------------- +# do_dry_run / do_status +# --------------------------------------------------------------------------- + +def do_dry_run(docs_dir: Path) -> None: + """Print what would be swapped without making any changes.""" + docs_dir = Path(docs_dir) + swap_list = parse_swap_list(docs_dir / SWAP_LIST_FILE) + if not swap_list: + print("(dry-run) No stems in swap list.") + return + + for stem in swap_list: + md_from, md_to, rst_path = _resolve_stem_paths(docs_dir, stem) + issues = [] + if not md_from.exists(): + issues.append("md- source missing") + if not rst_path.exists(): + issues.append("RST missing") + if md_to.exists(): + issues.append("COLLISION: plain .md already exists") + if issues: + print(f" SKIP {stem}: {', '.join(issues)}") + else: + print(f" SWAP {md_from.name} → {md_to.name} (in {md_from.parent.relative_to(docs_dir) if md_from.parent != docs_dir else '.'})") + + +def do_status(docs_dir: Path) -> None: + """Show current swap state.""" + docs_dir = Path(docs_dir) + state_path = _state_path(docs_dir) + if not state_path.exists(): + print("swap_sources: no active swap state.") + return + + state = json.loads(state_path.read_text(encoding="utf-8")) + swaps = state.get("swaps", []) + print(f"swap_sources: {len(swaps)} file(s) currently swapped:") + for entry in swaps: + print(f" {entry['md_from']} → {entry['md_to']} (excludes {entry['rst_excluded']})") + + +# --------------------------------------------------------------------------- +# CLI +# --------------------------------------------------------------------------- + +def main(argv=None): + parser = argparse.ArgumentParser( + description="Swap md-prefixed MyST files in place of RST files before Sphinx builds." + ) + group = parser.add_mutually_exclusive_group(required=True) + group.add_argument("--swap", action="store_true", help="Perform swap") + group.add_argument("--restore", action="store_true", help="Restore original files") + group.add_argument("--dry-run", action="store_true", help="Show what would be swapped") + group.add_argument("--status", action="store_true", help="Show current swap state") + + parser.add_argument( + "--docs-dir", + type=Path, + default=None, + help="Path to docs/ directory (default: auto-detected from script location)", + ) + + args = parser.parse_args(argv) + + if args.docs_dir is None: + # Default: repo_root/docs where repo_root = parent of scripts/ + repo_root = Path(__file__).resolve().parent.parent + docs_dir = repo_root / "docs" + else: + docs_dir = args.docs_dir.resolve() + + if not docs_dir.is_dir(): + parser.error(f"docs directory not found: {docs_dir}") + + if args.swap: + do_swap(docs_dir) + elif args.restore: + do_restore(docs_dir) + elif args.dry_run: + do_dry_run(docs_dir) + elif args.status: + do_status(docs_dir) + + +if __name__ == "__main__": + main() diff --git a/tests/test_import_myst.py b/tests/test_import_myst.py new file mode 100644 index 00000000..1d975b45 --- /dev/null +++ b/tests/test_import_myst.py @@ -0,0 +1,101 @@ +"""Tests for import_myst.py — run with: + cd tests && PYTHONPATH=../scripts python3 -m pytest test_import_myst.py -v +""" +import warnings +from pathlib import Path + +import pytest + + +# --------------------------------------------------------------------------- +# import_page tests (no git dependency) +# --------------------------------------------------------------------------- + +def test_import_single_page(tmp_path): + """Creates md-{name}.md with the given content.""" + from import_myst import import_page + + docs = tmp_path / "docs" + docs.mkdir() + content = b"# quick-start\nHello MyST\n" + + result = import_page("quick-start", content, docs, force=False) + + assert result is True + dest = docs / "md-quick-start.md" + assert dest.exists() + assert dest.read_bytes() == content + + +def test_import_skip_identical(tmp_path): + """Returns False and does not modify the file when content is identical.""" + from import_myst import import_page + + docs = tmp_path / "docs" + docs.mkdir() + content = b"# quick-start\nIdentical content\n" + dest = docs / "md-quick-start.md" + dest.write_bytes(content) + mtime_before = dest.stat().st_mtime_ns + + result = import_page("quick-start", content, docs, force=False) + + assert result is False + assert dest.read_bytes() == content + assert dest.stat().st_mtime_ns == mtime_before + + +def test_import_warn_different_without_force(tmp_path): + """Returns False and keeps old content when content differs and force=False.""" + from import_myst import import_page + + docs = tmp_path / "docs" + docs.mkdir() + old_content = b"# old content\n" + new_content = b"# new content\n" + dest = docs / "md-quick-start.md" + dest.write_bytes(old_content) + + with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter("always") + result = import_page("quick-start", new_content, docs, force=False) + + assert result is False + assert dest.read_bytes() == old_content + assert len(caught) == 1 + assert "force" in str(caught[0].message).lower() + + +def test_import_overwrite_with_force(tmp_path): + """Returns True and writes new content when force=True.""" + from import_myst import import_page + + docs = tmp_path / "docs" + docs.mkdir() + old_content = b"# old content\n" + new_content = b"# new content\n" + dest = docs / "md-quick-start.md" + dest.write_bytes(old_content) + + result = import_page("quick-start", new_content, docs, force=True) + + assert result is True + assert dest.read_bytes() == new_content + + +def test_import_nested_path(tmp_path): + """Creates parent dirs and writes md-{name}.md in the correct nested location.""" + from import_myst import import_page + + docs = tmp_path / "docs" + docs.mkdir() + content = b"# zone\nFirewall zone docs\n" + + result = import_page("configuration/firewall/zone", content, docs, force=False) + + assert result is True + dest = docs / "configuration" / "firewall" / "md-zone.md" + assert dest.exists() + assert dest.read_bytes() == content + # Parent dirs were created + assert (docs / "configuration" / "firewall").is_dir() diff --git a/tests/test_swap_sources.py b/tests/test_swap_sources.py new file mode 100644 index 00000000..8576e056 --- /dev/null +++ b/tests/test_swap_sources.py @@ -0,0 +1,238 @@ +"""Tests for swap_sources.py — run with: + cd tests && PYTHONPATH=../scripts python -m pytest test_swap_sources.py -v +""" +import json +import os +import sys +from pathlib import Path + +import pytest + +# --------------------------------------------------------------------------- +# Helper +# --------------------------------------------------------------------------- + +def _setup_docs(tmp_path: Path, stems: list[str]) -> Path: + """Create a minimal docs/ tree with RST + md-prefixed MD files for each stem.""" + docs = tmp_path / "docs" + for stem in stems: + p = Path(stem) + name = p.name + parent = p.parent # may be "." for flat stems + target_dir = docs / parent if str(parent) != "." else docs + target_dir.mkdir(parents=True, exist_ok=True) + # RST file that would normally be the Sphinx source + (target_dir / f"{name}.rst").write_text(f".. _{name}:\n\nDummy RST for {stem}\n") + # md- prefixed MyST file waiting to be swapped in + (target_dir / f"md-{name}.md").write_text(f"# {name}\nDummy MyST for {stem}\n") + return docs + + +# --------------------------------------------------------------------------- +# parse_swap_list +# --------------------------------------------------------------------------- + +def test_parse_swap_list_basic(tmp_path): + from swap_sources import parse_swap_list + + swap_txt = tmp_path / "_swap.txt" + swap_txt.write_text( + "# comment\n" + "\n" + "configuration/firewall/zone\n" + " quick-start \n" # leading/trailing whitespace + "# another comment\n" + "installation/virtual/vmware\n" + ) + stems = parse_swap_list(swap_txt) + assert stems == [ + "configuration/firewall/zone", + "quick-start", + "installation/virtual/vmware", + ] + + +def test_parse_swap_list_empty(tmp_path): + from swap_sources import parse_swap_list + + missing = tmp_path / "_swap.txt" + assert parse_swap_list(missing) == [] + + +# --------------------------------------------------------------------------- +# do_swap +# --------------------------------------------------------------------------- + +def test_swap_renames_files(tmp_path): + from swap_sources import do_swap + + stems = ["quick-start"] + docs = _setup_docs(tmp_path, stems) + (tmp_path / "docs" / "_swap.txt").write_text("quick-start\n") + + do_swap(docs) + + assert (docs / "quick-start.md").exists(), "md- file should be renamed to plain .md" + assert not (docs / "md-quick-start.md").exists(), "md- prefix file should be gone" + assert (docs / "quick-start.rst").exists(), "RST file should still exist" + + +def test_swap_creates_state_file(tmp_path): + from swap_sources import do_swap + + stems = ["quick-start"] + docs = _setup_docs(tmp_path, stems) + (docs / "_swap.txt").write_text("quick-start\n") + + do_swap(docs) + + state_file = docs / "_build" / "_swap_state.json" + assert state_file.exists(), "state file should be created in _build/" + + state = json.loads(state_file.read_text()) + assert state["version"] == 1 + assert len(state["swaps"]) == 1 + + entry = state["swaps"][0] + assert entry["stem"] == "quick-start" + assert "md_from" in entry + assert "md_to" in entry + assert "rst_excluded" in entry + + +def test_swap_creates_exclude_file(tmp_path): + from swap_sources import do_swap + + stems = ["quick-start"] + docs = _setup_docs(tmp_path, stems) + (docs / "_swap.txt").write_text("quick-start\n") + + do_swap(docs) + + exclude_file = docs / "_build" / "_swap_exclude.txt" + assert exclude_file.exists(), "exclude file should be created in _build/" + + lines = [l.strip() for l in exclude_file.read_text().splitlines() if l.strip()] + assert "quick-start.rst" in lines + + +# --------------------------------------------------------------------------- +# do_restore +# --------------------------------------------------------------------------- + +def test_restore_undoes_renames(tmp_path): + from swap_sources import do_restore, do_swap + + stems = ["quick-start"] + docs = _setup_docs(tmp_path, stems) + (docs / "_swap.txt").write_text("quick-start\n") + + do_swap(docs) + assert (docs / "quick-start.md").exists() + + do_restore(docs) + + assert (docs / "md-quick-start.md").exists(), "md- prefix file should be restored" + assert not (docs / "quick-start.md").exists(), "plain .md should be gone after restore" + + state_file = docs / "_build" / "_swap_state.json" + exclude_file = docs / "_build" / "_swap_exclude.txt" + assert not state_file.exists(), "state file should be deleted after restore" + assert not exclude_file.exists(), "exclude file should be deleted after restore" + + +def test_restore_noop_without_state(tmp_path): + from swap_sources import do_restore + + docs = tmp_path / "docs" + docs.mkdir() + # Should not raise even with no state file + do_restore(docs) # no error = pass + + +# --------------------------------------------------------------------------- +# Collision / validation +# --------------------------------------------------------------------------- + +def test_swap_fails_on_collision(tmp_path): + from swap_sources import do_swap + + stems = ["quick-start", "cli"] + docs = _setup_docs(tmp_path, stems) + (docs / "_swap.txt").write_text("quick-start\ncli\n") + + # Simulate a collision: unprefixed .md already exists for "cli" + (docs / "cli.md").write_text("# collision\n") + + with pytest.raises(RuntimeError, match="collision"): + do_swap(docs) + + # Rollback: first stem's rename should be undone + assert (docs / "md-quick-start.md").exists(), "rollback should undo completed renames" + assert not (docs / "quick-start.md").exists(), "renamed file should not exist after rollback" + + # State file should NOT be written on failure + state_file = docs / "_build" / "_swap_state.json" + assert not state_file.exists(), "no state file should be written on failure" + + +# --------------------------------------------------------------------------- +# Rollback on rename failure (monkeypatched os.rename) +# --------------------------------------------------------------------------- + +def test_swap_rollback_on_rename_failure(tmp_path, monkeypatch): + """If os.rename raises on the second call, the first rename must be undone.""" + from swap_sources import do_swap + + stems = ["quick-start", "cli"] + docs = _setup_docs(tmp_path, stems) + (docs / "_swap.txt").write_text("quick-start\ncli\n") + + call_count = {"n": 0} + real_rename = os.rename + + def failing_rename(src, dst): + call_count["n"] += 1 + if call_count["n"] == 2: + raise OSError("simulated rename failure") + real_rename(src, dst) + + monkeypatch.setattr(os, "rename", failing_rename) + + with pytest.raises(RuntimeError): + do_swap(docs) + + # First rename (quick-start) should have been rolled back + assert (docs / "md-quick-start.md").exists(), "rollback should undo the first rename" + assert not (docs / "quick-start.md").exists(), "renamed file should not exist after rollback" + + # No state file should exist + assert not (docs / "_build" / "_swap_state.json").exists() + + +# --------------------------------------------------------------------------- +# Nested paths +# --------------------------------------------------------------------------- + +def test_swap_nested_paths(tmp_path): + from swap_sources import do_swap, do_restore + + stems = ["configuration/firewall/zone"] + docs = _setup_docs(tmp_path, stems) + (docs / "_swap.txt").write_text("configuration/firewall/zone\n") + + do_swap(docs) + + swapped = docs / "configuration" / "firewall" / "zone.md" + md_source = docs / "configuration" / "firewall" / "md-zone.md" + assert swapped.exists(), "nested md file should be renamed" + assert not md_source.exists() + + exclude_file = docs / "_build" / "_swap_exclude.txt" + lines = [l.strip() for l in exclude_file.read_text().splitlines() if l.strip()] + assert "configuration/firewall/zone.rst" in lines + + do_restore(docs) + + assert md_source.exists(), "nested md- file should be restored" + assert not swapped.exists() |
